Skip to main content
declarativeNetRequest API 封鎖廣告與追蹤器。你宣告比對規則,瀏覽器就會在請求離開網路堆疊前原生封鎖它們。

你會做出什麼

為什麼 MV3 取代了阻斷式 webRequest

Manifest V2 的廣告封鎖器註冊阻斷式 webRequest 監聽器。每個請求都要暫停,等擴充功能的 JavaScript 決定它的命運。Manifest V3 基於效能與隱私因素移除了這個模型。改用 declarativeNetRequest 後,瀏覽器自己評估你的規則。你的程式碼從不佔據請求路徑,也從不為了封鎖而讀取請求內容。 代理式的使用情境,例如把所有流量導向另一台伺服器,請改用 proxy API 而不是請求規則。

Manifest

封鎖與允許規則不需要 host permissions。重新導向規則與標頭規則需要受影響網站的 host permissions。
manifest.json
Extension.js 會編譯 rule_resources 引用的規則集檔案,並隨建置輸出一起發出。

靜態規則

靜態規則放在 rules.json,會在擴充功能載入時載入。
rules.json
||domain^ 過濾語法會比對一個網域及其所有子網域。

動態規則

動態規則用於在執行階段變動的過濾條件,例如使用者自行加入的封鎖清單項目。重新加入規則前先移除該規則 id,讓更新保持冪等。
background.js
Chrome 對靜態與動態規則的數量有上限。在發佈大型過濾清單前,先到 declarativeNetRequest 參考文件確認目前的限制。

在徽章上統計已封鎖的請求

一個呼叫就能把 action 徽章變成各分頁的規則命中計數器。
background.js
要用 getMatchedRules 自行讀取命中的規則,需加上 declarativeNetRequestFeedback 權限。

執行

在編輯 manifest.json 之前,先知道 manifest 變更需要重新啟動開發伺服器。參考 開發更新行為
開啟一個會請求被封鎖網域的頁面。規則命中時,徽章數字會上升。

Firefox 注意事項

  • Firefox 在 Manifest V3 支援 declarativeNetRequest
  • Firefox 不支援 setExtensionActionOptions,因此徽章計數器僅限 Chromium。
  • Firefox 在 Manifest V3 仍允許阻斷式 webRequest,Chrome 則把它保留給政策安裝。
  • 當兩個目標出現分歧時,使用 瀏覽器專屬 manifest 欄位

從範本開始

action 範本附帶一個 background script 加上工具列 popup,是封鎖器 UI 的好基礎。
儲存庫:extension-js/examples/action

最佳實務

  • 靜態規則放在 rules.json,動態規則保留給使用者的選擇。
  • 給每個動態規則一個穩定的 id,讓移除保持可預期。
  • resourceTypes 限定在你要封鎖的類型,而不是所有類型。
  • 優先使用封鎖與允許規則,它們不需要 host permissions。
  • 在發佈過濾條件更新前,用真實頁面測試規則。

後續步驟