webRequest.onHeadersReceived

當請求的 HTTP 響應頭被接收時觸發。使用此事件修改 HTTP 響應頭。

要使響應頭與請求資料的其餘部分一起傳遞給監聽器，請在 extraInfoSpec 陣列中傳遞 "responseHeaders"。

如果您使用 "blocking"，則您的 manifest.json 中必須具有 "webRequestBlocking" API 許可權。

擴充套件程式可能會發出衝突的請求。如果兩個擴充套件程式針對同一個請求監聽 onHeadersReceived 並返回 responseHeaders 來設定原始響應中不存在的相同頭（例如，Set-Cookie），則只有其中一個更改會成功。

但是，Content-Security-Policy 頭被區別對待；其值會被組合起來應用所有指定的策略。但如果兩個擴充套件程式設定的 CSP 值衝突，CSP 服務會使限制更嚴格以解決衝突。例如，如果一個擴充套件程式設定 img-src: example.com，而另一個擴充套件程式設定 img-src: example.org，則結果是 img-src: 'none'。合併的修改總是傾向於更嚴格，儘管擴充套件程式可以刪除原始 CSP 頭。

如果你想檢視系統處理的頭，而沒有其他擴充套件程式更改它們的風險，請使用 webRequest.onResponseStarted，儘管你無法在此事件上修改頭。

語法

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

事件有三個函式

addListener(listener, filter, extraInfoSpec): 向此事件新增監聽器。
removeListener(listener): 停止監聽此事件。listener 引數是要移除的監聽器。
hasListener(listener): 檢查 listener 是否已為此事件註冊。如果正在監聽，則返回 true，否則返回 false。

addListener 語法

引數

監聽器

當此事件發生時呼叫的函式。該函式將傳遞此引數

details: object。請求的詳細資訊。如果你在 extraInfoSpec 中包含了 "responseHeaders"，這將包含響應頭。

返回：webRequest.BlockingResponse。如果在 extraInfoSpec 引數中指定了 "blocking"，則事件監聽器將返回一個 BlockingResponse 物件，並且可以設定其 responseHeaders 屬性。在 Firefox 中，返回值可以是一個解析為 BlockingResponse 的 Promise。

filter

webRequest.RequestFilter。一組過濾器，用於限制傳送到此監聽器的事件。

extraInfoSpec 可選

string 陣列。事件的額外選項。您可以傳遞以下任何值

"blocking" 使請求同步，以便你可以修改請求和響應頭
"responseHeaders" 將響應頭包含在傳遞給監聽器的 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 在一個標籤頁內是唯一的。

fromCache

boolean。響應是否從磁碟快取中獲取。

incognito

boolean。請求是否來自隱私瀏覽視窗。

ip

string。傳送請求的伺服器的 IP 地址。它可能是一個 IPv6 字面地址。

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。故障轉移超時（秒）。如果代理連線失敗，在此期間將不再使用該代理。

requestId

string。請求的 ID。請求 ID 在瀏覽器會話中是唯一的，因此您可以使用它們來關聯與同一請求相關的不同事件。

responseHeaders 可選

webRequest.HttpHeaders。此請求接收到的 HTTP 響應頭。

statusCode

integer。伺服器返回的標準 HTTP 狀態碼。

statusLine

string。響應的 HTTP 狀態行，或 HTTP/0.9 響應（即缺少狀態行的響應）的“HTTP/0.9 200 OK”字串。

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 字尾表示跟蹤並提供內容的跟蹤器。阻止它們可以保護使用者，但也可能導致網站損壞或元素無法顯示。

示例

此程式碼在從目標 URL 請求資源時設定一個額外的 cookie

let targetPage =
  "https://mdn.club.tw/en-US/Firefox/Developer_Edition";

// Add the new header to the original array,
// and return it.
function setCookie(e) {
  const setMyCookie = {
    name: "Set-Cookie",
    value: "my-cookie1=my-cookie-value1",
  };
  e.responseHeaders.push(setMyCookie);
  return { responseHeaders: e.responseHeaders };
}

// Listen for onHeaderReceived for the target page.
// Set "blocking" and "responseHeaders".
browser.webRequest.onHeadersReceived.addListener(
  setCookie,
  { urls: [targetPage] },
  ["blocking", "responseHeaders"],
);

此程式碼執行與上一個示例相同的事情，只是監聽器是非同步的，返回一個用新頭解析的 Promise

const targetPage =
  "https://mdn.club.tw/en-US/Firefox/Developer_Edition";

// Return a Promise that sets a timer.
// When the timer fires, resolve the promise with
// modified set of response headers.
function setCookieAsync(e) {
  const asyncSetCookie = new Promise((resolve, reject) => {
    setTimeout(() => {
      const setMyCookie = {
        name: "Set-Cookie",
        value: "my-cookie1=my-cookie-value1",
      };
      e.responseHeaders.push(setMyCookie);
      resolve({ responseHeaders: e.responseHeaders });
    }, 2000);
  });

  return asyncSetCookie;
}

// Listen for onHeaderReceived for the target page.
// Set "blocking" and "responseHeaders".
browser.webRequest.onHeadersReceived.addListener(
  setCookieAsync,
  { urls: [targetPage] },
  ["blocking", "responseHeaders"],
);

瀏覽器相容性

注意：此 API 基於 Chromium 的 chrome.webRequest API。本文件源自 Chromium 程式碼中的 web_request.json。

幫助改進 MDN

瞭解如何貢獻

本頁面由 MDN 貢獻者在 2025 年 7 月 17 日最後修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題