Chrome 迁移到 Manifest V3 后扩展如何使用 declarativeNetRequest：规则集更新与权限边界

把 Chrome 扩展从 Manifest V2 迁到 Manifest V3 时，最容易卡住的地方不是把 background 改成 service worker，而是原来依赖 webRequestBlocking 的网络规则没有了直接平替。现在更稳妥的做法，是把“匹配什么请求、采取什么动作”写成 declarativeNetRequest 规则交给浏览器评估，再用 updateDynamicRules 管理确实需要运行时变化的部分。

如果扩展只需要拦截或升级请求，先采用 declarativeNetRequest；只有重定向、改请求头等场景，才继续核对 host_permissions，不要把所有站点权限一并放进清单。

Manifest V3 为什么把网络规则交给 declarativeNetRequest

Manifest V3 的变化有两个相互关联的方向：后台上下文改为按需唤醒的 service worker，远程托管代码不再允许由扩展运行；网络请求修改则从“每次请求通知扩展进程”转向“浏览器根据声明式规则直接评估”。这降低了扩展长期占用资源和读取用户网络请求的机会，但也意味着规则不能再随意用 JavaScript 临场计算。

对迁移项目来说，先把需求分成两类更实际：阻止、升级 HTTPS 这类规则通常可以直接落到 declarativeNetRequest；重定向、修改请求头则要同时核对请求 URL 和 initiator 的访问范围。MDN 对权限提示和 host permissions 的区分写得很清楚，不能只看规则本身能否载入。

最小规则集：从 manifest.json 到第一次请求匹配

先用静态规则验证迁移方向。目录中准备 manifest.json 和 rules.json，清单只声明必要权限：

{
  "manifest_version": 3,
  "name": "Request Guard",
  "version": "1.0.0",
  "permissions": ["declarativeNetRequest"],
  "declarative_net_request": {
    "rule_resources": [{
      "id": "ruleset_main",
      "enabled": true,
      "path": "rules.json"
    }]
  }
}

rules.json 只做一个容易验收的动作，例如阻止指定域名下的图片请求：

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

这里的 example.test 只是测试域名，不代表真实业务站点。加载未打包扩展后，用开发者工具 Network 面板观察匹配请求，再回到 chrome://extensions 的扩展详情确认没有额外权限提示。规则中的 id 必须在规则集内唯一，priority 至少为 1。

动态规则更新：updateDynamicRules 解决什么问题

静态规则适合随扩展版本发布的基线；用户在选项页增加过滤域名、或者策略服务下发小批量变更时，才需要动态规则。动态规则跨浏览器会话和扩展更新保持，代码要同时提供新增与删除的 id，避免每次更新都把历史规则叠加一遍。

const newRule = {
  id: 1001,
  priority: 1,
  action: { type: "block" },
  condition: {
    urlFilter: "||ads.example.test/",
    resourceTypes: ["script"]
  }
};

chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: [1001],
  addRules: [newRule]
});

这个写法的关键不是 API 调用本身，而是“先移除同 id，再添加新版本”的更新语义。生产扩展还应在回调或 Promise 结果中记录失败原因，并在选项页保留当前规则的可见状态。不要把服务端返回的任意 JSON 原样变成规则，至少先限制 action、resourceTypes、域名和规则数量。

host_permissions 什么时候必须补上

权限边界取决于动作，不取决于“我已经申请了 declarativeNetRequest”这一句话。阻止或升级请求通常可以只申请 declarativeNetRequest；如果规则要重定向，或者要修改请求头，就必须检查对应请求 URL 的 host permissions。除导航请求外，发起该请求的 initiator 也会影响权限判断。

权限越宽，用户越难判断扩展在做什么。迁移时可以先用最窄的域名和动作做一组未打包测试，再逐项增加范围。若某个需求必须依赖可编程判断，要重新评估它是否真的适合声明式规则，而不是偷偷保留旧的阻塞式拦截假设。

规则优先级与兼容处理别混在一起

同一扩展内，规则先按 priority 判断；动作类型也有明确的处理顺序。不要仅凭“动态规则一定覆盖静态规则”来写跨浏览器逻辑，MDN 已提示不同浏览器对规则集来源优先级的保证并不相同。兼容层更应该围绕结果写：在测试浏览器中调用可用的匹配测试能力，记录命中规则、最终动作和未命中的原因。

如果目标是 Chrome 扩展，回归表至少覆盖 Manifest V3 加载、静态规则命中、动态规则替换、扩展更新后规则是否仍在、权限提示是否收敛，以及重定向或改头场景下的 initiator 权限。只测“扩展能安装”是不够的，安装成功并不代表规则真的被浏览器接受。

常见问题

declarativeNetRequest 能完全替代 webRequest 吗？

不能。它适合声明式的阻止、升级、重定向和部分请求头修改；需要在每次请求到来时运行任意 JavaScript 判断的场景，仍要重新设计能力边界。

动态规则会在 Chrome 重启后消失吗？

动态规则设计为跨浏览器会话持久保存，也能跨扩展更新保留。仍应把规则版本和更新失败写入扩展自己的诊断记录，方便确认实际状态。

为什么规则载入了，但重定向没有发生？

先核对重定向动作需要的主机权限，再检查请求的 initiator、资源类型和规则优先级。只声明阻止请求所需的权限，不会自动获得重定向所需的权限。

迁移时要不要把所有 host_permissions 都加上？

不建议。按实际动作和域名收敛权限，先在未打包扩展中观察权限提示与规则命中，再逐步放大范围。

落地前的四项验收

• 清单验收：manifest.json 的规则集 id、路径和权限与需求一致。
• 行为验收：用 Network 面板确认阻止、升级或重定向确实发生，而不是只看扩展图标。
• 更新验收：重复调用 updateDynamicRules 后没有重复 id，扩展更新和浏览器重启后规则状态符合预期。
• 权限验收：针对重定向和请求头修改逐项核对 host_permissions 与 initiator，不用通配权限掩盖设计问题。

Manifest V3 的迁移重点，是把“脚本拦截请求”改成“浏览器按声明评估规则”。先用小规则集跑通，再逐项确认动态更新、权限和兼容边界，通常比直接搬运旧后台页更容易定位问题。