1. Mozilla
  2. 附加组件
  3. 浏览器扩展
  4. JavaScript API
  5. webRequest
  6. webRequest.onBeforeSendHeaders

webRequest.onBeforeSendHeaders

此事件在发送任何 HTTP 数据之前触发，但在所有 HTTP 头都可用之后。如果您想修改 HTTP 请求头，这是一个很好的监听位置。

要让请求头与其余请求数据一起传递给监听器，请在 extraInfoSpec 数组中传递 "requestHeaders"。

要同步修改请求头：在 extraInfoSpec 中传递 "blocking"，然后在您的事件监听器中，返回一个带有名为 requestHeaders 属性的 BlockingResponse，其值是要发送的请求头集合。

要异步修改请求头：在 extraInfoSpec 中传递 "blocking"，然后在您的事件监听器中，返回一个用 BlockingResponse 解析的 Promise。

如果您使用 "blocking"，则您的 manifest.json 中必须具有 "webRequestBlocking" API 权限。

此处可能会出现扩展冲突。如果两个扩展为同一请求监听 onBeforeSendHeaders，则第二个监听器将看到第一个监听器所做的修改，并且能够撤销第一个监听器所做的任何更改。例如，如果第一个监听器添加一个 Cookie 头，而第二个监听器移除所有 Cookie 头，则第一个监听器的修改将丢失。如果您想查看实际发送的头，而不冒其他扩展随后更改它们的风险，请使用 onSendHeaders，尽管您无法在此事件中修改头。

并非所有实际发送的头都始终包含在 requestHeaders 中。特别是，与缓存相关的头（例如，Cache-Control、If-Modified-Since、If-None-Match）从不发送。此外，此处的行为可能因浏览器而异。

根据规范，头名称不区分大小写。这意味着为了匹配特定的头，监听器在比较之前应该将名称转换为小写。

js
for (const header of e.requestHeaders) {
  if (header.name.toLowerCase() === desiredHeader) {
    // process header
  }
}

浏览器保留由浏览器生成的头名称的原始大小写。如果扩展的监听器更改了大小写，此更改将不会保留。

语法

js
browser.webRequest.onBeforeSendHeaders.addListener(
  listener,             //  function
  filter,               //  object
  extraInfoSpec         //  optional array of strings
)
browser.webRequest.onBeforeSendHeaders.removeListener(listener)
browser.webRequest.onBeforeSendHeaders.hasListener(listener)

事件有三个函数

addListener(listener, filter, extraInfoSpec)

向此事件添加监听器。

removeListener(listener)

停止监听此事件。listener 参数是要移除的监听器。

hasListener(listener)

检查 listener 是否已为此事件注册。如果正在监听，则返回 true，否则返回 false。

addListener 语法

参数

监听器

当此事件发生时调用的函数。该函数将传递此参数

details

object。请求的详细信息。如果您在 extraInfoSpec 中包含了 "requestHeaders"，则此信息包括请求头。有关更多信息，请参阅详细信息部分。

返回：webRequest.BlockingResponse。如果 extraInfoSpec 参数中指定了 "blocking"，则事件监听器应返回一个 BlockingResponse 对象，并可以设置其 requestHeaders 属性。

filter

webRequest.RequestFilter。一组过滤器，用于限制发送到此监听器的事件。

extraInfoSpec 可选

string 数组。事件的额外选项。您可以传递以下任何值

  • "blocking"：使请求同步，以便您可以修改请求头。
  • "requestHeaders"：将请求头包含在传递给监听器的 details 对象中。

额外对象

details

cookieStoreId

string。如果请求来自上下文身份中打开的标签页，则为上下文身份的 cookie 存储 ID。有关更多信息，请参阅使用上下文身份。

documentUrl

string。资源将加载到的文档的 URL。例如，如果“https://example.com”上的网页包含图像或 iframe，则图像或 iframe 的 documentUrl 将是“https://example.com”。对于顶级文档，documentUrl 未定义。

frameAncestors

array。包含帧层次结构中每个文档的信息，直到顶层文档。数组中的第一个元素包含有关所请求文档的直接父级的信息，最后一个元素包含有关顶层文档的信息。如果加载实际上是针对顶层文档，则此数组为空。

url

string。文档加载来源的 URL。

frameId

integer。文档的 frameId。details.frameAncestors[0].frameId 与 details.parentFrameId 相同。

frameId

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

incognito

boolean。请求是否来自隐私浏览窗口。

method（方法）

string。标准 HTTP 方法：例如，“GET”或“POST”。

originUrl

string。触发请求的资源的 URL。例如，如果“https://example.com”包含一个链接，并且用户点击该链接，则生成请求的 originUrl 为“https://example.com”。

originUrl 通常但不总是与 documentUrl 相同。例如，如果一个页面包含一个 iframe，并且 iframe 包含一个将新文档加载到 iframe 中的链接，则生成请求的 documentUrl 将是 iframe 的父文档，但 originUrl 将是包含链接的 iframe 中文档的 URL。

parentFrameId

integer。包含发送请求的帧的父帧的 ID。如果没有父帧，则设置为 -1。

proxyInfo

object。此属性仅在请求通过代理时存在。它包含以下属性：

主机

string。代理服务器的主机名。

port

integer。代理服务器的端口号。

type

string。代理服务器的类型。以下之一：

  • "http"：HTTP 代理（或 HTTPS 的 SSL CONNECT）
  • "https"：通过 TLS 连接到代理的 HTTP 代理
  • "socks"：SOCKS v5 代理
  • "socks4"：SOCKS v4 代理
  • "direct"：无代理
  • "unknown"：未知代理
username

string。代理服务的用户名。

proxyDNS

boolean。如果代理将根据提供的主机名执行域名解析，这意味着客户端不应自行进行 DNS 查找，则为 True。

failoverTimeout

integer。故障转移超时（秒）。如果代理连接失败，在此期间将不再使用该代理。

requestHeaders 可选

webRequest.HttpHeaders。将与此请求一起发送的 HTTP 请求头。

requestId

string。请求的 ID。请求 ID 在浏览器会话中是唯一的，因此您可以使用它们来关联与同一请求相关的不同事件。

tabId

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

thirdParty

boolean。指示请求及其内容窗口层次结构是否是第三方。

timeStamp

number。此事件触发的时间，以纪元以来的毫秒数表示。

type

webRequest.ResourceType。正在请求的资源类型：例如，“image”、“script”、“stylesheet”。

url

string。请求的目标。

urlClassification

object。如果请求被Firefox 跟踪保护分类，则与请求关联的跟踪类型。这是一个包含以下属性的对象：

firstParty

array 类型的 string。请求的第一方分类标志。

thirdParty

array 类型的 string。请求或其窗口层次结构的第三方分类标志。

分类标志包括：

  • fingerprinting 和 fingerprinting_content：表示请求涉及指纹识别（“发现指纹识别的来源”）。
    • fingerprinting 表示该域属于指纹识别和跟踪类别。此类域的示例包括希望将配置文件与访问用户关联的广告商。
    • fingerprinting_content 表示该域属于指纹识别类别但不属于跟踪类别。此类域的示例包括使用指纹识别技术识别访问用户以进行反欺诈目的的支付提供商。
  • cryptomining 和 cryptomining_content：类似于指纹识别类别，但用于加密挖矿资源。
  • tracking、tracking_ad、tracking_analytics、tracking_social 和 tracking_content：表示请求涉及跟踪。tracking 是任何通用跟踪请求，ad、analytics、social 和 content 后缀标识跟踪器的类型。
  • emailtracking 和 emailtracking_content：表示请求涉及跟踪电子邮件。
  • any_basic_tracking：一个元标志，结合了跟踪和指纹识别标志，不包括 tracking_content 和 fingerprinting_content。
  • any_strict_tracking：一个元标志，结合了所有跟踪和指纹识别标志。
  • any_social_tracking：一个元标志，结合了所有社交跟踪标志。

您可以在 disconnect.me 网站上找到有关跟踪器类型的更多信息。content 后缀表示跟踪并提供内容的跟踪器。阻止它们可以保护用户，但也可能导致网站损坏或元素无法显示。

示例

此代码更改“User-Agent”头，使浏览器将自身标识为 Opera 12.16，但仅当访问 https://httpbin.org/ 下的页面时。

js
"use strict";

/*
This is the page for which we want to rewrite the User-Agent header.
*/
const targetPage = "https://httpbin.org/*";

/*
Set UA string to Opera 12
*/
const ua =
  "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16";

/*
Rewrite the User-Agent header to "ua".
*/
function rewriteUserAgentHeader(e) {
  for (const header of e.requestHeaders) {
    if (header.name.toLowerCase() === "user-agent") {
      header.value = ua;
    }
  }
  return { requestHeaders: e.requestHeaders };
}

/*
Add rewriteUserAgentHeader as a listener to onBeforeSendHeaders,
only for the target page.

Make it "blocking" so we can modify the headers.
*/
browser.webRequest.onBeforeSendHeaders.addListener(
  rewriteUserAgentHeader,
  { urls: [targetPage] },
  ["blocking", "requestHeaders"],
);

此代码与上一个示例完全相同，只是监听器是异步的，返回一个用新头解析的 Promise。

js
"use strict";

/*
This is the page for which we want to rewrite the User-Agent header.
*/
const targetPage = "https://httpbin.org/*";

/*
Set UA string to Opera 12
*/
const ua =
  "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16";

/*
Rewrite the User-Agent header to "ua".
*/
function rewriteUserAgentHeaderAsync(e) {
  const asyncRewrite = new Promise((resolve, reject) => {
    setTimeout(() => {
      for (const header of e.requestHeaders) {
        if (header.name.toLowerCase() === "user-agent") {
          header.value = ua;
        }
      }
      resolve({ requestHeaders: e.requestHeaders });
    }, 2000);
  });

  return asyncRewrite;
}

/*
Add rewriteUserAgentHeader as a listener to onBeforeSendHeaders,
only for the target page.

Make it "blocking" so we can modify the headers.
*/
browser.webRequest.onBeforeSendHeaders.addListener(
  rewriteUserAgentHeaderAsync,
  { urls: [targetPage] },
  ["blocking", "requestHeaders"],
);

扩展程序示例

浏览器兼容性

注意：此 API 基于 Chromium 的 chrome.webRequest API。此文档来源于 Chromium 代码中的 web_request.json。

帮助改进 MDN

了解如何贡献

此页面最后修改于 ，由 MDN 贡献者完成。

在 GitHub 上查看此页面 • 报告此内容存在的问题
© . Content available under a Creative Commons license.