webRequest
为发出 HTTP 请求的不同阶段添加事件侦听器，其中包括 ws:// 和 wss:// 上的 websocket 请求。事件侦听器接收有关请求的详细信息，并且可以修改或取消请求。
每个事件在请求的特定阶段触发。事件的顺序如下所示
但是，扩展可能无法观察到所有这些事件。例如，当重定向目标与事件 filter.urls 不匹配时，onBeforeRedirect 之后可能不会接着是 onBeforeRequest。这可能是因为过滤器中的 URL 定义过于狭窄，或者扩展无法观察到重定向目标，例如当它重定向到 data: URL 时。
onErrorOccurred 可以在请求期间的任何时间触发。此外，请注意，有时事件的顺序可能与此不同。例如，在 Firefox 中，在 HSTS 升级时，onBeforeRedirect 事件会在 onBeforeRequest 之后立即触发。如果 Firefox 跟踪保护 阻止了请求，也会触发 onErrorOccurred。
所有事件（除了 onErrorOccurred）都可以将三个参数传递给 addListener()
- 侦听器本身
- 一个
filter对象，这样您就可以只在对特定 URL 或特定类型资源发出的请求时收到通知 - 一个可选的
extraInfoSpec对象。您可以使用它来传递其他特定于事件的指令。
侦听器函数会传递一个 details 对象，其中包含有关请求的信息。这包括请求 ID，它用于使附加组件能够关联与单个请求相关的事件。它在一个浏览器会话和附加组件的上下文中是唯一的。即使在重定向和身份验证交换过程中，它也保持不变。
要对给定主机使用 webRequest API，扩展必须具有 "webRequest" API 权限 和该主机的 主机权限。要使用 "blocking" 功能，扩展还必须具有 "webRequestBlocking" API 权限。
要拦截页面加载的资源（例如图像、脚本或样式表），扩展必须具有资源的主机权限以及请求资源的主页的主机权限。例如，如果 https://mdn.org.cn 上的页面从 https://mdn.mozillademos.org 加载图像，则如果要拦截图像请求，扩展必须同时具有这两个主机权限。
修改请求
在某些事件中，您可以修改请求。具体来说，您可以
- 在中取消请求
- 在中重定向请求
- 在中修改请求头
- 在中修改响应头
- 在中提供身份验证凭据
为此，您需要在事件的 addListener() 中的 extraInfoSpec 参数中传递一个值为 "blocking" 的选项。这使得侦听器成为同步的。
然后，在侦听器中，您可以返回一个 BlockingResponse 对象，该对象指示您需要进行的修改：例如，您要发送的修改后的请求头。
浏览器启动时的请求
当使用 "blocking" 选项注册侦听器并在扩展启动期间注册侦听器时，如果在浏览器启动期间发出了与侦听器匹配的请求，则扩展会提前启动。这使扩展能够在浏览器启动时观察请求。如果不执行这些步骤，则可能会错过在启动时发出的请求。
推测性请求
浏览器可以建立推测性连接，它会确定对 URI 的请求可能很快就会到来。这种类型的连接不提供有效的选项卡信息，因此请求详细信息（如 tabId、frameId、parentFrameId 等）不准确。这些连接具有 webRequest.ResourceType 为 speculative。
访问安全信息
在 onHeadersReceived 侦听器中，您可以通过调用 getSecurityInfo() 来访问请求的 TLS 属性。为此，您还必须在事件的 addListener() 中的 extraInfoSpec 参数中传递“blocking”。
您可以读取 TLS 握手的详细信息，但不能修改它们或覆盖浏览器的信任决策。
修改响应
要修改请求的 HTTP 响应主体，请调用 webRequest.filterResponseData，并向其传递请求的 ID。这将返回一个 webRequest.StreamFilter 对象，您可以使用它来检查和修改浏览器接收到的数据。
为此，您必须具有 "webRequestBlocking" API 权限以及相关的 "webRequest" API 权限 和 主机权限。
类型
webRequest.BlockingResponse-
此类型的对象由在
extraInfoSpec参数中设置了"blocking"的事件侦听器返回。通过在BlockingResponse中设置特定属性，侦听器可以修改网络请求。 webRequest.CertificateInfo-
描述单个 X.509 证书的对象。
webRequest.HttpHeaders-
HTTP 标头的数组。每个标头都表示为一个对象，该对象具有两个属性：
name和value或binaryValue。 webRequest.RequestFilter-
描述要应用于
webRequest事件的过滤器的对象。 webRequest.ResourceType-
表示在 Web 请求中获取的特定类型的资源。
webRequest.SecurityInfo-
描述特定 Web 请求的安全属性的对象。
webRequest.StreamFilter-
一个对象，可用于在接收 HTTP 响应时监视和修改它们。
webRequest.UploadData-
包含在 URL 请求中上传的数据。
属性
webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES-
在 10 分钟内可以调用
handlerBehaviorChanged()的最大次数。
方法
webRequest.handlerBehaviorChanged()-
此方法可用于确保在页面位于浏览器内存缓存中时事件侦听器能够正确应用。
webRequest.filterResponseData()-
为给定请求返回一个
webRequest.StreamFilter对象。 webRequest.getSecurityInfo()-
获取与给定请求关联的TLS连接的详细信息。
事件
webRequest.onBeforeRequest-
在发出请求且标题可用之前触发。如果要取消或重定向请求，这是一个很好的监听位置。
webRequest.onBeforeSendHeaders-
在发送任何 HTTP 数据之前但 HTTP 标题可用后触发。如果要修改 HTTP 请求标头，这是一个很好的监听位置。
webRequest.onSendHeaders-
在发送标头之前触发。如果您的附加组件或其他附加组件在
onBeforeSendHeaders webRequest.onHeadersReceived-
在接收到与请求关联的 HTTP 响应标头时触发。您可以使用此事件修改 HTTP 响应标头。
webRequest.onAuthRequired-
当服务器要求客户端提供身份验证凭据时触发。侦听器可以不执行任何操作、取消请求或提供身份验证凭据。
webRequest.onResponseStarted-
在接收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着状态行和响应标头可用。
webRequest.onBeforeRedirect-
在服务器发起的重定向即将发生时触发。
webRequest.onCompleted-
在请求完成时触发。
webRequest.onErrorOccurred-
发生错误时触发。
浏览器兼容性
BCD 表格仅在浏览器中加载
示例扩展
注意：此 API 基于 Chromium 的chrome.webRequest API。本文档源自 Chromium 代码中的web_request.json。