说明
使用 chrome.webRequest API 可以观察和分析流量，以及拦截、屏蔽或修改运行中的请求。
权限
webRequest您必须在扩展程序清单中声明 "webRequest" 权限，才能使用 Web 请求 API 以及必要的主机权限。如需拦截子资源请求，扩展程序必须能访问请求的网址及其发起者。例如：
{
"name": "My extension",
...
"permissions": [
"webRequest"
],
"host_permissions": [
"*://*.google.com/*"
],
...
}
webRequestBlocking
注册屏蔽事件处理脚本时必填。从 Manifest V3 开始，此功能仅适用于通过政策安装的扩展程序。
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
- 部分数据
- 普拉格玛
- 代理授权
- 代理连接
- 传输编码
从 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-Encoding
- Referer
- Cookie
从 Chrome 72 开始，Set-Cookie 响应标头不再提供。如果没有在 opt_extraInfoSpec 中指定 'extraHeaders'，便无法修改或删除标头。
从 Chrome 89 开始，如果没有在 opt_extraInfoSpec 中指定 'extraHeaders'，则无法有效修改或删除 X-Frame-Options 响应标头。
webRequest API 仅公开扩展程序有权查看的请求（给定其主机权限）。此外，只能使用以下架构：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 请求标头。 - WebTransport over HTTP/3 不支持重定向和身份验证。
请求 ID
每个请求均由请求 ID 进行标识。此 ID 在浏览器会话和扩展程序的上下文中是唯一的。该值在请求的生命周期内保持不变，可用于匹配同一请求的事件。请注意，如果发生 HTTP 重定向或 HTTP 身份验证，系统会将多个 HTTP 请求映射到一个 Web 请求。
注册事件监听器
如需为网络请求注册事件监听器，您可以使用常规 addListener() 函数的变体。除了指定回调函数外，您还必须指定过滤器参数，并且可以指定可选的 extra info 参数。
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 中指定字符串，以请求有关请求的其他信息。此字段仅用于在明确请求的情况下提供有关请求数据的详细信息。
处理身份验证
如需处理 HTTP 身份验证请求，请向清单文件添加 "webRequestAuthProvider" 权限：
{
"permissions": [
"webRequest",
"webRequestAuthProvider"
]
}
请注意，具有 "webRequestBlocking" 权限的政策安装的扩展程序不需要此权限。
如需同步提供凭据，请执行以下操作：
chrome.webRequest.onAuthRequired.addListener((details) => {
return {
authCredentials: {
username: 'guest',
password: 'guest'
}
};
},
{ urls: ['https://httpbin.org/basic-auth/guest/guest'] },
['blocking']
);
如需异步提供凭据，请执行以下操作：
chrome.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 将公共资源请求重定向到无法通过 Web 访问的资源时，相应扩展程序会被屏蔽并引发错误。即使无法通过网络访问的资源归重定向扩展程序所有，上述情况仍适用。如需声明用于声明式 WebRequest API 的资源，必须在清单中声明并填充 "web_accessible_resources" 数组，如此处所述。
冲突解决
在 Web 请求 API 的当前实现中，如果至少一个扩展程序指示取消请求，则相应请求会被视为已取消。如果扩展程序取消了请求，则所有扩展程序都会收到 onErrorOccurred 事件通知。一次只能重定向请求或修改标头。如果有多个扩展程序尝试修改请求，系统会优先选择最新安装的扩展程序，并忽略所有其他扩展程序。如果扩展程序的修改或重定向指令被忽略，则不会收到通知。
缓存
Chrome 使用了两种缓存：磁盘缓存和超快内存缓存。内存中缓存的生命周期与渲染进程的生命周期相关联，大致对应于标签页的生命周期。从内存缓存中应答的请求对 Web 请求 API 不可见。如果请求处理程序更改其行为（例如，阻止请求的行为），简单的页面刷新可能不会遵循这一更改后的行为。为了确保行为变更生效，请调用 handlerBehaviorChanged() 以刷新内存中的缓存。但请不要经常这样做；刷新缓存是一项成本很高的操作。注册或取消注册事件监听器后，您无需调用 handlerBehaviorChanged()。
时间戳
仅保证网站请求事件的 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 事件的响应。如果设置了此字段，则使用提供的凭据发出请求。
-
密码
string
-
用户名
string
-
-
取消
布尔值 选填
如果为 true，则会取消请求。这样可以阻止发送请求。此 API 可用作对 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件的响应。
-
redirectUrl
字符串（可选）
仅用作对 onBeforeRequest 和 onHeadersReceived 事件的响应。如果设置了此字段，则系统将阻止发送/完成原始请求，而会重定向到给定的网址。允许重定向到非 HTTP 协议方案（例如
data:）。由重定向操作发起的重定向使用重定向的原始请求方法，但有一个例外：如果在 onHeadersReceived 阶段启动重定向，则将使用 GET 方法发出重定向。忽略采用ws://和wss://架构的网址的重定向。 -
requestHeaders
HttpHeaders 可选
仅用于对 onBeforeSendHeaders 事件的响应。如果设置了此字段，则改为使用这些请求标头发出请求。
-
responseHeaders
HttpHeaders 可选
仅用于响应 onHeadersReceived 事件。如果设置了此字段，系统会假定服务器已使用这些响应标头进行响应。只有在您确实想要修改标头以限制冲突数量（只有一个扩展程序可以修改每个请求的
responseHeaders）时，才会返回responseHeaders。
FormDataItem
包含在表单数据中传递的数据。对于网址编码形式，如果数据为 UTF-8 字符串，则存储为字符串，否则存储为 ArrayBuffer。对于表单数据，类型是 ArrayBuffer。如果 form-data 表示上传文件，则它是包含文件名的字符串（如果提供了文件名）。
枚举
ArrayBuffer
string
HttpHeaders
HTTP 标头数组。每个标头都表示为一个包含键 name 以及 value 或 binaryValue 的字典。
类型
对象 []
属性
-
binaryValue
number[] 选填
HTTP 标头的值（如果无法用 UTF-8 表示），存储为各个字节值 (0..255)。
-
name
string
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)。
OnResponseStartedOptions
枚举
"responseHeaders"
指定应包含在事件中的响应标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
OnSendHeadersOptions
枚举
"requestHeaders"
指定应在事件中包含请求标头。
"extraHeaders"
指定标头可以违反跨域资源共享 (CORS)。
RequestFilter
一个对象，用于描述要应用于 webRequest 事件的过滤条件。
属性
-
tabId
数字可选
-
种类
ResourceType[] 可选
请求类型的列表。与任何类型都不匹配的请求将被滤除。
-
urls
字符串[]
网址或网址格式的列表。与任何网址都不匹配的请求将被滤除。
-
windowId
数字可选
ResourceType
枚举
"main_frame"
将资源指定为主框架。
"sub_frame"
将资源指定为子帧。
"stylesheet"
将资源指定为样式表。
"script"
以脚本形式指定资源。
"image"
将资源指定为图片。
"font"
将资源指定为字体。
"object"
将资源指定为对象。
"xmlhttprequest"
将资源指定为 XMLHttpRequest。
"ping"
将资源指定为 ping。
"csp_report"
将资源指定为内容安全政策 (CSP) 报告。
"media"
将资源指定为媒体对象。
"websocket"
将资源指定为 WebSocket。
"webbundle"
将资源指定为 WebBundle。
"other"
将资源指定为未包含在所列类型中的类型。
UploadData
包含通过网址请求上传的数据。
属性
-
字节
任意（可选）
包含数据副本的 ArrayBuffer。
-
文件
字符串（可选）
包含文件的路径和名称的字符串。
属性
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
每 10 分钟的持续时间间隔可以调用 handlerBehaviorChanged 的最大次数。handlerBehaviorChanged 是一个成本高昂的函数调用，不应经常调用。
值
20
方法
handlerBehaviorChanged()
chrome.webRequest.handlerBehaviorChanged(
callback?: function,
)
在 webRequest 处理程序的行为发生更改时需要调用，以防止由于缓存而导致处理错误。此函数调用的开销很大。不要经常调用它。
参数
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Chrome 116 及更高版本Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
活动
onActionIgnored
chrome.webRequest.onActionIgnored.addListener(
callback: function,
)
扩展程序建议的网络修改被忽略时触发。当与其他扩展程序发生冲突时，就会发生这种情况。
参数
-
callback
功能
callback参数如下所示：(details: object)=>void
-
明细
对象
-
action
被忽略的建议操作。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
-
onAuthRequired
chrome.webRequest.onAuthRequired.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnAuthRequiredOptions[],
)
收到身份验证失败时触发。该监听器有三个选项：可提供身份验证凭据、取消请求并显示错误页面，或者不对验证执行任何操作。如果提供了错误的用户凭据，系统可能会针对同一请求多次调用该方法。请注意，在 extraInfoSpec 参数中只能指定 'blocking' 或 'asyncBlocking' 模式之一。
参数
-
callback
功能
callback参数如下所示：(details: object,asyncCallback?: function)=>BlockingResponse|undefined
-
明细
对象
-
挑战者
对象
请求身份验证的服务器。
-
主办方
string
-
端口
number
-
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
isProxy
boolean
true 表示代理身份验证，false 表示 WWW 身份验证。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
大区
字符串（可选）
服务器提供的身份验证领域（如果有）。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
随此响应一起收到的 HTTP 响应标头。
-
方案
string
身份验证方案，例如基本或摘要。
-
statusCode
number
Chrome 43 及更高版本服务器返回的标准 HTTP 状态代码。
-
statusLine
string
响应的 HTTP 状态行或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串；如果没有标头，则返回空字符串。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
asyncCallback
函数（可选）
Chrome 58 及更高版本asyncCallback参数如下所示：(response: BlockingResponse)=>void
-
条回复
-
-
返回
BlockingResponse|未定义
如果在“extraInfoSpec”参数中指定了“blocking”，事件监听器应返回此类型的对象。
-
-
filter
-
extraInfoSpec
onBeforeRedirect
chrome.webRequest.onBeforeRedirect.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRedirectOptions[],
)
在即将发生服务器发起的重定向时触发。
参数
-
callback
功能
callback参数如下所示：(details: object)=>void
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
fromCache
boolean
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
ip
字符串（可选）
请求实际发送到的服务器 IP 地址。请注意，它可能是字面 IPv6 地址。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
redirectUrl
string
新网址。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
随此重定向一起收到的 HTTP 响应标头。
-
statusCode
number
服务器返回的标准 HTTP 状态代码。
-
statusLine
string
响应的 HTTP 状态行或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串；如果没有标头，则返回空字符串。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
-
filter
-
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
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestBody
对象（可选）
包含 HTTP 请求正文数据。仅当 extraInfoSpec 包含“requestBody”时提供。
-
error
字符串（可选）
获取请求正文数据时出错。
-
formData
对象（可选）
如果请求方法是 POST，且正文是以 UTF8 编码的键值对序列（编码为 multipart/form-data 或 application/x-www-form-urlencoded），则会显示此字典，并为每个键提供该键的所有值的列表。如果数据属于其他媒体类型，或者格式有误，则字典不存在。此字典的示例值是 {'key': ['value1', 'value2']}。
-
原始
UploadData[] 可选
如果请求方法是 PUT 或 POST，并且正文尚未在 formData 中进行解析，则未解析的请求正文元素会包含在此数组中。
-
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
返回
BlockingResponse|未定义
如果在“extraInfoSpec”参数中指定了“blocking”，事件监听器应返回此类型的对象。
-
-
filter
-
extraInfoSpec
onBeforeSendHeaders
chrome.webRequest.onBeforeSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeSendHeadersOptions[],
)
在请求标头可用后，在发送 HTTP 请求之前触发。这种情况可能会在 TCP 连接到服务器之后、发送任何 HTTP 数据之前发生。
参数
-
callback
功能
callback参数如下所示：(details: object)=>BlockingResponse|undefined
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestHeaders
HttpHeaders 可选
将随此请求一起发送的 HTTP 请求标头。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
返回
BlockingResponse|未定义
如果在“extraInfoSpec”参数中指定了“blocking”，事件监听器应返回此类型的对象。
-
-
filter
-
extraInfoSpec
onCompleted
chrome.webRequest.onCompleted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnCompletedOptions[],
)
完成请求时触发。
参数
-
callback
功能
callback参数如下所示：(details: object)=>void
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
fromCache
boolean
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
ip
字符串（可选）
请求实际发送到的服务器 IP 地址。请注意，它可能是字面 IPv6 地址。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
随此响应一起收到的 HTTP 响应标头。
-
statusCode
number
服务器返回的标准 HTTP 状态代码。
-
statusLine
string
响应的 HTTP 状态行或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串；如果没有标头，则返回空字符串。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
-
filter
-
extraInfoSpec
OnCompletedOptions[] 可选
onErrorOccurred
chrome.webRequest.onErrorOccurred.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnErrorOccurredOptions[],
)
发生错误时触发。
参数
-
callback
功能
callback参数如下所示：(details: object)=>void
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。如果请求是帧的导航，则此值不存在。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
error
string
错误说明。此字符串不保证在各版本之间保持向后兼容性。您不得根据其内容解析和执行操作。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
fromCache
boolean
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
ip
字符串（可选）
请求实际发送到的服务器 IP 地址。请注意，它可能是字面 IPv6 地址。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
-
filter
-
extraInfoSpec
onHeadersReceived
chrome.webRequest.onHeadersReceived.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnHeadersReceivedOptions[],
)
在收到请求的 HTTP 响应标头时触发。
参数
-
callback
功能
callback参数如下所示：(details: object)=>BlockingResponse|undefined
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
通过此响应收到的 HTTP 响应标头。
-
statusCode
number
Chrome 43 及更高版本服务器返回的标准 HTTP 状态代码。
-
statusLine
string
响应的 HTTP 状态行或 HTTP/0.9 响应的“HTTP/0.9 200 OK”字符串（即缺少状态行的响应）。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
返回
BlockingResponse|未定义
如果在“extraInfoSpec”参数中指定了“blocking”，事件监听器应返回此类型的对象。
-
-
filter
-
extraInfoSpec
onResponseStarted
chrome.webRequest.onResponseStarted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnResponseStartedOptions[],
)
在收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着可以使用状态行和响应标头。
参数
-
callback
功能
callback参数如下所示：(details: object)=>void
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
fromCache
boolean
指示此响应是否是从磁盘缓存中提取的。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
ip
字符串（可选）
请求实际发送到的服务器 IP 地址。请注意，它可能是字面 IPv6 地址。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
responseHeaders
HttpHeaders 可选
随此响应一起收到的 HTTP 响应标头。
-
statusCode
number
服务器返回的标准 HTTP 状态代码。
-
statusLine
string
响应的 HTTP 状态行或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串；如果没有标头，则返回空字符串。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
-
filter
-
extraInfoSpec
onSendHeaders
chrome.webRequest.onSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnSendHeadersOptions[],
)
在请求即将发送到服务器之前触发（在触发 onSendHeaders 时，可以看到对以前的 onBeforeSendHeaders 回调的修改）。
参数
-
callback
功能
callback参数如下所示：(details: object)=>void
-
明细
对象
-
documentId
string
Chrome 106 及更高版本发出请求的文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（
type为main_frame或sub_frame），则frameId表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameTypeChrome 106 及更高版本
发生请求的帧类型。
-
发起方
字符串（可选）
Chrome 63 及更高版本发起请求的来源。这一点不会因重定向而改变。如果这是一个不透明来源，将使用字符串“null”。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。
-
requestHeaders
HttpHeaders 可选
随此请求一起发送的 HTTP 请求标头。
-
requestId
string
请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。
-
timeStamp
number
此信号触发的时间（以毫秒为单位，从 Epoch 起算）。
-
类型
将如何使用请求的资源。
-
网址
string
-
-
-
filter
-
extraInfoSpec
OnSendHeadersOptions[] 可选