WebExtension捕获响应头报错：TypeError: browser.webRequest.onHeaderReceived未定义

咱们先拆解你遇到的两个核心问题：TypeError: browser.webRequest.onHeaderReceived is undefined，还有响应头输出成[object Object]的情况，一个个来解决：

一、为什么会出现browser.webRequest.onHeaderReceived is undefined？ #

这个错误主要来自三个常见原因：

1. 扩展权限未正确配置 #

webRequest API需要在manifest.json里明确声明权限，同时还要指定你要监听的网址范围。比如：

{
  "manifest_version": 3, // 若用Manifest V2则写2
  "name": "响应头捕获工具",
  "version": "1.0",
  "background": {
    "service_worker": "background.js" // Manifest V3用service_worker，V2用scripts字段
  },
  "permissions": [
    "webRequest",
    "<all_urls>" // 也可指定特定网址，比如"*://*.example.com/*"
  ]
}

如果没配置这些权限，浏览器会限制你的扩展访问webRequest相关API，自然就会出现“未定义”的错误。

2. 浏览器API兼容性问题 #

Chrome等Chromium系浏览器原生支持的是chrome.webRequest而非browser，只有Firefox等少数浏览器原生兼容browser命名空间。要跨浏览器适配的话，可以这样处理：

// 自动适配浏览器API
const webRequest = browser?.webRequest || chrome.webRequest;
webRequest.onHeaderReceived.addListener(...)

3. 监听代码放错了位置 #

webRequest API只能在**后台脚本（background script/service worker）**中使用，不能放在内容脚本（content script）里——内容脚本的权限被严格限制，无法调用这类浏览器级别的API。一定要把监听响应头的代码移到后台脚本中。

二、为什么响应头输出成[object Object]？ #

onHeaderReceived回调里的responseHeaders是一个对象数组，每个对象包含name和value属性，直接用字符串拼接的话，JavaScript会默认把对象转为[object Object]。你需要遍历数组或者用JSON.stringify格式化输出：

示例代码（background.js）：

// 先处理API兼容性
const webRequest = browser?.webRequest || chrome.webRequest;

webRequest.onHeaderReceived.addListener(
  (details) => {
    // 逐个输出响应头键值对
    console.log("响应头详情：");
    details.responseHeaders.forEach(header => {
      console.log(`${header.name}: ${header.value}`);
    });
    // 或者转成格式化的JSON查看完整结构
    console.log("完整响应头JSON:", JSON.stringify(details.responseHeaders, null, 2));
  },
  { urls: ["<all_urls>"] }, // 指定要监听的网址范围
  ["responseHeaders"] // Manifest V3必须明确指定这个参数，才能获取响应头
);

注意：Manifest V3中，addListener的第三个参数（extraInfoSpec）必须明确写["responseHeaders"]，否则无法拿到响应头数据。

最后验证步骤 #

1. 检查manifest.json的权限、后台脚本配置是否正确
2. 把监听代码移到后台脚本，处理好API兼容性
3. 重新加载扩展，访问目标网站后查看控制台输出

这样应该就能解决你的问题啦！

内容的提问来源于stack exchange，提问作者user9371654