如何在Manifest V3中使用阻塞式请求监听器？迁移求助

核心问题原因 #

Manifest V3 彻底移除了 webRequestBlocking 权限，同时不再支持 chrome.webRequest API 的阻塞式监听器（也就是你代码里的 ["blocking"] 参数）。要实现请求拦截/下载逻辑，必须改用声明式网络请求（Declarative Net Request, DNR） API。

步骤1：更新 Manifest.json 配置 #

1. 删掉 webRequest 权限，添加 DNR 相关权限
2. 新增 host_permissions，指定你的扩展需要匹配的 URL 模式（替代原来在 webRequest 监听器里的 urls 参数）
3. 保留原有的其他权限和配置即可

修改后的配置示例：

{
  "manifest_version": 3,
  "name": "你的扩展名称",
  "version": "1.0",
  "permissions": [
    "downloads",
    "notifications",
    "storage",
    "declarativeNetRequest",
    "declarativeNetRequestFeedback" // 用于监听规则匹配事件，触发下载
  ],
  "host_permissions": [
    "<all_urls>" // 替换成你需要匹配的特定URL，比如 "*://*.example.com/*"
  ],
  "background": {
    "service_worker": "background.js"
  },
  "options_page": "options.html"
}

步骤2：替换阻塞式监听器代码 #

根据你的需求选对应的方案：

方案A：需要拦截并取消原请求 + 触发下载

用 DNR 动态规则拦截请求，再监听匹配事件启动下载：

// background.js
// 初始化动态规则：拦截目标URL并取消原请求
chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: [1], // 先移除已存在的同名规则（避免重复）
  addRules: [
    {
      id: 1,
      priority: 1,
      action: { type: "cancel" }, // 取消原请求
      condition: {
        urlFilter: "*://*.example.com/*", // 替换成你的目标URL模式
        resourceTypes: ["all"] // 可按需指定资源类型，比如 ["image", "xmlhttprequest"]
      }
    }
  ]
});

// 监听规则匹配事件，触发下载
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener((details) => {
  const targetUrl = details.request.url;
  chrome.downloads.download({ url: targetUrl })
    .catch(err => console.error("下载失败：", err));
});

方案B：仅监听请求并触发下载（不拦截原请求）

如果不需要取消原请求，直接用非阻塞的 webRequest 监听器就行（不用DNR）：

// background.js
chrome.webRequest.onBeforeRequest.addListener(
  (details) => {
    chrome.downloads.download({ url: details.url })
      .catch(err => console.error("下载失败：", err));
  },
  { urls: ["*://*.example.com/*"] }, // 替换成你的目标URL模式
  [] // 千万不要加 "blocking" 参数
);

额外注意点 #

• V3 的 Service Worker 是无状态的，如果规则需要根据用户配置动态调整，要结合 chrome.storage 存配置，在 Service Worker 启动时加载对应规则
• declarativeNetRequestFeedback 权限只是用来监听匹配事件的，如果你的逻辑不需要触发下载以外的操作，可以根据情况调整
• 固定不变的规则也可以写成静态规则（在 manifest 里通过 rule_resources 声明），动态规则更适合需要实时调整的场景

内容的提问来源于stack exchange，提问作者Felix D.