取代封鎖網路要求監聽器

在 Manifest V3 中修改網路要求

Manifest V3 會變更擴充功能處理網路要求修改方式。擴充功能不會攔截網路要求,也不會在執行階段使用 chrome.webRequest 進行變更,而是會指定規則,說明在符合特定條件時要執行的動作。請使用宣告式網路要求 API 執行這項操作。

Web Request API 和 Declarative Net Request API 有明顯差異。您需要根據用途重寫程式碼,而不是用另一個函式呼叫取代函式呼叫。本節將逐步說明這項程序。

在資訊清單 V2 中,封鎖網頁要求可能會大幅降低擴充功能和相關網頁的效能。webRequest 命名空間支援九個可能會阻斷的事件,每個事件都會使用無限數量的事件處理常式。更糟的是,每個網頁都可能遭到多個擴充功能封鎖,而且這類擴充功能所需的權限相當侵入性。Manifest V3 會以宣告式規則取代回呼,以防範這類問題。

這是三個部分中的第二個部分,說明非擴充功能服務 worker 的程式碼所需的變更。說明如何將 Manifest V2 使用的阻斷式網頁要求,轉換為 Manifest V3 使用的宣告式網頁要求。其他兩個部分則會說明遷移至 Manifest V3 所需的程式碼更新,以及提升安全性

更新權限

請對 manifest.json 中的 "permissions" 欄位進行下列變更。

  • 如果您不再需要觀察網路要求,請移除 "webRequest" 權限。
  • 將比對模式從 "permissions" 移至 "host_permissions"

視用途而定,您可能需要新增其他權限。這些權限會說明其支援的用途。

建立宣告式網路要求規則

如要建立宣告式網際要求規則,您必須在 manifest.json 中新增 "declarative_net_request" 物件。"declarative_net_request" 區塊包含指向規則檔案的 "rule_resource" 物件陣列。規則檔案包含一組物件,可指定動作和觸發這些動作的條件。

常見用途

以下各節說明宣告式網際要求的常見用途。以下說明僅提供簡要概要。如要進一步瞭解這裡的所有資訊,請參閱 API 參考資料中的 chrome.declarativeNetRequest

封鎖單一網址

在資訊清單 V2 中,常見的用途是使用背景指令碼中的 onBeforeRequest 事件封鎖網頁要求。

Manifest V2 背景指令碼
chrome.webRequest.onBeforeRequest.addListener((e) => {
   
return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

針對資訊清單 V3,請使用 "block" 動作類型建立新的 declarativeNetRequest 規則。請注意範例規則中的 "condition" 物件。其 "urlFilter" 會取代傳遞至 webRequest 事件監聽器的 urls 選項。"resourceTypes" 陣列會指定要封鎖的資源類別。這個範例只會封鎖主要 HTML 網頁,但您可以封鎖特定項目,例如字型。

資訊清單 V3 規則檔案
[
 
{
   
"id" : 1,
   
"priority": 1,
   
"action" : { "type" : "block" },
   
"condition" : {
     
"urlFilter" : "||example.com",
     
"resourceTypes" : ["main_frame"]
   
}
 
}
]

如要讓這項功能運作,您必須更新擴充功能的權限。在 manifest.json 中,將 "webRequestBlocking" 權限替換為 "declarativeNetRequest" 權限。請注意,由於封鎖內容不需要主機權限,因此網址已從 "permissions" 欄位移除。如上所示,規則檔案會指定宣告式網際網路要求適用的主機。

如要嘗試這項功能,請參考範例存放區中的程式碼。

Manifest V2
  "permissions": [
   
"webRequestBlocking",
   
"https://*.example.com/*"
 
]
Manifest V3
  "permissions": [
   
"declarativeNetRequest",
 
]

重新導向多個網址

在資訊清單 V2 中,另一個常見用途是使用 BeforeRequest 事件重新導向網頁要求。

Manifest V2 背景指令碼
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"]
);

如果是資訊清單 V3,請使用 "redirect" 動作類型。如前所述,"urlFilter" 會取代傳遞至 webRequest 事件監聽器的 url 選項。請注意,在本例中,規則檔案的 "action" 物件包含 "redirect" 欄位,其中包含要傳回的網址,而非要篩選的網址。

資訊清單 V3 規則檔案
[
 
{
   
"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" 權限。

如要嘗試這項功能,請參考範例存放區中的程式碼。

Manifest V2
  "permissions": [
   
"webRequestBlocking",
   
"https://developer.chrome.com/docs/extensions/*",
   
"https://developer.chrome.com/docs/extensions/reference"
 
]
Manifest V3
  "permissions": [
   
"declarativeNetRequestWithHostAccess"
 
],
 
"host_permissions": [
   
"https://developer.chrome.com/*"
 
]

封鎖 Cookie

在資訊清單 V2 中,封鎖 Cookie 需要在網頁要求標頭傳送前攔截並移除特定標頭。

Manifest V2 背景指令碼
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" 陣列。支援的值與先前的範例相同。

如要嘗試這項功能,請參考範例存放區中的程式碼。

Manifest V3 manifest.json
[
 
{
   
"id": 1,
   
"priority": 1,
   
"action": {
     
"type": "modifyHeaders",
     
"requestHeaders": [
       
{ "header": "cookie", "operation": "remove" }
     
]
   
},
   
"condition": {
     
"urlFilter": "|*?no-cookies=1",
     
"resourceTypes": ["main_frame"]
   
}
 
}
]

在這種情況下,您也必須變更擴充功能的權限。如同先前所述,將 "webRequestBlocking" 權限替換為 "declarativeNetRequest" 權限。

Manifest V2
  "permissions": [
   
"webRequest",
   
"webRequestBlocking",
   
"https://*/*",
   
"http://*/*"
 
],
Manifest V3
  "permissions": [
   
"declarativeNetRequest",
 
],
 
"host_permissions": [
   
"