declarativeNetRequest API 拦截广告和跟踪器。你声明匹配规则,浏览器在请求离开网络栈之前原生地拦截它们。
你要构建什么
为什么 MV3 用它取代了阻塞式 webRequest
Manifest V2 的广告拦截器注册阻塞式webRequest 监听器。每个请求都要暂停,等扩展的 JavaScript 决定它的去留。出于性能和隐私考虑,Manifest V3 移除了这种模型。使用 declarativeNetRequest 时,浏览器自己求值你的规则。你的代码从不站在请求路径上,也从不为了拦截而读取请求内容。
对于代理类的用例,比如把所有流量路由到另一台服务器,请改用 proxy API 而不是请求规则。
Manifest
拦截和放行规则不需要 host 权限。重定向规则和 header 规则需要受影响站点的 host 权限。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 模板自带一个后台脚本和一个工具栏 popup,是拦截器 UI 的好起点。
最佳实践
- 静态规则放在
rules.json里,动态规则留给用户的选择。 - 给每条动态规则一个稳定的 id,让移除保持可预期。
- 把
resourceTypes收窄到你实际拦截的类型,而不是所有类型。 - 优先使用拦截和放行规则,它们不需要 host 权限。
- 发布过滤器更新之前,先在真实页面上测试规则。
下一步
- 在拦截网络请求中观察流量而不拦截它。
- 用安全检查清单审查你的权限面。
- 回顾 Manifest V3 概念了解后台模型。

