refresh date: 2026-09-25 robots: noindex
说明
使用 chrome.webRequest API 观察和分析流量，以及拦截、屏蔽或修改传输中的请求。
权限
webRequest清单
您必须在扩展程序清单中声明 "webRequest" 权限，才能使用 Web 请求 API 以及必要的主机权限。如需拦截子资源请求，扩展程序必须有权访问请求的网址及其发起方。例如：
{
"name": "My extension",
...
"permissions": [
"webRequest"
],
"host_permissions": [
"*://*.google.com/*"
],
...
}
从 Chrome 108 开始，如果您使用 "webRequest" 和 "webRequestAuthProvider" 权限，则可以异步提供 onAuthRequired 事件的凭据。
请求的生命周期
Web 请求 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 不支持重定向和身份验证。
概念
如以下部分所述，Web 请求 API 中的事件使用请求 ID，您可以在注册事件监听器时选择性地指定过滤条件和额外信息。
请求 ID
每个请求都由一个请求 ID 标识。此 ID 在浏览器会话和扩展程序上下文中是唯一的。它在请求的生命周期内保持不变，可用于匹配同一请求的事件。请注意，在 HTTP 重定向或 HTTP 身份验证的情况下，多个 HTTP 请求会映射到一个 Web 请求。
注册事件监听器
如需为 Web 请求注册事件监听器，您可以使用常规 addListener() 函数的变体。除了指定回调函数之外，您还必须指定过滤条件参数，并且可以指定可选的额外信息参数。
Web 请求 API 的 addListener() 的三个实参具有以下定义：
var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];
以下是监听 onBeforeRequest 事件的示例：
chrome.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 中指定字符串，以请求有关请求的其他信息。仅在明确请求时，此字段才用于提供有关请求数据的详细信息。
实现细节
在开发使用 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 的所有请求：
chrome.webRequest.onBeforeRequest.addListener(
function(details) {
return {cancel: details.url.indexOf("://www.evil.com/") != -1};
},
{urls: ["<all_urls>"]},
["blocking"]
);
由于此函数使用阻塞事件处理脚本，因此需要在清单文件中具有 "webRequest" 以及 "webRequestBlocking" 权限。
以下示例以更高效的方式实现了相同的目标，因为未定位到 www.evil.com 的请求无需传递给扩展程序：
chrome.webRequest.onBeforeRequest.addListener(
function(details) { return {cancel: true}; },
{urls: ["*://www.evil.com/*"]},
["blocking"]
);
以下示例说明了如何从所有请求中删除 User-Agent 标头：
chrome.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"]
);
如需试用 chrome.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
包含在表单数据中传递的数据。对于 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
枚举
"redirect"
"request_headers"
"response_headers"
"auth_credentials"
OnAuthRequiredOptions
枚举
"responseHeaders"
指定应在事件中包含响应标头。
"blocking"
指定在回调函数返回之前阻止请求。
"asyncBlocking"
指定以异步方式处理回调函数。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnBeforeRedirectOptions
枚举
"responseHeaders"
指定应在事件中包含响应标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnBeforeRequestOptions
枚举
"blocking"
指定在回调函数返回之前阻止请求。
"requestBody"
指定应在事件中包含请求正文。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnBeforeSendHeadersOptions
枚举
"requestHeaders"
指定应在事件中包含请求标头。
"blocking"
指定在回调函数返回之前阻止请求。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnCompletedOptions
枚举
"responseHeaders"
指定应在事件中包含响应标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnErrorOccurredOptions
值
"extraHeaders"
OnHeadersReceivedOptions
枚举
"blocking"
指定在回调函数返回之前阻止请求。
"responseHeaders"
指定应在事件中包含响应标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
"securityInfo"
指定应在事件中包含 SecurityInfo。
"securityInfoRawDer"
指定事件中应包含具有证书原始字节的 SecurityInfo。
OnResponseStartedOptions
枚举
"responseHeaders"
指定应在事件中包含响应标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnSendHeadersOptions
枚举
"requestHeaders"
指定应在事件中包含请求标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
RequestFilter
一个对象，用于描述要应用于 webRequest 事件的过滤条件。
属性
-
tabId
number 可选
-
类型
ResourceType[] 可选
请求类型列表。系统会滤除与任何类型都不匹配的请求。
-
网址
字符串[]
网址或网址格式列表。无法与任何网址匹配的请求将被滤除。
-
windowId
number 可选
ResourceType
枚举
"main_frame"
将资源指定为主框架。
"sub_frame"
将资源指定为子框架。
"stylesheet"
将资源指定为样式表。
"script"
将资源指定为脚本。
"image"
将资源指定为图片。
"font"
将资源指定为字体。
"object"
将资源指定为对象。
"xmlhttprequest"
将资源指定为 XMLHttpRequest。
"ping"
将资源指定为 ping。
"csp_report"
将资源指定为内容安全政策 (CSP) 报告。
"media"
将资源指定为媒体对象。
"websocket"
将资源指定为 WebSocket。
"webbundle"
将资源指定为 WebBundle。
“其他”
指定资源类型不属于所列类型。
SecurityInfo
属性
-
证书
object[]
证书列表
-
指纹
对象
证书的指纹。
-
sha256
字符串
证书的 sha256 指纹。
-
-
rawDER
ArrayBuffer 可选
DER 编码服务器证书的原始字节
-
-
州
字符串
连接的状态。安全、不安全、损坏。
UploadData
包含在网址请求中上传的数据。
属性
-
字节
any 可选
包含数据副本的 ArrayBuffer。
-
文件
字符串 可选
包含文件路径和名称的字符串。
属性
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
在 10 分钟的持续时间间隔内，handlerBehaviorChanged 可调用的次数上限。handlerBehaviorChanged 是一个开销很大的函数调用，不应频繁调用。
值
20
方法
handlerBehaviorChanged()
chrome.webRequest.handlerBehaviorChanged(
callback?: function,
): Promise<void>
当 webRequest 处理程序的行为发生更改时，需要调用此方法，以防止因缓存而导致处理不正确。此函数调用开销很大。请勿频繁调用。
参数
-
callback
函数可选
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
事件
onActionIgnored
chrome.webRequest.onActionIgnored.addListener(
callback: function,
)
当扩展程序对网络请求的提议修改被忽略时触发。如果与其他扩展程序发生冲突，就会出现这种情况。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
action
被忽略的建议操作。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。
-
-
onAuthRequired
chrome.webRequest.onAuthRequired.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnAuthRequiredOptions[],
)
在收到身份验证失败时触发。监听器有三种选择：提供身份验证凭证、取消请求并显示错误页，或者不采取任何操作。如果提供了错误的用户凭据，则可能会针对同一请求多次调用此方法。请注意，在 extraInfoSpec 参数中只能指定 'blocking' 或 'asyncBlocking' 模式中的一种。
参数
-
callback
函数
callback参数如下所示：(details: object, asyncCallback?: function) => BlockingResponse | undefined
-
详细信息
对象
-
挑战者
对象
请求身份验证的服务器。
-
主机
字符串
-
端口
数值
-
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
isProxy
布尔值
如果为 Proxy-Authenticate，则为 true；如果为 WWW-Authenticate，则为 false。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。
-
parentFrameId
数值
封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。
-
大区
字符串 可选
服务器提供的身份验证领域（如果有）。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
与此响应一起收到的 HTTP 响应标头。
-
方案
字符串
身份验证方案，例如 Basic 或 Digest。
-
statusCode
数值
Chrome 43 及更高版本服务器返回的标准 HTTP 状态代码。
-
statusLine
字符串
响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串，或空字符串（如果没有标头）。
-
tabId
数值
发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。
-
timeStamp
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
asyncCallback
函数可选
Chrome 58 及更高版本asyncCallback参数如下所示：(response: BlockingResponse) => void
-
Response
-
-
返回
BlockingResponse | undefined
如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。
-
-
过滤条件
-
extraInfoSpec
onBeforeRedirect
chrome.webRequest.onBeforeRedirect.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRedirectOptions[],
)
在服务器发起的重定向即将发生时触发。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
fromCache
布尔值
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
ip
字符串 可选
请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 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
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
-
过滤条件
-
extraInfoSpec
onBeforeRequest
chrome.webRequest.onBeforeRequest.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRequestOptions[],
)
在即将发出请求时触发。
参数
-
callback
函数
callback参数如下所示：(details: object) => BlockingResponse | undefined
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 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
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
返回
BlockingResponse | undefined
如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。
-
-
过滤条件
-
extraInfoSpec
onBeforeSendHeaders
chrome.webRequest.onBeforeSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeSendHeadersOptions[],
)
在发送 HTTP 请求之前，一旦请求标头可用，就会触发。这可能发生在与服务器建立 TCP 连接之后，但在发送任何 HTTP 数据之前。
参数
-
callback
函数
callback参数如下所示：(details: object) => BlockingResponse | undefined
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。
-
parentFrameId
数值
封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。
-
requestHeaders
HttpHeaders 可选
将随此请求一起发送的 HTTP 请求标头。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。
-
tabId
数值
发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。
-
timeStamp
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
返回
BlockingResponse | undefined
如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。
-
-
过滤条件
-
extraInfoSpec
onCompleted
chrome.webRequest.onCompleted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnCompletedOptions[],
)
在请求完成时触发。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
fromCache
布尔值
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
ip
字符串 可选
请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 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
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
-
过滤条件
-
extraInfoSpec
OnCompletedOptions[] 可选
onErrorOccurred
chrome.webRequest.onErrorOccurred.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnErrorOccurredOptions[],
)
在发生错误时触发。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。如果请求是框架的导航，则此值不存在。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
错误
字符串
错误说明。此字符串不保证在不同版本之间保持向后兼容。您不得根据其内容进行解析和采取行动。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
fromCache
布尔值
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
ip
字符串 可选
请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。
-
parentFrameId
数值
封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。
-
tabId
数值
发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。
-
timeStamp
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
-
过滤条件
-
extraInfoSpec
onHeadersReceived
chrome.webRequest.onHeadersReceived.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnHeadersReceivedOptions[],
)
在收到请求的 HTTP 响应标头时触发。
参数
-
callback
函数
callback参数如下所示：(details: object) => BlockingResponse | undefined
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。
-
parentFrameId
数值
封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
此响应收到的 HTTP 响应标头。
-
securityInfo
SecurityInfo 可选
Chrome 144 及更高版本有关用于底层连接的 TLS/QUIC 连接的信息。仅在
extraInfoSpec参数中指定了securityInfo时提供。 -
statusCode
数值
Chrome 43 及更高版本服务器返回的标准 HTTP 状态代码。
-
statusLine
字符串
响应的 HTTP 状态行，或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串。
-
tabId
数值
发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。
-
timeStamp
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
返回
BlockingResponse | undefined
如果在“extraInfoSpec”参数中指定了“blocking”，则事件监听器应返回此类型的对象。
-
-
过滤条件
-
extraInfoSpec
onResponseStarted
chrome.webRequest.onResponseStarted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnResponseStartedOptions[],
)
在收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着状态行和响应标头可用。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
fromCache
布尔值
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
ip
字符串 可选
请求实际发送到的服务器 IP 地址。请注意，它可能是字面量 IPv6 地址。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 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
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
-
过滤条件
-
extraInfoSpec
onSendHeaders
chrome.webRequest.onSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnSendHeadersOptions[],
)
在请求即将发送到服务器之前触发（在触发 onSendHeaders 时，之前 onBeforeSendHeaders 回调的修改可见）。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串 可选
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
数值
值 0 表示请求发生在主框架中；正值表示请求发生的子框架的 ID。如果加载了（子）框架的文档（
type为main_frame或sub_frame），frameId表示此框架的 ID，而不是外部框架的 ID。框架 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的框架类型。
-
发起方
字符串 可选
Chrome 63 及更高版本发起请求的来源。此值不会因重定向而发生变化。如果这是不透明来源，则会使用字符串“null”。
-
方法
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串 可选
Chrome 106 及更高版本拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。
-
parentFrameId
数值
封装发送请求的框架的框架 ID。如果不存在父框架，则设置为 -1。
-
requestHeaders
HttpHeaders 可选
随此请求一起发送的 HTTP 请求标头。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。因此，它们可用于关联同一请求的不同事件。
-
tabId
数值
发出请求的标签页的 ID。如果请求与标签页无关，则设置为 -1。
-
timeStamp
数值
此信号的触发时间（以毫秒为单位，从纪元算起）。
-
类型
所请求资源的使用方式。
-
网址
字符串
-
-
-
过滤条件
-
extraInfoSpec
OnSendHeadersOptions[] 可选