取代封鎖網路要求監聽器

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

Web Request API 和 Declarative Net Request API 有顯著差異。您需要根據用途重新編寫程式碼，而不是以另一個函式呼叫取代一個函式呼叫。本節將逐步引導您完成這項程序。

如果擴充功能是透過政策安裝，則不需要進行這些變更。對於透過政策安裝的擴充功能，Manifest V3 仍提供 webRequestBlocking 權限。

這是三節中的第二節，說明非擴充功能服務工作人員的程式碼需要進行的變更。本文說明如何將 Manifest V2 使用的封鎖網路要求，轉換為 Manifest V3 使用的宣告式網路要求。另外兩節則涵蓋更新程式碼 (遷移至 Manifest V3 時需要) 和提升安全性。

簡介

在 Manifest V2 中，封鎖網路要求可能會大幅降低擴充功能和網頁的效能。webRequest 命名空間支援九個可能造成封鎖的事件，每個事件都可採用無限數量的事件處理常式。更糟的是，每個網頁都可能遭到多個擴充功能封鎖，而這類擴充功能所需的權限會侵犯隱私。Manifest V3 會以宣告式規則取代回呼，防範這類問題。

更新權限

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

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

視用途而定，您可能需要新增其他權限。這些權限會連同支援的使用案例一併說明。

建立宣告式網路要求規則

如要建立宣告式網路要求規則，請將 "declarative_net_request" 物件新增至 manifest.json。"declarative_net_request" 區塊包含指向規則檔案的 "rule_resource" 物件陣列。規則檔案包含物件陣列，可指定動作和叫用這些動作的條件。

常見用途

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

封鎖單一網址

在 Manifest V2 中，常見的用途是在背景指令碼中使用 onBeforeRequest 事件封鎖網路要求。

資訊清單 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 網頁，但您也可以只封鎖字型。

資訊清單 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 事件的另一個常見用途是重新導向網路要求。

資訊清單 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

在 Manifest V2 中，如要封鎖 Cookie，必須先攔截網頁要求標頭，然後再傳送標頭並移除特定 Cookie。

資訊清單 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" 陣列。支援的值與先前的範例相同。

如要試用這項功能，請前往範例存放區取得下方程式碼。

資訊清單 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": [
    ""
  ]