refresh date: 2026-09-25 robots: noindex
說明
使用 chrome.webRequest API 觀察及分析流量，並攔截、封鎖或修改傳輸中的要求。
權限
webRequest資訊清單
您必須在擴充功能資訊清單中宣告 "webRequest" 權限，才能使用網頁要求 API，以及必要的主機權限。如要攔截子資源要求，擴充功能必須能存取要求的網址和發起端。例如：
{
"name": "My extension",
...
"permissions": [
"webRequest"
],
"host_permissions": [
"*://*.google.com/*"
],
...
}
自 Chrome 108 起，如果您使用 "webRequest" 和 "webRequestAuthProvider" 權限，可以非同步提供 onAuthRequired 事件的憑證。
要求的生命週期
網頁要求 API 定義了一組事件，這些事件會遵循網頁要求的生命週期。您可以使用這些事件來觀察及分析流量。某些同步事件可讓您攔截、封鎖或修改要求。
下圖說明成功要求的事件生命週期，後續則為事件定義：
onBeforeRequest(可選擇同步)- 即將提出請求時觸發。這個事件會在建立任何 TCP 連線前傳送，可用於取消或重新導向要求。
onBeforeSendHeaders(可選擇同步)- 在即將發出要求且初始標頭已準備就緒時觸發。這個事件旨在允許擴充功能新增、修改及刪除要求標頭 (*)。
onBeforeSendHeaders事件會傳遞給所有訂閱者，因此不同的訂閱者可能會嘗試修改要求；請參閱「實作詳細資料」一節，瞭解如何處理這項作業。這個事件可用於取消要求。 onSendHeaders- 在所有擴充功能都有機會修改要求標頭後觸發，並顯示最終 (*) 版本。系統會在標頭傳送至網路前觸發事件。這項事件僅供參考，且會以非同步方式處理。但無法修改或取消要求。
onHeadersReceived(可選擇同步)- 每次收到 HTTP(S) 回應標頭時觸發。由於重新導向和驗證要求，每個要求可能會發生多次。這個事件可讓擴充功能新增、修改及刪除回應標頭，例如傳入的 Content-Type 標頭。快取指令會在觸發這個事件前處理，因此修改 Cache-Control 等標頭不會影響瀏覽器的快取。此外，您也可以取消或重新導向要求。
onAuthRequired(可選擇同步)- 當要求需要驗證使用者時，就會觸發這個事件。您可以同步處理這個事件，提供驗證憑證。請注意，擴充功能可能會提供無效的憑證。請注意，不要重複提供無效憑證，以免進入無限迴圈。這項功能也可用來取消要求。
onBeforeRedirect- 在即將執行重新導向時觸發。重新導向可由 HTTP 回應代碼或擴充功能觸發。這類事件僅供參考，且會以非同步方式處理。您無法修改或取消要求。
onResponseStarted- 收到回應主體的第一個位元組時觸發。如果是 HTTP 要求，這表示狀態行和回應標頭可用。這項事件僅供參考，且會以非同步方式處理。但無法修改或取消要求。
onCompleted- 在要求處理成功時觸發。
onErrorOccurred- 無法成功處理要求時觸發。
網頁要求 API 可保證，對於每個要求，系統都會觸發 onCompleted 或 onErrorOccurred 做為最終事件，但有一個例外狀況：如果要求重新導向至 data:// 網址，則 onBeforeRedirect 是最後回報的事件。
* 請注意，網頁要求 API 會向擴充功能提供網路堆疊的抽象概念。 在內部，一個網址要求可以分割成多個 HTTP 要求 (例如從大型檔案擷取個別位元組範圍)，也可以由網路堆疊處理，而不與網路通訊。因此，API 不會提供傳送至網路的最終 HTTP 標頭。舉例來說，擴充功能無法查看與快取相關的所有標頭。
目前不會向 onBeforeSendHeaders 事件提供下列標頭。這份清單不保證完整或穩定。
- 授權
- Cache-Control
- 連線
- Content-Length
- 主機
- If-Modified-Since
- If-None-Match
- If-Range
- Partial-Data
- Pragma
- Proxy-Authorization
- Proxy-Connection
- Transfer-Encoding
自 Chrome 79 起，修改要求標頭會影響跨源資源共享 (CORS) 檢查。如果跨源要求的修改標頭不符合條件，系統會傳送 CORS 預檢，詢問伺服器是否可接受這類標頭。如果確實需要以違反 CORS 通訊協定的方式修改標頭，請在 opt_extraInfoSpec 中指定 'extraHeaders'。另一方面，修改回應標頭無法騙過 CORS 檢查。如要欺騙 CORS 通訊協定，您也必須為回應修改指定 'extraHeaders'。
自 Chrome 79 起，webRequest API 預設「不會」攔截 CORS 預檢要求和回應。如果要求網址的 opt_extraInfoSpec 中有指定 'extraHeaders' 的監聽器，擴充功能就會看到該要求網址的 CORS 預檢。onBeforeRequest 也可以從 Chrome 79 取得 'extraHeaders'。
從 Chrome 79 開始，系統「不會提供」下列要求標頭，且除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法修改或移除：
- 來源
自 Chrome 72 起，如果您需要在跨源讀取封鎖 (CORB) 封鎖回應之前修改回應，則必須在 opt_extraInfoSpec 中指定 'extraHeaders'。
自 Chrome 72 起，系統「不會提供」下列要求標頭，且除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法修改或移除這些標頭：
- Accept-Language
- Accept-Encoding
- 參照網址
- Cookie
自 Chrome 72 起，系統「不會提供」Set-Cookie 回應標頭，且除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法修改或移除。
自 Chrome 89 起，除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法有效修改或移除 X-Frame-Options 回應標頭。
webRequest API 只會根據擴充功能的主機權限，公開擴充功能有權查看的要求。此外，只有下列配置可供存取：http://、https://、ftp://、file://、ws:// (Chrome 58 以上版本)、wss:// (Chrome 58 以上版本)、urn: (Chrome 91 以上版本) 或 chrome-extension://。此外，即使某些要求的網址使用上述其中一種配置，也會遭到隱藏。包括 chrome-extension://other_extension_id (其中 other_extension_id 不是處理要求的擴充功能 ID)、https://www.google.com/chrome，以及其他與瀏覽器核心功能相關的機密要求。此外，系統會對封鎖事件處理常式隱藏擴充功能中的同步 XMLHttpRequest，以免發生死結。請注意，對於某些支援的配置，由於對應通訊協定的性質，可用的事件集可能會受到限制。舉例來說，如果是檔案配置，則只能調度 onBeforeRequest、onResponseStarted、onCompleted 和 onErrorOccurred。
從 Chrome 58 開始，webRequest API 支援攔截 WebSocket 握手要求。由於交握是透過 HTTP 升級要求完成，因此其流程符合以 HTTP 為導向的 webRequest 模型。請注意，API 不會攔截：
- 透過已建立的 WebSocket 連線傳送個別訊息。
- WebSocket 正在關閉連線。
WebSocket 要求不支援重新導向。
自 Chrome 72 起，擴充功能必須同時具備要求網址和要求發起者的主機權限，才能攔截要求。
從 Chrome 96 開始，webRequest API 支援攔截透過 HTTP/3 握手要求的 WebTransport。由於交握是透過 HTTP CONNECT 要求完成，因此其流程符合以 HTTP 為導向的 webRequest 模型。請注意：
- 工作階段建立後，擴充功能無法透過 webRequest API 觀察或介入工作階段。
- 系統會忽略在
onBeforeSendHeaders中修改 HTTP 要求標頭。 - 透過 HTTP/3 傳輸的 WebTransport 不支援重新導向和驗證。
概念
如以下各節所述，網頁要求 API 中的事件會使用要求 ID，您可以在註冊事件監聽器時，視需要指定篩選器和額外資訊。
要求 ID
每個要求都有專屬 ID。這個 ID 在瀏覽器工作階段和擴充功能環境中是專屬的。在要求的生命週期內，這個 ID 會維持不變，可用於比對相同要求的事件。請注意，如果是 HTTP 重新導向或 HTTP 驗證，多個 HTTP 要求會對應至一個網頁要求。
註冊事件監聽器
如要為網頁要求註冊事件監聽器，請使用一般 addListener() 函式的變化版本。除了指定回呼函式外，您還必須指定篩選器引數，並可選擇指定額外資訊引數。
網頁要求 API 的 addListener() 有三個引數，定義如下：
var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];
以下是監聽 onBeforeRequest 事件的範例：
chrome.webRequest.onBeforeRequest.addListener(
callback, filter, opt_extraInfoSpec);
每次呼叫 addListener() 時，都必須將回呼函式做為第一個參數。這個回呼函式會傳遞字典，其中包含目前網址要求的相關資訊。這本字典中的資訊取決於特定事件類型以及 opt_extraInfoSpec 的內容。
如果選用的 opt_extraInfoSpec 陣列包含 'blocking' 字串 (僅限特定事件)，回呼函式會同步處理。也就是說，在回呼函式傳回之前，要求會遭到封鎖。在這種情況下，回呼可以傳回 webRequest.BlockingResponse，決定要求的後續生命週期。視情況而定，這項回應可取消或重新導向要求 (onBeforeRequest)、取消要求或修改標頭 (onBeforeSendHeaders、onHeadersReceived)，以及取消要求或提供驗證憑證 (onAuthRequired)。
如果選用的 opt_extraInfoSpec 陣列改為包含 'asyncBlocking' 字串 (僅適用於 onAuthRequired)，擴充功能可以非同步產生 webRequest.BlockingResponse。
webRequest.RequestFilter filter 可讓您限制觸發事件的要求，限制維度包括：
- 網址
- 網址模式，例如
*://www.google.com/foo*bar。 - 類型
- 要求類型，例如
main_frame(為頂層框架載入的文件)、sub_frame(為內嵌框架載入的文件) 和image(網站上的圖片)。詳情請參閱webRequest.RequestFilter。 - 分頁 ID
- 分頁 ID。
- 視窗 ID
- 視窗的 ID。
視事件類型而定，您可以在 opt_extraInfoSpec 中指定字串，要求提供要求的其他資訊。只有在明確要求時，才會使用這個方法提供要求的詳細資料。
實作詳情
開發使用 Web Request API 的擴充功能時，請務必瞭解幾項導入細節：
web_accessible_resources
如果擴充功能使用 webRequest API，將公開資源要求重新導向至無法透過網路存取的資源，系統會封鎖該要求並傳回錯誤。即使無法透過網路存取的資源是由重新導向擴充功能所擁有，上述情況仍適用。如要宣告與 declarativeWebRequest API 搭配使用的資源，請按照這裡的說明，在資訊清單中宣告並填入 "web_accessible_resources" 陣列。
衝突解決
在目前的網頁要求 API 實作中，如果至少有一個擴充功能指示取消要求，系統就會視為取消要求。如果擴充功能取消要求，所有擴充功能都會收到 onErrorOccurred 事件通知。一次只能有一個擴充功能重新導向要求或修改標頭。如果有多個擴充功能嘗試修改要求，系統會採用最近安裝的擴充功能，並忽略其他擴充功能。如果修改或重新導向指令遭到忽略，擴充功能不會收到通知。
快取
Chrome 採用兩種快取：磁碟快取和速度極快的記憶體內快取。記憶體內快取的生命週期與轉譯程序的生命週期相關，大致對應至分頁。Web Request API 無法偵測到從記憶體快取回應的要求。如果要求處理常式變更行為 (例如，根據要求封鎖的行為)，簡單的頁面重新整理可能不會遵循這項變更行為。為確保行為變更順利完成，請呼叫 handlerBehaviorChanged() 來清除記憶體內快取。但請勿經常執行，因為清除快取是非常耗費資源的操作。註冊或取消註冊事件監聽器後，您不需要呼叫 handlerBehaviorChanged()。
時間戳記
網頁要求事件的 timestamp 屬性只能保證內部一致。比較兩個事件可得出正確的時間差，但如果與擴充功能中的目前時間比較 (例如透過 (new Date()).getTime())，可能會產生非預期的結果。
錯誤處理
如果嘗試以無效的引數註冊事件，系統會擲回 JavaScript 錯誤，且不會註冊事件處理常式。如果處理事件時擲回錯誤，或事件處理常式傳回無效的封鎖回應，系統會將錯誤訊息記錄到擴充功能的控制台，並忽略該要求的處理常式。
範例
以下範例說明如何封鎖所有傳送至 www.evil.com 的要求：
chrome.webRequest.onBeforeRequest.addListener(
function(details) {
return {cancel: details.url.indexOf("://www.evil.com/") != -1};
},
{urls: ["<all_urls>"]},
["blocking"]
);
由於這個函式使用封鎖事件處理常式，因此需要在資訊清單檔案中加入 "webRequest" 和 "webRequestBlocking" 權限。
以下範例能以更有效率的方式達到相同目標，因為未指定 www.evil.com 的要求不需要傳遞至擴充功能：
chrome.webRequest.onBeforeRequest.addListener(
function(details) { return {cancel: true}; },
{urls: ["*://www.evil.com/*"]},
["blocking"]
);
以下範例說明如何從所有要求中刪除 User-Agent 標頭：
chrome.webRequest.onBeforeSendHeaders.addListener(
function(details) {
for (var i = 0; i < details.requestHeaders.length; ++i) {
if (details.requestHeaders[i].name === 'User-Agent') {
details.requestHeaders.splice(i, 1);
break;
}
}
return {requestHeaders: details.requestHeaders};
},
{urls: ["<all_urls>"]},
["blocking", "requestHeaders"]
);
如要試用 chrome.webRequest API，請從 chrome-extension-samples 存放區安裝 webRequest 範例。
類型
BlockingResponse
為已套用「blocking」extraInfoSpec 的事件處理常式傳回值。允許事件處理常式修改網路要求。
屬性
-
authCredentials
物件 選填
僅用於回應 onAuthRequired 事件。如果設定，系統會使用提供的憑證提出要求。
-
密碼
字串
-
使用者名稱
字串
-
-
取消
布林值 選填
如果為 true，系統會取消要求。這會導致系統無法傳送要求。這可用於回應 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件。
-
redirectUrl
字串 選填
僅用於回應 onBeforeRequest 和 onHeadersReceived 事件。如果設定這項政策，系統會阻止傳送/完成原始要求，並改為重新導向至指定網址。允許重新導向至非 HTTP 配置，例如
data:。由重新導向動作啟動的重新導向會使用原始要求方法，但有一個例外：如果重新導向是在 onHeadersReceived 階段啟動，則會使用 GET 方法發出重新導向。系統會忽略從ws://和wss://配置網址重新導向。 -
requestHeaders
HttpHeaders 選填
僅用於回應 onBeforeSendHeaders 事件。如果設定，系統會改用這些要求標頭提出要求。
-
responseHeaders
HttpHeaders 選填
僅用於回應 onHeadersReceived 事件。如果設定，系統會假設伺服器改為使用這些回應標頭回應。只有在您確實想修改標頭，以限制衝突數量時，才傳回
responseHeaders(每個要求只能有一個擴充功能修改responseHeaders)。
FormDataItem
包含表單資料中傳遞的資料。如果是網址編碼表單，當資料為 UTF-8 字串時，會儲存為字串，否則會儲存為 ArrayBuffer。如果是表單資料，則為 ArrayBuffer。如果表單資料代表上傳檔案，則為包含檔案名稱的字串 (如有提供檔案名稱)。
列舉
ArrayBuffer
字串
HttpHeaders
HTTP 標頭陣列。每個標頭都以字典表示，其中包含 name 鍵，以及 value 或 binaryValue。
類型
object[]
屬性
-
binaryValue
number[] 選填
如果 HTTP 標頭的值無法以 UTF-8 表示，則會儲存為個別位元組值 (0..255)。
-
名稱
字串
HTTP 標頭的名稱。
-
值
字串 選填
HTTP 標頭的值 (如果能以 UTF-8 表示)。
IgnoredActionType
列舉
"redirect"
"request_headers"
"response_headers"
"auth_credentials"
OnAuthRequiredOptions
列舉
"responseHeaders"
指定事件應包含回應標頭。
"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。
"asyncBlocking"
指定以非同步方式處理回呼函式。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
OnBeforeRedirectOptions
列舉
"responseHeaders"
指定事件應包含回應標頭。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
OnBeforeRequestOptions
列舉
"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。
"requestBody"
指定事件應包含要求主體。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
OnBeforeSendHeadersOptions
列舉
"requestHeaders"
指定事件應包含要求標頭。
"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
OnCompletedOptions
列舉
"responseHeaders"
指定事件應包含回應標頭。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
OnErrorOccurredOptions
值
"extraHeaders"
OnHeadersReceivedOptions
列舉
"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。
"responseHeaders"
指定事件應包含回應標頭。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
"securityInfo"
指定事件應包含 SecurityInfo。
"securityInfoRawDer"
指定事件應包含含有憑證原始位元組的 SecurityInfo。
OnResponseStartedOptions
列舉
"responseHeaders"
指定事件應包含回應標頭。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
OnSendHeadersOptions
列舉
"requestHeaders"
指定事件應包含要求標頭。
"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。
RequestFilter
描述要套用至 webRequest 事件的篩選條件物件。
屬性
-
tabId
數字 選填
-
類型
ResourceType[] 選填
要求類型清單。系統會篩除不符合任何類型的要求。
-
網址
string[]
網址或網址模式清單。系統會篩除不符合任何網址的要求。
-
windowId
數字 選填
ResourceType
列舉
"main_frame"
將資源指定為主頁框。
"sub_frame"
將資源指定為子框架。
"stylesheet"
將資源指定為樣式表。
"script"
將資源指定為指令碼。
"image"
將資源指定為圖片。
"font"
將資源指定為字型。
"object"
將資源指定為物件。
"xmlhttprequest"
將資源指定為 XMLHttpRequest。
"ping"
將資源指定為連線偵測 (ping)。
"csp_report"
將資源指定為內容安全政策 (CSP) 報表。
"media"
將資源指定為媒體物件。
"websocket"
將資源指定為 WebSocket。
"webbundle"
將資源指定為 WebBundle。
"other"
將資源指定為未列出的類型。
SecurityInfo
屬性
-
憑證
object[]
憑證清單
-
指紋
物件
憑證的指紋。
-
sha256
字串
憑證的 sha256 指紋。
-
-
rawDER
ArrayBuffer 選用
DER 編碼伺服器憑證的原始位元組
-
-
state
字串
連線狀態。安全、不安全、損毀。
UploadData
包含在網址要求中上傳的資料。
屬性
-
位元組
任意 選填
含有資料副本的 ArrayBuffer。
-
檔案
字串 選填
包含檔案路徑和名稱的字串。
屬性
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
每 10 分鐘持續間隔內，可呼叫 handlerBehaviorChanged 的次數上限。handlerBehaviorChanged 是耗費大量資源的函式呼叫，不應經常呼叫。
值
20
方法
handlerBehaviorChanged()
chrome.webRequest.handlerBehaviorChanged(
callback?: function,
): Promise<void>
當 webRequest 處理常式的行為變更時，必須呼叫這個方法，以免因快取而導致處理不正確。這個函式呼叫的成本很高。請勿頻繁呼叫。
參數
-
callback
函式 選填
callback參數如下：() => void
傳回
-
承諾<void>
Chrome 116 以上版本Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
事件
onActionIgnored
chrome.webRequest.onActionIgnored.addListener(
callback: function,
)
當擴充功能對網路要求提出的修改建議遭到忽略時，就會觸發這個事件。如果與其他擴充功能發生衝突，就會發生這種情況。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
已忽略的建議動作。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
-
onAuthRequired
chrome.webRequest.onAuthRequired.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnAuthRequiredOptions[],
)
收到驗證失敗時觸發。監聽器有三個選項：提供驗證憑證、取消要求並顯示錯誤頁面，或不對驗證要求採取任何動作。如果提供的使用者憑證不正確，系統可能會針對同一要求多次呼叫這個方法。請注意，extraInfoSpec 參數只能指定 'blocking' 或 'asyncBlocking' 模式。
參數
-
callback
函式
callback參數如下：(details: object, asyncCallback?: function) => BlockingResponse | undefined
-
詳細資料
物件
-
挑戰者
物件
要求驗證的伺服器。
-
主機
字串
-
通訊埠
數字
-
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
isProxy
布林值
Proxy-Authenticate 為 True，WWW-Authenticate 為 False。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
領域
字串 選填
伺服器提供的驗證領域 (如有)。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
responseHeaders
HttpHeaders 選填
與這項回應一併收到的 HTTP 回應標頭。
-
架構
字串
驗證配置，例如 Basic 或 Digest。
-
statusCode
數字
Chrome 43 以上版本伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
asyncCallback
函式 選填
Chrome 58 以上版本asyncCallback參數如下：(response: BlockingResponse) => void
-
returns
BlockingResponse | undefined
如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。
-
-
篩選器
-
extraInfoSpec
onBeforeRedirect
chrome.webRequest.onBeforeRedirect.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRedirectOptions[],
)
伺服器即將啟動重新導向時觸發。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
fromCache
布林值
指出這項回應是否從磁碟快取擷取。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
ip
字串 選填
實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
redirectUrl
字串
新網址。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
responseHeaders
HttpHeaders 選填
與這個重新導向一併收到的 HTTP 回應標頭。
-
statusCode
數字
伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
-
篩選器
-
extraInfoSpec
onBeforeRequest
chrome.webRequest.onBeforeRequest.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRequestOptions[],
)
即將提出要求時觸發。
參數
-
callback
函式
callback參數如下：(details: object) => BlockingResponse | undefined
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestBody
物件 選填
包含 HTTP 要求主體資料。只有在 extraInfoSpec 包含「requestBody」時才會提供。
-
錯誤
字串 選填
取得要求主體資料時發生錯誤。
-
formData
物件 選填
如果要求方法是 POST，且主體是以 UTF8 編碼的鍵/值組合序列 (編碼為 multipart/form-data 或 application/x-www-form-urlencoded)，則會顯示這個字典，且每個鍵都會包含該鍵的所有值清單。如果資料屬於其他媒體類型，或格式不正確，則不會顯示字典。這個字典的值範例為 {'key': ['value1', 'value2']}。
-
raw
UploadData[] 選用
如果要求方法是 PUT 或 POST，且主體尚未在 formData 中剖析，則未剖析的要求主體元素會包含在這個陣列中。
-
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
returns
BlockingResponse | undefined
如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。
-
-
篩選器
-
extraInfoSpec
onBeforeSendHeaders
chrome.webRequest.onBeforeSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeSendHeadersOptions[],
)
在傳送 HTTP 要求前，一旦要求標頭可用，就會觸發。這可能發生在與伺服器建立 TCP 連線後，但尚未傳送任何 HTTP 資料前。
參數
-
callback
函式
callback參數如下：(details: object) => BlockingResponse | undefined
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestHeaders
HttpHeaders 選填
要與這項要求一併傳送的 HTTP 要求標頭。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
returns
BlockingResponse | undefined
如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。
-
-
篩選器
-
extraInfoSpec
onCompleted
chrome.webRequest.onCompleted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnCompletedOptions[],
)
要求完成時觸發。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
fromCache
布林值
指出這項回應是否從磁碟快取擷取。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
ip
字串 選填
實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
responseHeaders
HttpHeaders 選填
與這項回應一併收到的 HTTP 回應標頭。
-
statusCode
數字
伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
-
篩選器
-
extraInfoSpec
OnCompletedOptions[] 選用
onErrorOccurred
chrome.webRequest.onErrorOccurred.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnErrorOccurredOptions[],
)
發生錯誤時觸發。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。如果要求是導覽頁框，則不會顯示這個值。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
錯誤
字串
錯誤說明。我們不保證這個字串在不同版本之間能維持回溯相容性。請勿剖析內容並據此採取行動。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
fromCache
布林值
指出這項回應是否從磁碟快取擷取。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
ip
字串 選填
實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
-
篩選器
-
extraInfoSpec
onHeadersReceived
chrome.webRequest.onHeadersReceived.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnHeadersReceivedOptions[],
)
收到要求的 HTTP 回應標頭時觸發。
參數
-
callback
函式
callback參數如下：(details: object) => BlockingResponse | undefined
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
responseHeaders
HttpHeaders 選填
與這項回應一併收到的 HTTP 回應標頭。
-
securityInfo
SecurityInfo 選填
Chrome 144+基礎連線所用 TLS/QUIC 連線的相關資訊。只有在
extraInfoSpec參數中指定securityInfo時，系統才會提供這項資訊。 -
statusCode
數字
Chrome 43 以上版本伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
returns
BlockingResponse | undefined
如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。
-
-
篩選器
-
extraInfoSpec
onResponseStarted
chrome.webRequest.onResponseStarted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnResponseStartedOptions[],
)
收到回應主體的第一個位元組時觸發。如果是 HTTP 要求，這表示狀態行和回應標頭可用。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
fromCache
布林值
指出這項回應是否從磁碟快取擷取。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
ip
字串 選填
實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
responseHeaders
HttpHeaders 選填
與這項回應一併收到的 HTTP 回應標頭。
-
statusCode
數字
伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
-
篩選器
-
extraInfoSpec
onSendHeaders
chrome.webRequest.onSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnSendHeadersOptions[],
)
在要求傳送至伺服器前觸發 (在 onSendHeaders 觸發時，可看到先前 onBeforeSendHeaders 回呼的修改)。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
documentId
字串 選填
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件所處的生命週期。
-
frameId
數字
值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (
type為main_frame或sub_frame)，frameId會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。 -
frameTypeChrome 106 以上版本
發生要求的頁框類型。
-
initiator
字串 選填
Chrome 63 以上版本發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。
-
方法
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選填
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。
-
parentFrameId
數字
包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。
-
requestHeaders
HttpHeaders 選填
與這項要求一併傳送的 HTTP 要求標頭。
-
requestId
字串
要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。
-
tabId
數字
要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
數字
觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。
-
類型
要求資源的使用方式。
-
網址
字串
-
-
-
篩選器
-
extraInfoSpec
OnSendHeadersOptions[] 選用