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.