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 上查看此页面 • 报告此内容的问题