Firefox扩展修改请求头（User-Agent）失效问题求助

我正在开发一款Firefox基础扩展用于修改请求头，按照官方文档示例实现后无效，调整代码仍无法正常工作。已在manifest.json中申请了webRequest、webRequestBlocking、storage、tabs等权限，相关代码如下：

原manifest.json权限配置 #

{
  ...
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "storage",
    "tabs"
  ],
  ...
}

原background.js代码 #

let currentUserAgent = '';

function updateUserAgent(userAgent) {
  currentUserAgent = userAgent;
  console.log('User agent updated:', currentUserAgent); // 已输出日志
  console.log("Registering onBeforeSendHeaders event listener..."); // 已输出日志
  chrome.webRequest.onBeforeSendHeaders.addListener(
    handleRequest,
    { urls: ["<all_urls>"] },
    ["blocking", "requestHeaders"]
  );
  console.log(chrome.webRequest.onBeforeSendHeaders.hasListener(handleRequest)); // 输出true
}

function handleRequest(details) {
  console.log('Handling request:', details); // 无日志输出

  // 检查是否存在user-agent请求头
  const userAgentHeader = details.requestHeaders.find(header => header.name.toLowerCase() === 'user-agent');
  if (userAgentHeader) {
    console.log('User-Agent header found:', userAgentHeader.value); // 无日志输出
    userAgentHeader.value = currentUserAgent;
    console.log('User-Agent header updated:', userAgentHeader.value); // 无日志输出
  } else {
    console.log('User-Agent header not found in the request headers.'); // 无日志输出
  }

  return { requestHeaders: details.requestHeaders };
}

// 启动时获取保存的User-Agent
chrome.storage.local.get('userAgent', (data) => {
  updateUserAgent(data.userAgent || 'Default User Agent');
});

// 监听消息以更新User-Agent
chrome.runtime.onMessage.addListener(message => {
  if (message.action === 'updateUserAgent') {
    updateUserAgent(message.userAgent);
  }
});

尝试替换chrome为browser对象后问题依旧，通过Network面板和BurpSuite抓包验证，请求头并未被修改。

问题分析与修复步骤 #

1. 重复注册监听器引发异常

每次调用updateUserAgent都会重新添加onBeforeSendHeaders监听器，多次绑定同一回调会导致逻辑冲突，甚至让监听器无法正常触发。需将监听器注册逻辑移到初始化阶段，仅执行一次。

2. 缺少修改受保护请求头的必要参数

User-Agent属于浏览器标记为“受保护”的请求头，在Firefox中修改它必须在监听器的extraInfoSpec参数中添加"extraHeaders"，否则无法对该字段进行修改。

3. Manifest版本权限配置差异

如果使用Manifest V3，需将主机权限单独放在host_permissions字段中，不能与普通权限混写；Manifest V2则可直接将<all_urls>加入permissions数组。

修改后的代码示例 #

Manifest.json（Manifest V3）

{
  "manifest_version": 3,
  "permissions": ["webRequest", "webRequestBlocking", "storage"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  ...
}

Manifest.json（Manifest V2）

{
  "manifest_version": 2,
  "permissions": ["webRequest", "webRequestBlocking", "storage", "<all_urls>"],
  "background": {
    "scripts": ["background.js"]
  },
  ...
}

background.js

let currentUserAgent = '';

// 仅注册一次请求监听器
browser.webRequest.onBeforeSendHeaders.addListener(
  handleRequest,
  { urls: ["<all_urls>"] },
  ["blocking", "requestHeaders", "extraHeaders"] // 新增extraHeaders参数
);

function updateUserAgent(userAgent) {
  currentUserAgent = userAgent;
  console.log('User agent updated:', currentUserAgent);
}

function handleRequest(details) {
  console.log('Handling request:', details);
  if (!currentUserAgent) {
    return { requestHeaders: details.requestHeaders };
  }

  // 查找并修改User-Agent头
  const userAgentHeader = details.requestHeaders.find(header => header.name.toLowerCase() === 'user-agent');
  if (userAgentHeader) {
    userAgentHeader.value = currentUserAgent;
    console.log('Updated User-Agent:', userAgentHeader.value);
  } else {
    // 若请求中无User-Agent头，直接添加
    details.requestHeaders.push({ name: 'User-Agent', value: currentUserAgent });
    console.log('Added User-Agent:', currentUserAgent);
  }

  return { requestHeaders: details.requestHeaders };
}

// 初始化获取保存的User-Agent
browser.storage.local.get('userAgent', (data) => {
  updateUserAgent(data.userAgent || 'Default User Agent');
});

// 监听消息更新User-Agent
browser.runtime.onMessage.addListener((message) => {
  if (message.action === 'updateUserAgent') {
    updateUserAgent(message.userAgent);
  }
});

验证方法 #

1. 打开Firefox的扩展调试页面（about:debugging#/runtime/this-firefox），查看background脚本的控制台日志，确认handleRequest是否正常触发。
2. 通过浏览器Network面板或抓包工具，检查请求的User-Agent头是否已被修改。

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