news 2026/8/5 19:06:29

WebExtensions开发进阶：Declarative Net Request API拦截网络请求实战

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
WebExtensions开发进阶：Declarative Net Request API拦截网络请求实战

WebExtensions开发进阶：Declarative Net Request API拦截网络请求实战

【免费下载链接】webextensionsCharter and administrivia for the WebExtensions Community Group (WECG)项目地址: https://gitcode.com/gh_mirrors/we/webextensions

Declarative Net Request API是WebExtensions开发中的强大工具，它允许开发者通过声明式规则来拦截和修改网络请求。本文将为你提供一个完整的实战指南，帮助你快速掌握这一API的使用方法。

一、什么是Declarative Net Request API？

Declarative Net Request API是WebExtensions API的一部分，它提供了一种声明式的方式来拦截和修改网络请求。与传统的webRequest API相比，它具有更高的性能和更强的安全性。

使用Declarative Net Request API，开发者可以定义一系列规则，这些规则会被浏览器高效地执行。这些规则可以用于阻止广告、跟踪器，修改请求头，重定向请求等。

二、开始使用Declarative Net Request API

2.1 配置manifest.json

要使用Declarative Net Request API，首先需要在manifest.json中添加相应的权限和配置。

{ "manifest_version": 3, "name": "我的网络请求拦截器", "version": "1.0", "permissions": ["declarativeNetRequest", "declarativeNetRequestWithHostAccess"], "declarative_net_request": { "rule_resources": [ { "id": "ruleset_1", "enabled": true, "path": "rules.json" } ] } }

在这个配置中，我们声明了需要使用的权限，并定义了一个规则集。规则集包含一个唯一的ID、是否启用以及规则文件的路径。

2.2 创建规则文件

接下来，我们需要创建规则文件。在上面的配置中，我们指定了规则文件的路径为"rules.json"。下面是一个简单的规则文件示例：

[ { "id": 1, "priority": 1, "condition": { "urlFilter": "||example.com/*", "resourceTypes": ["script", "image"] }, "action": { "type": "block" } } ]

这个规则会阻止所有来自example.com的脚本和图片请求。

三、规则的结构和类型

3.1 规则的基本结构

每个规则由以下几个部分组成：

  • id: 规则的唯一标识符，必须是大于等于1的整数。
  • priority: 规则的优先级，默认为1，数值越大优先级越高。
  • condition: 规则的触发条件。
  • action: 当规则被触发时执行的操作。

3.2 条件(condition)的属性

条件部分可以包含以下属性：

  • urlFilter: 用于匹配请求URL的模式。
  • regexFilter: 用于匹配请求URL的正则表达式。
  • isUrlFilterCaseSensitive: urlFilter或regexFilter是否区分大小写。
  • initiatorDomains: 规则仅匹配来自这些域名的请求。
  • excludedInitiatorDomains: 规则不匹配来自这些域名的请求。
  • requestDomains: 规则仅匹配这些域名的请求。
  • excludedRequestDomains: 规则不匹配这些域名的请求。
  • resourceTypes: 规则匹配的资源类型列表。
  • excludedResourceTypes: 规则不匹配的资源类型列表。
  • requestMethods: 规则匹配的HTTP请求方法列表。
  • excludedRequestMethods: 规则不匹配的HTTP请求方法列表。
  • domainType: 指定请求是第一方还是第三方。
  • tabIds: 规则匹配的标签ID列表。
  • excludedTabIds: 规则不匹配的标签ID列表。

3.3 操作(action)的类型

操作类型包括：

  • block: 阻止请求。
  • redirect: 重定向请求。
  • allow: 允许请求。
  • upgradeScheme: 将HTTP请求升级为HTTPS。
  • modifyHeaders: 修改请求头或响应头。
  • allowAllRequests: 允许所有请求。

四、动态规则和会话规则

除了在manifest.json中定义的静态规则外，Declarative Net Request API还支持动态规则和会话规则。

4.1 动态规则

动态规则可以在运行时添加和删除，并且会在浏览器会话之间保持。使用updateDynamicRules方法可以更新动态规则：

chrome.declarativeNetRequest.updateDynamicRules({ removeRuleIds: [1, 2], addRules: [ { id: 3, priority: 1, condition: { urlFilter: "||example.net/*", resourceTypes: ["script"] }, action: { type: "block" } } ] }, () => { console.log("动态规则已更新"); });

4.2 会话规则

会话规则也可以在运行时添加和删除，但不会在浏览器会话之间保持。使用updateSessionRules方法可以更新会话规则：

chrome.declarativeNetRequest.updateSessionRules({ removeRuleIds: [3], addRules: [ { id: 4, priority: 2, condition: { urlFilter: "||example.org/*", resourceTypes: ["image"] }, action: { type: "block" } } ] }, () => { console.log("会话规则已更新"); });

五、高级用法：修改请求头和响应头

Declarative Net Request API不仅可以阻止和重定向请求，还可以修改请求头和响应头。下面是一个修改请求头的示例：

{ "id": 5, "priority": 1, "condition": { "urlFilter": "||example.com/*", "resourceTypes": ["main_frame"] }, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "User-Agent", "operation": "set", "value": "My Custom User Agent" } ] } }

这个规则会将所有访问example.com的主框架请求的User-Agent头设置为"My Custom User Agent"。

六、测试和调试规则

为了帮助开发者测试和调试规则，Declarative Net Request API提供了testMatchOutcome方法。这个方法可以检查一个假设的请求是否会被任何规则匹配：

chrome.declarativeNetRequest.testMatchOutcome({ url: "https://example.com/script.js", type: "script" }, (result) => { console.log("匹配的规则:", result.matchedRules); });

此外，API还提供了isRegexSupported方法来检查一个正则表达式是否被支持：

chrome.declarativeNetRequest.isRegexSupported({ regex: "^https://example\\.com/.*$" }, (result) => { if (result.isSupported) { console.log("正则表达式被支持"); } else { console.log("正则表达式不被支持，原因:", result.reason); } });

七、性能和限制

虽然Declarative Net Request API非常强大，但也有一些性能考虑和限制需要注意：

  • 静态规则、动态规则和会话规则都有各自的数量限制。
  • 正则表达式规则也有数量限制，并且某些复杂的正则表达式可能不被支持。
  • 规则的优先级很重要，高优先级的规则会覆盖低优先级的规则。

关于具体的限制数值，可以参考API的属性，如MAX_NUMBER_OF_STATIC_RULESETS、MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES等。

八、总结

Declarative Net Request API为WebExtensions开发者提供了一种高效、安全的方式来拦截和修改网络请求。通过本文的介绍，你应该已经掌握了该API的基本使用方法和一些高级技巧。

无论是开发广告拦截器、隐私保护工具，还是其他需要控制网络请求的扩展，Declarative Net Request API都是一个非常有价值的工具。希望本文能够帮助你更好地利用这一API，开发出功能强大的WebExtensions扩展。

要开始使用Declarative Net Request API，你可以克隆WebExtensions项目仓库：https://gitcode.com/gh_mirrors/we/webextensions，其中包含了丰富的API文档和示例代码，如接口定义文件interfaces/firefox/schemas/declarative_net_request.json。

祝你在WebExtensions开发的道路上取得成功！🚀

【免费下载链接】webextensionsCharter and administrivia for the WebExtensions Community Group (WECG)项目地址: https://gitcode.com/gh_mirrors/we/webextensions

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/8/5 19:06:05

3步实现STL到STEP格式转换：免费工具stltostp让3D设计数据无缝流通

3步实现STL到STEP格式转换：免费工具stltostp让3D设计数据无缝流通 【免费下载链接】stltostp Convert stl files to STEP brep files 项目地址: https://gitcode.com/gh_mirrors/st/stltostp 你是否曾经遇到过这样的困境：从3D扫描仪获得的STL文件…

作者头像 李华
网站建设 2026/8/5 19:01:34

基于Python的咖啡销售及数据分析系统

一、关键词咖啡销售、咖啡商品管理、订单管理、销售数据分析二、作品包含源码数据库全套环境和工具资源本地部署教程三、项目技术前端技术： Html、Css、Js、Vue3.2、Element-Plus后端技术：Python、Django四、运行环境（以下版本亲测&#xff0…

作者头像 李华
网站建设 2026/8/5 19:00:28

GetQzonehistory：永久保存QQ空间回忆的终极免费备份工具

GetQzonehistory：永久保存QQ空间回忆的终极免费备份工具 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory 你是否曾翻看多年前的QQ空间说说，那些记录着青春点滴的文…

作者头像 李华
网站建设 2026/8/5 18:59:53

2025终极语音转文字指南：Buzz离线转录工具从入门到精通

2025终极语音转文字指南：Buzz离线转录工具从入门到精通 【免费下载链接】buzz Buzz transcribes and translates audio offline on your personal computer. Powered by OpenAIs Whisper. 项目地址: https://gitcode.com/GitHub_Trending/buz/buzz 还在为会议…

作者头像 李华
网站建设 2026/8/5 18:59:08

SynCamVideo Dataset深度解析：Unreal Engine 5打造的多视角视频金矿

SynCamVideo Dataset深度解析：Unreal Engine 5打造的多视角视频金矿 【免费下载链接】SynCamMaster [ICLR25] SynCamMaster: Synchronizing Multi-Camera Video Generation from Diverse Viewpoints 项目地址: https://gitcode.com/gh_mirrors/sy/SynCamMaster …

作者头像 李华
网站建设 2026/8/5 18:58:50

LGTV Companion终极指南：10个技巧实现PC与OLED电视智能联动

LGTV Companion终极指南：10个技巧实现PC与OLED电视智能联动 【免费下载链接】LGTVCompanion Power On and Off WebOS LG TVs together with your PC 项目地址: https://gitcode.com/gh_mirrors/lg/LGTVCompanion 你是否正在使用LG OLED电视作为PC显示器&…

作者头像 李华