browser.webRequest

说明

使用 chrome.webRequest API 观察和分析流量，以及拦截、屏蔽或修改传输中的请求。

权限

webRequest

您必须在扩展程序清单中声明 "webRequest" 权限，才能使用 Web 请求 API 以及必要的主机权限。如需拦截子资源请求，扩展程序必须有权访问请求的网址及其发起方。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

webRequestBlocking

注册阻塞事件处理脚本时必须提供。从 Manifest V3 开始，此功能仅适用于通过政策安装的扩展程序。

webRequestAuthProvider

必须使用 onAuthRequired 方法。请参阅处理身份验证。

概念和用法

请求的生命周期

Web 请求 API 定义了一组遵循 Web 请求生命周期的事件。您可以使用这些事件来观察和分析流量。某些同步事件允许您拦截、屏蔽或修改请求。

下图展示了成功请求的事件生命周期，后文提供了事件定义：

从 webrequest API 的角度来看，Web 请求的生命周期

onBeforeRequest（可选择同步）
在即将发出请求时触发。此事件在建立任何 TCP 连接之前发送，可用于取消或重定向请求。
onBeforeSendHeaders（可选择同步）
在即将发出请求且初始标头已准备就绪时触发。该事件旨在允许扩展程序添加、修改和删除请求标头 (*)。onBeforeSendHeaders 事件会传递给所有订阅者，因此不同的订阅者可能会尝试修改请求；如需了解如何处理这种情况，请参阅实现细节部分。此事件可用于取消请求。
onSendHeaders
在所有扩展程序都有机会修改请求标头后触发，并显示最终 (*) 版本。该事件会在标头发送到网络之前触发。此事件仅供参考，并以异步方式处理。不允许修改或取消请求。
onHeadersReceived（可选择同步）
每次收到 HTTP(S) 响应标头时触发。由于重定向和身份验证请求，每个请求可能会发生多次这种情况。此事件旨在允许扩展程序添加、修改和删除响应标头，例如传入的 Content-Type 标头。缓存指令会在触发此事件之前进行处理，因此修改 Cache-Control 等标头不会影响浏览器的缓存。它还允许您取消或重定向请求。
onAuthRequired（可选择同步）
当请求需要对用户进行身份验证时触发。此事件可以同步处理，以提供身份验证凭证。请注意，扩展程序可能会提供无效的凭据。请注意，不要因反复提供无效凭据而进入无限循环。这也可用于取消请求。
onBeforeRedirect
在即将执行重定向时触发。重定向可由 HTTP 响应代码或扩展程序触发。此事件仅供参考，并以异步方式处理。您无法修改或取消请求。
onResponseStarted
在收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着状态行和响应标头可用。此事件仅供参考，并以异步方式处理。但无法修改或取消请求。
onCompleted
在请求处理成功时触发。
onErrorOccurred
在无法成功处理请求时触发。

Web 请求 API 可保证对于每个请求，都会触发 onCompleted 或 onErrorOccurred 作为最终事件，但有一个例外：如果请求重定向到 data:// 网址，则 onBeforeRedirect 是最后报告的事件。

* 请注意，Web 请求 API 会向扩展程序呈现网络栈的抽象。 在内部，一个网址请求可以拆分为多个 HTTP 请求（例如，从大文件中提取单个字节范围），也可以由网络栈处理，而无需与网络通信。因此，该 API 不会提供发送到网络的最终 HTTP 标头。例如，扩展程序无法看到与缓存相关的所有标头。

目前，onBeforeSendHeaders 事件不提供以下标头。此列表不保证完整或稳定。

  • 授权
  • Cache-Control
  • 连接
  • Content-Length
  • 主机
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

从 Chrome 79 开始，请求标头修改会影响跨域资源共享 (CORS) 检查。如果跨域请求的已修改标头不符合条件，则会导致发送 CORS 预检，以询问服务器是否可以接受此类标头。如果您确实需要以违反 CORS 协议的方式修改标头，则需要在 opt_extraInfoSpec 中指定 'extraHeaders'。另一方面，响应标头修改无法欺骗 CORS 检查。如果您需要欺骗 CORS 协议，则还需要为响应修改指定 'extraHeaders'。

从 Chrome 79 开始，webRequest API 默认不会拦截 CORS 预检请求和响应。如果请求网址在 opt_extraInfoSpec 中指定了 'extraHeaders' 的监听器，则扩展程序可以看到该请求网址的 CORS 预检。onBeforeRequest 还可以从 Chrome 79 中获取 'extraHeaders'。

从 Chrome 79 开始，系统不提供以下请求标头，并且在未在 opt_extraInfoSpec 中指定 'extraHeaders' 的情况下，无法修改或移除该标头：

  • 来源

从 Chrome 72 开始，如果您需要在跨源读取阻止 (CORB) 阻止响应之前修改响应，则需要在 opt_extraInfoSpec 中指定 'extraHeaders'。

从 Chrome 72 开始，系统不提供以下请求标头，并且在未于 opt_extraInfoSpec 中指定 'extraHeaders' 的情况下，无法修改或移除这些标头：

  • Accept-Language
  • Accept-Encoding
  • Referer
  • Cookie

从 Chrome 72 开始，Set-Cookie 响应标头不会提供，并且在未指定 opt_extraInfoSpec 中的 'extraHeaders' 的情况下，无法修改或移除。

从 Chrome 89 开始，如果不指定 opt_extraInfoSpec 中的 'extraHeaders'，则无法有效修改或移除 X-Frame-Options 响应标头。

webRequest API 仅公开扩展程序有权查看的请求，具体取决于其主机权限。此外，只有以下 scheme 可供访问：http://、https://、ftp://、file://、ws://（自 Chrome 58 起）、wss://（自 Chrome 58 起）、urn:（自 Chrome 91 起）或 chrome-extension://。此外，即使某些请求的网址使用了上述某个架构，这些请求也会被隐藏。这些请求包括：chrome-extension://other_extension_id（其中 other_extension_id 不是要处理请求的扩展程序的 ID）、https://www.google.com/chrome，以及对浏览器功能至关重要的其他敏感请求。此外，来自扩展程序的同步 XMLHttpRequest 会对阻塞事件处理脚本隐藏，以防止死锁。请注意，对于某些受支持的架构，由于相应协议的性质，可用事件集可能会受到限制。例如，对于 file: 架构，只能分派 onBeforeRequest、onResponseStarted、onCompleted 和 onErrorOccurred。

从 Chrome 58 开始，webRequest API 支持拦截 WebSocket 握手请求。 由于握手是通过 HTTP 升级请求完成的，因此其流程符合面向 HTTP 的 webRequest 模型。请注意，该 API 不会拦截：

  • 通过已建立的 WebSocket 连接发送的单条消息。
  • WebSocket 正在关闭连接。

WebSocket 请求不支持重定向。

从 Chrome 72 开始，只有当扩展程序同时拥有所请求网址和请求发起方的主机权限时，才能拦截请求。

从 Chrome 96 开始，webRequest API 支持拦截基于 HTTP/3 的 WebTransport 握手请求。由于握手是通过 HTTP CONNECT 请求完成的，因此其流程符合面向 HTTP 的 webRequest 模型。请注意：

  • 会话建立后，扩展程序无法通过 webRequest API 观察或干预会话。
  • 系统会忽略在 onBeforeSendHeaders 中修改 HTTP 请求标头的操作。
  • 基于 HTTP/3 的 WebTransport 不支持重定向和身份验证。

请求 ID

每个请求都由一个请求 ID 标识。此 ID 在浏览器会话和扩展程序上下文中是唯一的。它在请求的生命周期内保持不变，可用于匹配同一请求的事件。请注意，在 HTTP 重定向或 HTTP 身份验证的情况下，多个 HTTP 请求会映射到一个 Web 请求。

注册事件监听器

如需为 Web 请求注册事件监听器，您可以使用常规 addListener() 函数的变体。除了指定回调函数之外，您还必须指定过滤条件参数，并且可以指定可选的额外信息参数。

Web 请求 API 的 addListener() 的三个实参具有以下定义：

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

以下是监听 onBeforeRequest 事件的示例：

browser.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

每次 addListener() 调用都将一个强制性回调函数作为第一个参数。系统会向此回调函数传递一个包含当前网址请求相关信息的字典。此字典中的信息取决于特定事件类型以及 opt_extraInfoSpec 的内容。

如果可选的 opt_extraInfoSpec 数组包含字符串 'blocking'（仅允许用于特定事件），则系统会同步处理回调函数。这意味着，在回调函数返回之前，请求会被阻止。在这种情况下，回调可以返回一个 webRequest.BlockingResponse，用于确定请求的后续生命周期。根据上下文，此响应允许取消或重定向请求 (onBeforeRequest)、取消请求或修改标头（onBeforeSendHeaders、onHeadersReceived），以及取消请求或提供身份验证凭证 (onAuthRequired)。

如果可选的 opt_extraInfoSpec 数组改为包含字符串 'asyncBlocking'（仅允许用于 onAuthRequired），则扩展程序可以异步生成 webRequest.BlockingResponse。

webRequest.RequestFilter filter 允许在各个维度中限制触发事件的请求：

网址
网址格式，例如 *://www.google.com/foo*bar。
类型
请求类型，例如 main_frame（为顶级框架加载的文档）、sub_frame（为嵌入式框架加载的文档）和 image（网站上的图片）。请参阅 webRequest.RequestFilter。
标签 ID
一个标签页的标识符。
窗口 ID
窗口的标识符。

根据事件类型，您可以在 opt_extraInfoSpec 中指定字符串，以请求有关请求的其他信息。仅在明确请求时，此字段才用于提供有关请求数据的详细信息。

处理身份验证

如需处理 HTTP 身份验证请求，请向清单文件添加 "webRequestAuthProvider" 权限：

{
  "permissions": [
    "webRequest",
    "webRequestAuthProvider"
  ]
}

请注意，对于具有 "webRequestBlocking" 权限的政策安装扩展程序，不需要此权限。

如需同步提供凭据，请执行以下操作：

browser.webRequest.onAuthRequired.addListener((details) => {
    return {
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    };
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['blocking']
);

如需异步提供凭证，请执行以下操作：

browser.webRequest.onAuthRequired.addListener((details, callback) => {
    callback({
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    });
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['asyncBlocking']
);

实现细节

在开发使用 Web 请求 API 的扩展程序时，可能需要了解一些重要的实现细节：

web_accessible_resources

如果扩展程序使用 webRequest API 将公共资源请求重定向到无法通过网络访问的资源，则该请求会被屏蔽，并会导致错误。即使无法通过网络访问的资源归重定向扩展程序所有，上述情况也同样适用。如需声明要与 declarativeWebRequest API 搭配使用的资源，必须在清单中声明并填充 "web_accessible_resources" 数组，如此处所述。

冲突解决

在 Web 请求 API 的当前实现中，如果至少有一个扩展程序指示取消请求，则该请求会被视为已取消。如果某个扩展程序取消了请求，所有扩展程序都会收到 onErrorOccurred 事件通知。一次只能有一个扩展程序重定向请求或修改标头。如果多个扩展程序尝试修改请求，则最近安装的扩展程序会生效，而所有其他扩展程序都会被忽略。如果扩展程序的修改或重定向指令被忽略，扩展程序不会收到通知。

缓存

Chrome 采用两种缓存：磁盘缓存和速度极快的内存缓存。内存缓存的生命周期与渲染进程的生命周期相关联，而渲染进程大致对应于一个标签页。 Web 请求 API 无法看到从内存缓存中应答的请求。如果请求处理程序更改了其行为（例如，根据哪些请求被屏蔽的行为），简单的页面刷新可能不会遵循此更改后的行为。为确保行为变更生效，请调用 handlerBehaviorChanged() 以刷新内存缓存。但不要经常这样做；刷新缓存是一项非常耗费资源的操作。注册或取消注册事件监听器后，您无需调用 handlerBehaviorChanged()。

时间戳

Web 请求事件的 timestamp 属性仅保证内部一致。将一个事件与另一个事件进行比较，可以得出它们之间的正确偏移量，但将它们与扩展程序内的当前时间进行比较（例如，通过 (new Date()).getTime()）可能会产生意外结果。

错误处理

如果您尝试使用无效参数注册事件，系统会抛出 JavaScript 错误，并且不会注册事件处理脚本。如果在处理事件时抛出错误，或者事件处理脚本返回无效的屏蔽响应，系统会将出错提示记录到扩展程序的控制台中，并且该请求会忽略该处理脚本。

示例

以下示例说明了如何屏蔽对 www.evil.com 的所有请求：

browser.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

由于此函数使用阻塞事件处理脚本，因此需要在清单文件中具有 "webRequest" 以及 "webRequestBlocking" 权限。

以下示例以更高效的方式实现了相同的目标，因为未定位到 www.evil.com 的请求无需传递给扩展程序：

browser.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

以下示例说明了如何从所有请求中删除 User-Agent 标头：

browser.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

如需试用 browser.webRequest API，请从 chrome-extension-samples 代码库中安装 webRequest 示例。

类型

BlockingResponse

为应用了“blocking”extraInfoSpec 的事件处理脚本返回值。允许事件处理脚本修改网络请求。

属性

  • authCredentials

    对象（可选）

    仅用作对 onAuthRequired 事件的响应。如果设置，则使用提供的凭据发出请求。

    • 密码

      字符串

    • username

      字符串

  • 取消

    布尔值 （可选）

    如果为 true，则请求会被取消。这样可以防止发送请求。这可用作对 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件的响应。

  • redirectUrl

    字符串 可选

    仅用作对 onBeforeRequest 和 onHeadersReceived 事件的响应。如果设置了此参数，系统会阻止发送/完成原始请求，而是将其重定向到指定网址。允许重定向到非 HTTP 架构（例如 data:）。由重定向操作发起的重定向会使用原始请求方法进行重定向，但有一个例外：如果重定向是在 onHeadersReceived 阶段发起的，则系统会使用 GET 方法发出重定向。系统会忽略从采用 ws:// 和 wss:// 架构的网址进行的重定向。

  • requestHeaders

    HttpHeaders 可选

    仅用作对 onBeforeSendHeaders 事件的响应。如果设置了此字段，则系统会改用这些请求标头发出请求。

  • responseHeaders

    HttpHeaders 可选

    仅用作对 onHeadersReceived 事件的响应。如果设置了此字段，系统会假定服务器已使用这些响应标头进行响应。只有在您确实想要修改标头时，才返回 responseHeaders，以限制冲突数量（每个请求只能有一个扩展程序修改 responseHeaders）。

FormDataItem

Chrome 66 及更高版本 browser.*（自 Chrome 148 起）

包含在表单数据中传递的数据。对于 urlencoded 表单，如果数据是 utf-8 字符串，则存储为字符串，否则存储为 ArrayBuffer。对于表单数据，它是 ArrayBuffer。如果表单数据表示上传文件，则它是包含文件名的字符串（如果提供了文件名）。

枚举

ArrayBuffer

字符串

HttpHeaders

HTTP 标头数组。每个标头都表示为一个字典，其中包含键 name 以及 value 或 binaryValue。

类型

object[]

属性

  • binaryValue

    number[] 可选

    如果 HTTP 标头的值无法用 UTF-8 表示，则存储为单个字节值 (0..255)。

  • name

    字符串

    HTTP 标头的名称。

  • 值

    字符串 可选

    HTTP 标头的值（如果可以用 UTF-8 表示）。

IgnoredActionType

Chrome 70 及更高版本 browser.*（自 Chrome 148 起）

枚举

"redirect"

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"responseHeaders"
指定应在事件中包含响应标头。

"blocking"
指定在回调函数返回之前阻止请求。

"asyncBlocking"
指定以异步方式处理回调函数。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

OnBeforeRedirectOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"responseHeaders"
指定应在事件中包含响应标头。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

OnBeforeRequestOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"blocking"
指定在回调函数返回之前阻止请求。

"requestBody"
指定应在事件中包含请求正文。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

OnBeforeSendHeadersOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"requestHeaders"
指定应在事件中包含请求标头。

"blocking"
指定在回调函数返回之前阻止请求。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

OnCompletedOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"responseHeaders"
指定应在事件中包含响应标头。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

OnErrorOccurredOptions

Chrome 79 及更高版本 browser.*（自 Chrome 148 起）

值

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"blocking"
指定在回调函数返回之前阻止请求。

"responseHeaders"
指定应在事件中包含响应标头。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

"securityInfo"
指定应在事件中包含 SecurityInfo。

"securityInfoRawDer"
指定事件中应包含具有证书原始字节的 SecurityInfo。

OnResponseStartedOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"responseHeaders"
指定应在事件中包含响应标头。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

OnSendHeadersOptions

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"requestHeaders"
指定应在事件中包含请求标头。

"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。

RequestFilter

一个对象，用于描述要应用于 webRequest 事件的过滤条件。

属性

  • tabId

    number 可选

  • 类型

    ResourceType[] 可选

    请求类型列表。系统会滤除与任何类型都不匹配的请求。

  • 网址

    字符串[]

    网址或网址格式列表。无法与任何网址匹配的请求将被滤除。

  • windowId

    number 可选

ResourceType

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"main_frame"
将资源指定为主框架。

"sub_frame"
将资源指定为子框架。

"stylesheet"
将资源指定为样式表。

"script"
将资源指定为脚本。

"image"
将资源指定为图片。

"font"
将资源指定为字体。

"object"
将资源指定为对象。

"xmlhttprequest"
将资源指定为 XMLHttpRequest。

"ping"
将资源指定为 ping。

"csp_report"
将资源指定为内容安全政策 (CSP) 报告。

"media"
将资源指定为媒体对象。

"websocket"
将资源指定为 WebSocket。

"webbundle"
将资源指定为 WebBundle。

“其他”
指定资源类型不属于所列类型。

SecurityInfo

Chrome 144 及更高版本 browser.*（自 Chrome 148 起）

属性

  • 证书

    object[]

    证书列表

    • 指纹

      对象

      证书的指纹。

      • sha256

        字符串

        证书的 sha256 指纹。

    • rawDER

      ArrayBuffer 可选

      DER 编码服务器证书的原始字节

  • 州

    字符串

    连接的状态。安全、不安全、损坏。

UploadData

包含在网址请求中上传的数据。

属性

  • 字节

    any 可选

    包含数据副本的 ArrayBuffer。

  • 文件

    字符串 可选

    包含文件路径和名称的字符串。

属性

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

在 10 分钟的持续时间间隔内，handlerBehaviorChanged 可调用的次数上限。handlerBehaviorChanged 是一个开销很大的函数调用，不应频繁调用。

值

20

方法

handlerBehaviorChanged()

browser.webRequest.handlerBehaviorChanged(): Promise<void>

当 webRequest 处理程序的行为发生更改时，需要调用此方法，以防止因缓存而导致处理不正确。此函数调用开销很大。请勿频繁调用。

返回

  • 承诺<void>

    Chrome 116 及更高版本 browser.*（自 Chrome 148 起）

事件

onActionIgnored

Chrome 70 及更高版本 browser.*（自 Chrome 148 起） 
browser.webRequest.onActionIgnored.addListener(
  callback: function,
)

当扩展程序对网络请求的提议修改被忽略时触发。如果与其他扩展程序发生冲突，就会出现这种情况。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • 被忽略的建议操作。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

onAuthRequired

browser.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

在收到身份验证失败时触发。监听器有三种选择：提供身份验证凭证、取消请求并显示错误页，或者不采取任何操作。如果提供了错误的用户凭据，则可能会针对同一请求多次调用此方法。请注意，在 extraInfoSpec 参数中只能指定 'blocking' 或 'asyncBlocking' 模式中的一种。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object, asyncCallback?: function) => BlockingResponse | undefined

    • 详细信息

      对象

      • 挑战者

        对象

        请求身份验证的服务器。

        • 主机

          字符串

        • 端口

          数值

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • isProxy

        布尔值

        如果为 Proxy-Authenticate，则为 true；如果为 WWW-Authenticate，则为 false。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • 大区

        字符串 可选

        服务器提供的身份验证领域（如果有）。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • responseHeaders

        HttpHeaders 可选

        与此响应一起收到的 HTTP 响应标头。

      • 方案

        字符串

        身份验证方案，例如 Basic 或 Digest。

      • statusCode

        数值

        Chrome 43 及更高版本 Chrome 148 及更高版本中的 browser.*

        服务器返回的标准 HTTP 状态代码。

      • statusLine

        字符串

        响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串，或空字符串（如果没有标头）。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

    • asyncCallback

      函数可选

      Chrome 58 及更高版本 browser.*（自 Chrome 148 起）

      asyncCallback 参数如下所示： 

      (response: BlockingResponse) => void

    • 返回

      BlockingResponse | undefined

      如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] 可选

onBeforeRedirect

browser.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

在服务器发起的重定向即将发生时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • fromCache

        布尔值

        指示此响应是否是从磁盘缓存中提取的。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • ip

        字符串 可选

        请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • redirectUrl

        字符串

        新网址。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • responseHeaders

        HttpHeaders 可选

        与此重定向一起收到的 HTTP 响应标头。

      • statusCode

        数值

        服务器返回的标准 HTTP 状态代码。

      • statusLine

        字符串

        响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串，或空字符串（如果没有标头）。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] 可选

onBeforeRequest

browser.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

在即将发出请求时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => BlockingResponse | undefined

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • documentLifecycle

        extensionTypes.DocumentLifecycle 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • frameType

        extensionTypes.FrameType 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestBody

        对象（可选）

        包含 HTTP 请求正文数据。仅在 extraInfoSpec 包含“requestBody”时提供。

        • 错误

          字符串 可选

          获取请求正文数据时出错。

        • formData

          对象（可选）

          如果请求方法为 POST，且正文是采用 UTF8 编码的键值对序列（编码为 multipart/form-data 或 application/x-www-form-urlencoded），则此字典存在，并且对于每个键，都包含该键的所有值的列表。如果数据属于其他媒体类型，或者格式不正确，则字典不存在。此字典的值示例为 {'key': ['value1', 'value2']}。

        • raw

          UploadData[] 可选

          如果请求方法为 PUT 或 POST，并且正文尚未在 formData 中解析，则未解析的请求正文元素将包含在此数组中。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

    • 返回

      BlockingResponse | undefined

      如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] 可选

onBeforeSendHeaders

browser.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

在发送 HTTP 请求之前，一旦请求标头可用，就会触发。这可能发生在与服务器建立 TCP 连接之后，但在发送任何 HTTP 数据之前。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => BlockingResponse | undefined

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestHeaders

        HttpHeaders 可选

        将随此请求一起发送的 HTTP 请求标头。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

    • 返回

      BlockingResponse | undefined

      如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] 可选

onCompleted

browser.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

在请求完成时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • fromCache

        布尔值

        指示此响应是否是从磁盘缓存中提取的。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • ip

        字符串 可选

        请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • responseHeaders

        HttpHeaders 可选

        与此响应一起收到的 HTTP 响应标头。

      • statusCode

        数值

        服务器返回的标准 HTTP 状态代码。

      • statusLine

        字符串

        响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串，或空字符串（如果没有标头）。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] 可选

onErrorOccurred

browser.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

在发生错误时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。如果请求是框架的导航，则此值不存在。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • 错误

        字符串

        错误说明。此字符串不保证在不同版本之间保持向后兼容。您不得根据其内容进行解析和采取行动。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • fromCache

        布尔值

        指示此响应是否是从磁盘缓存中提取的。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • ip

        字符串 可选

        请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] 可选

onHeadersReceived

browser.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

在收到请求的 HTTP 响应标头时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => BlockingResponse | undefined

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • responseHeaders

        HttpHeaders 可选

        此响应收到的 HTTP 响应标头。

      • securityInfo

        SecurityInfo 可选

        Chrome 144 及更高版本 browser.*（自 Chrome 148 起）

        有关用于底层连接的 TLS/QUIC 连接的信息。仅在 extraInfoSpec 参数中指定了 securityInfo 时提供。

      • statusCode

        数值

        Chrome 43 及更高版本 Chrome 148 及更高版本中的 browser.*

        服务器返回的标准 HTTP 状态代码。

      • statusLine

        字符串

        响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

    • 返回

      BlockingResponse | undefined

      如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] 可选

onResponseStarted

browser.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

在收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着状态行和响应标头可用。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • fromCache

        布尔值

        指示此响应是否是从磁盘缓存中提取的。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • ip

        字符串 可选

        请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • responseHeaders

        HttpHeaders 可选

        与此响应一起收到的 HTTP 响应标头。

      • statusCode

        数值

        服务器返回的标准 HTTP 状态代码。

      • statusLine

        字符串

        响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串，或空字符串（如果没有标头）。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] 可选

onSendHeaders

browser.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

在请求即将发送到服务器之前触发（在触发 onSendHeaders 时，之前 onBeforeSendHeaders 回调的修改可见）。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        发出请求的文档的 UUID。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        文档所处的生命周期。

      • frameId

        数值

        值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。

      • Chrome 106+ browser.*（自 Chrome 148 起）

        发生请求的框架类型。

      • 发起方

        字符串 可选

        Chrome 63 及更高版本 browser.*（自 Chrome 148 起）

        发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。

      • 方法

        字符串

        标准 HTTP 方法。

      • parentDocumentId

        字符串 可选

        Chrome 106+ browser.*（自 Chrome 148 起）

        拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

      • parentFrameId

        数值

        封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。

      • requestHeaders

        HttpHeaders 可选

        随此请求一起发送的 HTTP 请求标头。

      • requestId

        字符串

        请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。

      • tabId

        数值

        发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。

      • timeStamp

        数值

        此信号的触发时间（以毫秒为单位，从纪元算起）。

      • 类型

        ResourceType

        所请求资源的使用方式。

      • 网址

        字符串

  • 过滤条件

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] 可选