declarativeNetRequest

此 API 使扩展能够指定描述如何处理网络请求的条件和操作。这些声明性规则使浏览器能够在不通知扩展有关单个网络请求的情况下评估和修改网络请求。

权限

要使用此 API，扩展必须在其 manifest.json 文件中请求 "declarativeNetRequest" 或 "declarativeNetRequestWithHostAccess" 权限。

"declarativeNetRequest" 权限允许扩展在没有任何主机权限的情况下阻止和升级请求。如果扩展希望重定向请求或修改请求标头，或者使用 "declarativeNetRequestWithHostAccess" 权限而不是 "declarativeNetRequest" 权限，则需要主机权限。为了在这些情况下对请求进行操作，请求 URL 需要主机权限。对于除导航请求以外的所有请求（即资源类型 main_frame 和 sub_frame），请求的发起者也需要主机权限。请求的发起者通常是触发请求的文档或工作线程。

一些请求是受限制的，扩展无法匹配。其中包括特权浏览器请求、与受限域之间的请求，以及来自其他扩展的请求。

"declarativeNetRequestFeedback" 权限是使用 getMatchedRules 和 onRuleMatchedDebug 所必需的，因为它们返回有关匹配的声明性规则的信息。有关更多信息，请参见测试。

规则

声明性规则由四个字段定义

id – 在规则集中唯一标识规则的 ID。必须且应大于等于 1。
priority – 规则优先级。如果指定，则应大于等于 1。默认值为 1。有关优先级如何影响应用哪些规则的详细信息，请参见匹配优先级。
condition – 触发此规则的 condition。
action – 匹配规则时要采取的 action。规则可以执行以下操作之一
- 阻止网络请求。
- 重定向网络请求。
- 修改网络请求的标头。
- 阻止应用另一个匹配规则。

注意: 重定向操作不会重定向请求，并且当

操作未更改请求时，请求照常继续。
重定向 URL 无效时（例如，redirect.regexSubstitution 的值不是有效的 URL）。

这是一个阻止来自 "foo.com" 的所有脚本请求到任何包含 "abc" 作为子字符串的 URL 的示例规则

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 resourceTypes）具有与 allow 相同的效果，但也适用于从请求生成的文档（包括子级帧）中的未来子资源加载。
3. "block" 取消请求。
4. "upgradeScheme" 升级请求的方案。
5. "redirect" 重定向请求。
6. "modifyHeaders" 重写请求或响应头或两者。

注意： 当多个匹配规则具有相同的规则优先级和规则操作类型时，当匹配的操作支持其他属性时，结果可能不明确。这些属性会导致无法组合的结果。例如

"block" 操作不支持其他属性，因此没有歧义：所有匹配的 "block" 操作将导致相同的结果。
"redirect" 操作将请求重定向到一个目标。当多个 "redirect" 操作匹配时，除了一个 "redirect" 操作外，所有其他 "redirect" 操作都会被忽略。当重定向的请求匹配另一个规则条件时，仍然可以反复重定向。
当多个 "modifyHeaders" 操作触及不同的头时，可以独立地应用多个 "modifyHeaders" 操作。当它们触及相同头时，结果不明确，因为一些操作组合不允许（如declarativeNetRequest.ModifyHeaderInfo中所述）。因此，"modifyHeaders" 操作的评估顺序很重要。

要控制操作应用的顺序，为优先级顺序很重要的规则分配不同的priority值。

注意： 在规则优先级和规则操作之后，Firefox 会考虑规则所属的规则集，按以下优先级顺序：会话 > 动态 > 会话规则集。这不能在浏览器之间依赖，请参阅WECG 问题 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权限与declarativeNetRequest一起使用时，使用 declarativeNetRequest API 阻止或升级请求不需要主机权限。
declarativeNetRequest API 为用户提供了更好的隐私，因为扩展程序不会读取代表用户进行的网络请求。
（仅限 Chrome：）与 webRequest API 不同，使用 declarativeNetRequest API 阻止的任何图像或 iframe 都会在 DOM 中自动折叠。
在决定是否要阻止或重定向请求时，declarativeNetRequest API 优先于 webRequest API，因为它允许同步拦截。类似地，任何通过 declarativeNetRequest API 删除的头都不可见于 web 请求扩展程序。
webRequest API 比 declarativeNetRequest API 更灵活，因为它允许扩展程序以编程方式评估请求。

类型

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_INTERVALdeclarativeNetRequest.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" 权限调试扩展程序时，匹配请求的规则时触发。

示例扩展

浏览器兼容性

BCD 表仅在浏览器中加载