declarativeNetRequest - Mozilla

Permissions

要使用此 API，擴充套件必須在其 manifest.json 檔案中請求 "declarativeNetRequest" 或 "declarativeNetRequestWithHostAccess" 許可權。"declarativeNetRequest" 許可權會顯示給使用者在許可權提示中，而 "declarativeNetRequestWithHostAccess" 則不會。

當與 declarativeNetRequest 許可權一起使用時，"declarativeNetRequest" 許可權允許擴充套件攔截和升級請求，而無需任何主機許可權。如果擴充套件要重定向請求或修改請求上的標頭，或者當使用 "declarativeNetRequestWithHostAccess" 許可權而不是 "declarativeNetRequest" 許可權時，則需要主機許可權。在這些情況下對請求進行操作時，需要請求 URL 的主機許可權。對於所有請求，除了導航請求（即資源型別 main_frame 和 sub_frame）之外，請求發起者也需要主機許可權。請求的發起者通常是觸發請求的文件或 worker。

某些請求受到限制，不能被擴充套件匹配。這些包括特權瀏覽器請求、對或來自受限域的請求，以及來自其他擴充套件的請求。

使用 getMatchedRules 和 onRuleMatchedDebug 需要 "declarativeNetRequestFeedback" 許可權，因為它們返回匹配的宣告性規則資訊。有關更多資訊，請參閱測試。

規則

宣告性規則由四個欄位定義

id – 唯一標識規則集中規則的 ID。強制性，應 >= 1。
priority – 規則優先順序。指定時，應 >= 1。預設為 1。有關優先順序如何影響規則應用的詳細資訊，請參閱匹配優先順序。
condition – 觸發此規則的條件。
action – 匹配規則時要執行的操作。規則可以執行以下操作之一
- 阻止網路請求。
- 重定向網路請求。
- 修改網路請求的標頭。
- 阻止其他匹配規則的應用。

注意：當出現以下情況時，重定向操作不會重定向請求，請求照常繼續

操作不改變請求。
重定向 URL 無效（例如，redirect.regexSubstitution 的值不是有效 URL）。

這是一個示例規則，它阻止所有源自 "foo.com" 且 URL 中包含子字串 "abc" 的指令碼請求

json

{
  "id": 1,
  "priority": 1,
  "action": { "type": "block" },
  "condition": {
    "urlFilter": "abc",
    "initiatorDomains": ["foo.com"],
    "resourceTypes": ["script"]
  }
}

規則條件的 urlFilter 欄位用於指定與請求 URL 匹配的模式。有關詳細資訊，請參閱RuleCondition。URL 過濾器的示例包括

`urlFilter`	匹配	不匹配
`"abc"`	https://abcd.com https://example.com/abcd	https://ab.com
`"abc*d"`	https://abcd.com https://example.com/abcxyzd	https://abc.com
`"\|\|a.example.com"`	https://a.example.com/ https://b.a.example.com/xyz	https://example.com/
`"\|https*"`	https://example.com	http://example.com/ http://https.com

規則集

規則按規則集組織

靜態規則集：使用 "declarative_net_request" 清單鍵定義並存儲在擴充套件中的規則集合。擴充套件可以使用 updateEnabledRulesets 啟用和停用靜態規則集。啟用靜態規則集的集合會在會話之間保留，但不會在擴充套件更新之間保留。擴充套件安裝和更新時啟用的靜態規則集由 "declarative_net_request" 清單鍵的內容決定。
動態規則集：使用 updateDynamicRules 新增或刪除的規則。這些規則在會話和擴充套件更新之間保留。
會話規則集：使用 updateSessionRules 新增或刪除的規則。這些規則不會在瀏覽器會話之間保留。

注意：有關無效靜態規則的錯誤和警告僅在測試期間顯示。永久安裝的擴充套件中的無效靜態規則將被忽略。因此，透過測試驗證靜態規則集是否有效非常重要。

限制

靜態規則集限制

一個擴充套件可以

在 "declarative_net_request" 清單鍵中指定靜態規則集，最多達到 MAX_NUMBER_OF_STATIC_RULESETS 的值。
啟用靜態規則集（在 "declarative_net_request" 清單鍵中或透過程式設計方式），以便它們包含的規則數量（啟用或停用）不超過 GUARANTEED_MINIMUM_STATIC_RULES 的值，並且啟用靜態規則集的數量不超過 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS 的值。

注意：所有擴充套件的已啟用靜態規則集中的規則數量不得超過全侷限制。擴充套件不應依賴全侷限制具有特定值；相反，它們應使用 getAvailableStaticRuleCount 來查詢它們可以啟用的額外規則數量。
停用靜態規則集中的規則，最多達到 MAX_NUMBER_OF_DISABLED_STATIC_RULES 的值。但是，這些停用規則計入 GUARANTEED_MINIMUM_STATIC_RULES。

動態和會話範圍規則

擴充套件可以新增的動態和會話範圍規則的數量限制為

在 Safari 以及最高 Chrome 119 和 Firefox 127 中，為 MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES 的值。
從 Chrome 120 和 Firefox 128 開始，為 MAX_NUMBER_OF_DYNAMIC_RULES 和 MAX_NUMBER_OF_SESSION_RULES 的值。

匹配優先順序

當瀏覽器評估如何處理請求時，它會檢查每個擴充套件的規則，這些規則的條件與請求匹配，並按以下方式選擇要考慮應用的規則

規則優先順序，其中 1 是最低優先順序（未設定優先順序時規則預設為 1）。
如果這未能導致只有一個規則應用
規則操作，按以下優先順序順序
1. "allow" 表示忽略任何其他剩餘規則。
2. "allowAllRequests"（僅適用於 main_frame 和 sub_frame 資源型別）與 allow 具有相同的效果，但同時適用於從請求生成的文件（包括後代幀）中將來的子資源載入。
3. "block" 取消請求。
4. "upgradeScheme" 升級請求的方案。
5. "redirect" 重定向請求。
6. "modifyHeaders" 重寫請求或響應標頭，或兩者兼而有之。

注意：當多個匹配規則具有相同的規則優先順序和規則操作型別時，如果匹配的操作支援附加屬性，則結果可能會不明確。這些屬性可能導致無法組合的結果。例如

"block" 操作不支援附加屬性，因此沒有歧義：所有匹配的 "block" 操作都會產生相同的結果。
"redirect" 操作將請求重定向到一個目標。當多個 "redirect" 操作匹配時，除一個 "redirect" 操作外，所有其他操作都將被忽略。當重定向的請求匹配另一個規則條件時，仍然可能重複重定向。
當它們觸及不同的標頭時，可以獨立應用多個 "modifyHeaders" 操作。當它們觸及相同的標頭時，結果是不明確的，因為不允許某些操作組合（如 declarativeNetRequest.ModifyHeaderInfo 中所述）。因此，"modifyHeaders" 操作的評估順序很重要。

要控制操作的應用順序，請為優先順序重要的規則分配不同的 priority 值。

注意：在規則優先順序和規則操作之後，Firefox 會按此優先順序順序考慮規則所屬的規則集：會話 > 動態 > 會話規則集。這不能在不同瀏覽器之間依賴，請參閱 WECG issue 280。

如果只有一個擴充套件為請求提供規則，則應用該規則。但是，如果有多個擴充套件具有匹配規則，瀏覽器會按以下優先順序順序選擇要應用的規則

"block"
"redirect" 和 "upgradeScheme"
"allow" 和 "allowAllRequests"

如果請求未被阻止或重定向，則應用匹配的 modifyHeaders 操作，如 declarativeNetRequest.ModifyHeaderInfo 中所述。

測試

testMatchOutcome、getMatchedRules 和 onRuleMatchedDebug 可用於協助測試規則和規則集。這些 API 需要 "declarativeNetRequestFeedback" 許可權。此外

在 Chrome 中，這些 API 僅適用於未打包的擴充套件。
在 Firefox 中，這些 API 僅在將 extensions.dnr.feedback 首選項設定為 true 後可用。使用 about:config 或 web-ext CLI 工具的 --pref 標誌設定此首選項。

與 webRequest API 的比較

declarativeNetRequest API 在瀏覽器本身評估網路請求。這使其比 webRequest API 效能更高，webRequest API 中每個網路請求都在擴充套件程序的 JavaScript 中進行評估。
由於請求未被擴充套件程序攔截，declarativeNetRequest 消除了擴充套件對後臺頁面的需求。
與 webRequest API 不同，使用 declarativeNetRequest API 阻止或升級請求時，與 declarativeNetRequest 許可權一起使用時不需要主機許可權。
declarativeNetRequest API 為使用者提供更好的隱私保護，因為擴充套件不會讀取代表使用者發出的網路請求。
（僅限 Chrome：）與 webRequest API 不同，使用 declarativeNetRequest API 阻止的任何影像或 iframe 會自動在 DOM 中摺疊。
在決定是否阻止或重定向請求時，declarativeNetRequest API 優先於 webRequest API，因為它允許同步攔截。同樣，透過 declarativeNetRequest API 刪除的任何標頭都不會顯示給 webRequest 擴充套件。
webRequest API 比 declarativeNetRequest API 更靈活，因為它允許擴充套件以程式設計方式評估請求。

型別

declarativeNetRequest.HeaderInfo: 要匹配請求的響應標頭，在 rule.condition.excludedResponseHeaders 陣列或 rule.condition.responseHeaders 陣列中宣告。
declarativeNetRequest.MatchedRule: 匹配規則的詳細資訊。
declarativeNetRequest.ModifyHeaderInfo: 要修改請求的請求或響應標頭。
declarativeNetRequest.Redirect: 如何執行重定向的詳細資訊。僅對重定向規則有效。
declarativeNetRequest.ResourceType: 請求的資源型別。
declarativeNetRequest.Rule: 包含規則詳細資訊的物件。
declarativeNetRequest.RuleAction: 定義如果匹配規則要執行的操作的物件。
declarativeNetRequest.RuleCondition: 定義觸發規則條件的物件。
declarativeNetRequest.URLTransform: 包含要為重定向操作執行的 URL 轉換詳細資訊的物件。

屬性

declarativeNetRequest.DYNAMIC_RULESET_ID: 擴充套件新增的動態規則的規則集 ID。
declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL: 在 declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL declarativeNetRequest.getMatchedRules 呼叫可以進行的持續時間間隔。
declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES: 擴充套件在其啟用的靜態規則集中保證的最小靜態規則數量。
declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL: 在 declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL 期間可以呼叫 declarativeNetRequest.getMatchedRules 的次數。
declarativeNetRequest.MAX_NUMBER_OF_DISABLED_STATIC_RULES: 每個靜態規則集可以停用的最大靜態規則數量。
declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES 已棄用: 擴充套件可以新增的最大動態和會話範圍規則數量。
declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_RULES: 擴充套件可以新增的最大動態規則數量。
declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS: 擴充套件可以啟用的最大靜態規則集數量。
declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES: 擴充套件可以新增的最大正則表示式規則數量。
declarativeNetRequest.MAX_NUMBER_OF_SESSION_RULES: 擴充套件可以新增的最大會話範圍規則數量。
declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS: 擴充套件可以作為 declarative_net_request.rule_resources 清單鍵的一部分指定的靜態規則集的最大數量。
declarativeNetRequest.SESSION_RULESET_ID: 擴充套件新增的會話範圍規則的規則集 ID。

函式

declarativeNetRequest.getAvailableStaticRuleCount(): 返回擴充套件在達到全域性靜態規則限制之前可以啟用的靜態規則數量。
declarativeNetRequest.getDisabledRuleIds(): 返回靜態規則集中已停用規則的 ID。
declarativeNetRequest.getDynamicRules(): 返回擴充套件的動態規則集。
declarativeNetRequest.getEnabledRulesets(): 返回已啟用靜態規則集的 ID。
declarativeNetRequest.getMatchedRules(): 返回與擴充套件匹配的所有規則。
declarativeNetRequest.getSessionRules(): 返回擴充套件的會話範圍規則集。
declarativeNetRequest.isRegexSupported(): 檢查正則表示式是否支援作為 declarativeNetRequest.RuleCondition.regexFilter 規則條件。
declarativeNetRequest.setExtensionActionOptions(): 配置如何處理標籤頁的操作計數。
declarativeNetRequest.testMatchOutcome(): 檢查擴充套件的任何 declarativeNetRequest 規則是否會匹配假設的請求。
declarativeNetRequest.updateDynamicRules(): 修改擴充套件的活動動態規則集。
declarativeNetRequest.updateEnabledRulesets(): 更新擴充套件的活動靜態規則集。
declarativeNetRequest.updateSessionRules(): 修改擴充套件的會話範圍規則集。
declarativeNetRequest.updateStaticRules(): 修改靜態規則集中規則的啟用狀態。

事件

declarativeNetRequest.onRuleMatchedDebug: 當除錯具有 "declarativeNetRequestFeedback" 許可權的擴充套件時，當規則與請求匹配時觸發。

擴充套件程式示例

瀏覽器相容性

幫助改進 MDN

瞭解如何貢獻

此頁面最後由 MDN 貢獻者在 2025 年 7 月 17 日修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題