declarativeNetRequest API 封鎖廣告與追蹤器。你宣告比對規則,瀏覽器就會在請求離開網路堆疊前原生封鎖它們。
你會做出什麼
為什麼 MV3 取代了阻斷式 webRequest
Manifest V2 的廣告封鎖器註冊阻斷式webRequest 監聽器。每個請求都要暫停,等擴充功能的 JavaScript 決定它的命運。Manifest V3 基於效能與隱私因素移除了這個模型。改用 declarativeNetRequest 後,瀏覽器自己評估你的規則。你的程式碼從不佔據請求路徑,也從不為了封鎖而讀取請求內容。
代理式的使用情境,例如把所有流量導向另一台伺服器,請改用 proxy API 而不是請求規則。
Manifest
封鎖與允許規則不需要 host permissions。重新導向規則與標頭規則需要受影響網站的 host permissions。manifest.json
rule_resources 引用的規則集檔案,並隨建置輸出一起發出。
靜態規則
靜態規則放在rules.json,會在擴充功能載入時載入。
rules.json
||domain^ 過濾語法會比對一個網域及其所有子網域。
動態規則
動態規則用於在執行階段變動的過濾條件,例如使用者自行加入的封鎖清單項目。重新加入規則前先移除該規則 id,讓更新保持冪等。background.js
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 的好基礎。
最佳實務
- 靜態規則放在
rules.json,動態規則保留給使用者的選擇。 - 給每個動態規則一個穩定的 id,讓移除保持可預期。
- 把
resourceTypes限定在你要封鎖的類型,而不是所有類型。 - 優先使用封鎖與允許規則,它們不需要 host permissions。
- 在發佈過濾條件更新前,用真實頁面測試規則。
後續步驟
- 在 攔截網路請求 觀察流量而不封鎖它。
- 用 安全檢查清單 稽核你的權限面。
- 在 Manifest V3 概念 檢視 background 模型。

