取代封鎖網路要求監聽器

在 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" 物件陣列，該物件會指向規則檔案。規則檔案包含一組物件，可指定動作和觸發這些動作的條件。

常見用途

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

封鎖單一網址

在資訊清單 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"]
);

在 Manifest 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": [
    ""
  ]