取代封鎖網路要求監聽器

在 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 事件封鎖網路要求。

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

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

Manifest 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",
  ]

重新導向多個網址

Manifest 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" 欄位,其中含有要傳回的網址,而非篩選的網址。

Manifest 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

在 Manifest V2 中,如要封鎖 Cookie,必須先攔截網路要求標頭,才能傳送並移除特定 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": [
    ""
  ]