在 Manifest V3 中修改網路要求
Manifest V3 會變更擴充功能處理網路要求的修改方式。擴充功能不會使用 chrome.webRequest
攔截網路要求並在執行階段變更要求,而是會指定規則,描述符合一組條件時要執行的動作。請使用 Declarative Net Request API 進行設定。
Web Request API 和宣告式 Net Request API 有顯著差異,您不需要將一個函式呼叫替換為另一個函式呼叫,而是依據用途重新編寫程式碼。本節將逐步引導您完成這項程序。
在 Manifest V2 中,封鎖網路要求可能會大幅降低擴充功能及搭配運作網頁的效能。webRequest
命名空間支援九個可能封鎖的事件,每個事件都沒有數量限制的事件處理常式。更糟的是,每個網頁都可能遭到多個擴充功能封鎖,而且要求的權限也不高。Manifest V3 將回呼替換為宣告式規則,有助於解決這個問題。
這三個節是第二節,說明不屬於擴充功能 Service Worker 的程式碼需要變更。以及如何將 Manifest V2 使用的封鎖網路要求轉換成 Manifest V3 使用的宣告式淨要求。其他兩節將介紹遷移至 Manifest V3 及提升安全性所需的程式碼更新。
更新權限
對 manifest.json
中的 "permissions"
欄位進行下列變更。
- 如果您不再需要觀察網路要求,請移除
"webRequest"
權限。 - 將比對模式從
"permissions"
移至"host_permissions"
。
您必須根據用途新增其他權限,我們會透過這類權限支援的用途說明。
建立宣告式淨值要求規則
如要建立宣告式淨值要求規則,您必須在 manifest.json
中加入 "declarative_net_request"
物件。"declarative_net_request"
區塊包含 "rule_resource"
物件的陣列,這些物件指向規則檔案。規則檔案包含一個物件陣列,用於指定動作以及叫用這些動作的條件。
常見用途
以下各節說明宣告式網路要求的常見用途。以下說明只是簡要說明。如要進一步瞭解本文提供的所有資訊,請參閱 chrome.declarativeNetRequest
的 API 參考資料。
封鎖單一網址
Manifest V2 的常見用途是,在背景指令碼中使用 onBeforeRequest
事件封鎖網路要求。
chrome.webRequest.onBeforeRequest.addListener((e) => { return { cancel: true }; }, { urls: ["https://www.example.com/*"] }, ["blocking"]);
針對 Manifest V3,請使用 "block"
動作類型建立新的 declarativeNetRequest
規則。請注意範例規則中的 "condition"
物件。其 "urlFilter"
會取代傳遞至 webRequest
事件監聽器的 urls
選項。"resourceTypes"
陣列會指定要封鎖的資源類別。這個範例只封鎖主要的 HTML 網頁,但你可以只封鎖字型。
[ { "id" : 1, "priority": 1, "action" : { "type" : "block" }, "condition" : { "urlFilter" : "||example.com", "resourceTypes" : ["main_frame"] } } ]
如要使用這項功能,請更新擴充功能的權限。在 manifest.json
中,將 "webRequestBlocking"
權限替換為 "declarativeNetRequest"
權限。請注意,封鎖內容不需要主機權限,因此該網址會從 "permissions"
欄位中移除。如上所示,規則檔案會指定要套用宣告式網路要求的主機或主機。
如要試用,您可以在範例存放區中找到下列程式碼。
"permissions": [ "webRequestBlocking", "https://*.example.com/*" ]
"permissions": [ "declarativeNetRequest", ]
重新導向多個網址
Manifest V2 的另一個常見用途是使用 BeforeRequest
事件將網路要求重新導向。
chrome.webRequest.onBeforeRequest.addListener((e) => { console.log(e); return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" }; }, { urls: [ "https://developer.chrome.com/docs/extensions/mv2/" ] }, ["blocking"] );
如果是 Manifest V3,請使用 "redirect"
動作類型。和先前一樣,"urlFilter"
會取代傳遞至 webRequest
事件監聽器的 url
選項。請注意,在這個範例中,規則檔案的 "action"
物件包含 "redirect"
欄位,其中含有要傳回的網址,而非篩選的網址。
[ { "id" : 1, "priority": 1, "action": { "type": "redirect", "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" } }, "condition": { "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/", "resourceTypes": ["main_frame"] } }
如要採用這個做法,您也必須變更擴充功能的權限。和先前一樣,將 "webRequestBlocking"
權限替換為 "declarativeNetRequest"
權限。網址就會再次從 manifest.json
移至規則檔案。請注意,除了主機權限以外,重新導向還需具備 "declarativeNetRequestWithHostAccess"
權限。
如要試用,您可以在範例存放區中找到下列程式碼。
"permissions": [ "webRequestBlocking", "https://developer.chrome.com/docs/extensions/*", "https://developer.chrome.com/docs/extensions/reference" ]
"permissions": [ "declarativeNetRequestWithHostAccess" ], "host_permissions": [ "https://developer.chrome.com/*" ]
封鎖 Cookie
在 Manifest V2 中,如要封鎖 Cookie,必須先攔截網路要求標頭,才能傳送並移除特定 Cookie。
chrome.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
Manifest V3 也會透過規則檔案中的規則執行這項操作。這次的動作類型為「"modifyHeaders"
」。檔案採用 "requestHeaders"
物件的陣列,用於指定要修改的標頭以及如何修改這些物件。請注意,"condition"
物件只包含 "resourceTypes"
陣列。這個函式支援的值與先前範例相同。
如要試用,您可以在範例存放區中找到下列程式碼。
[ { "id": 1, "priority": 1, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "cookie", "operation": "remove" } ] }, "condition": { "urlFilter": "|*?no-cookies=1", "resourceTypes": ["main_frame"] } } ]
如要採用這個做法,您也必須變更擴充功能的權限。和先前一樣,將 "webRequestBlocking"
權限替換為 "declarativeNetRequest"
權限。
"permissions": [ "webRequest", "webRequestBlocking", "https://*/*", "http://*/*" ],
"permissions": [ "declarativeNetRequest", ], "host_permissions": [ "" ]