webRequest

为 HTTP 请求的各个阶段添加事件监听器，包括 ws:// 和 wss:// 上的 WebSocket 请求。事件监听器会接收有关请求的详细信息，并可以修改或取消请求。

每个事件在请求的特定阶段触发。事件顺序如下：

Order of requests is onBeforeRequest, onBeforeSendHeader, onSendHeaders, onHeadersReceived, onResponseStarted, and onCompleted. The onHeadersReceived can cause an onBeforeRedirect and an onAuthRequired. Events caused by onHeadersReceived start at the beginning onBeforeRequest. Events caused by onAuthRequired start at onBeforeSendHeader.

但是，扩展程序并非一定会观察到所有这些事件。例如，当重定向目标不匹配事件 filter.urls 时，onBeforeRedirect 可能不会紧接着 onBeforeRequest 触发。这可能是因为过滤器中的 URL 定义得很窄，或者扩展程序无法观察到重定向目标，例如当它重定向到 data: URL 时。

onErrorOccurred 可以在请求期间的任何时间触发。另外请注意，事件顺序有时可能与此不同。例如，在 Firefox 中，对于 HSTS 升级，onBeforeRedirect 事件会在 onBeforeRequest 之后立即触发。如果 Firefox 跟踪保护阻止了某个请求，也会触发 onErrorOccurred。

所有事件——除了 onErrorOccurred——都可以接受三个参数给 addListener()：

监听器本身
一个 filter 对象，因此您只能接收到特定 URL 或特定类型资源的请求通知。
一个可选的 extraInfoSpec 对象。您可以使用它来传递其他事件特定的指令。

监听器函数会接收一个包含请求信息的 details 对象。其中包括一个请求 ID，该 ID 用于使附加组件能够关联与单个请求相关的事件。它在浏览器会话和附加组件的上下文中是唯一的。在整个请求过程中，即使在重定向和身份验证交换过程中，它也会保持不变。

要为给定主机使用 webRequest API，扩展程序必须具有 "webRequest" API 权限以及该主机的主机权限。要使用 "blocking" 功能，扩展程序还必须拥有 "webRequestBlocking" API 权限。

要拦截由页面加载的资源（如图像、脚本或样式表），扩展程序必须同时拥有该资源的权限以及请求该资源的主页面的主机权限。例如，如果一个位于 https://mdn.org.cn 的页面从 https://mdn.mozillademos.org 加载图像，那么扩展程序必须同时拥有这两个主机权限才能拦截图像请求。

修改请求

在某些事件中，您可以修改请求。具体来说，您可以：

在以下情况下取消请求：
在以下情况下重定向请求：
- onBeforeRequest
- onHeadersReceived
在以下情况下修改请求头：
- onBeforeSendHeaders
在以下情况下修改响应头：
- onHeadersReceived
在以下情况下提供身份验证凭据：
- onAuthRequired

要执行此操作，您需要向事件的 addListener() 的 extraInfoSpec 参数中传递一个值为 "blocking" 的选项。这将使监听器变为同步。

在监听器中，您可以返回一个 BlockingResponse 对象，该对象指示您需要进行的修改：例如，您想要发送的已修改的请求头。

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: 发生错误时触发。