Chrome与Firefox Manifest V3背景脚本迁移及Parcel/web-ext兼容问题

核心问题拆解 #

• Chrome Manifest V3强制要求使用service_worker配置后台脚本
• Firefox当前Manifest V3仍依赖scripts字段（Preview/Beta版虽开始测试service_worker，但稳定版未全面支持）
• Parcel 2.x对Manifest V3的校验严格，仅认可service_worker；而web-ext 7.x在未启用service_worker的Firefox环境下会抛出service_worker is currently disabled错误

可行解决方案 #

1. 升级工具版本 #

先尝试更新web-ext到最新稳定版，旧版本可能未适配Firefox Preview对service_worker的默认支持：

npm install web-ext@latest --save-dev

更新后重新执行web-ext run --firefox-preview，确认报错是否消失。

2. 分浏览器构建专属Manifest #

由于工具校验规则冲突，最可靠的方式是生成两个Manifest文件，分别适配Chrome和Firefox：

步骤1：创建基础模板

在src目录下新建manifest.base.json，存放通用配置：

{
  "manifest_version": 3,
  "name": "你的扩展名称",
  "version": "1.0.0",
  "permissions": ["storage"],
  // 其他通用配置（如action、icons等）
}

步骤2：创建浏览器专属配置

• src/manifest.chrome.json（适配Chrome）：

{
  "background": {
    "service_worker": "background.js"
  }
}

• src/manifest.firefox.json（适配Firefox）：

{
  "background": {
    "scripts": ["background.js"],
    "type": "module"
  }
}

步骤3：编写合并脚本

在项目根目录创建build-manifest.js：

const fs = require('fs');
const path = require('path');

const target = process.argv[2] || 'chrome';
const baseManifest = require('./src/manifest.base.json');
const targetManifest = require(`./src/manifest.${target}.json`);

const finalManifest = {...baseManifest, ...targetManifest};

fs.writeFileSync(
  path.join(__dirname, 'src/manifest.json'),
  JSON.stringify(finalManifest, null, 2)
);

步骤4：更新package.json命令

{
  "scripts": {
    "build:chrome": "node build-manifest.js chrome && parcel build src/manifest.json --dist-dir dist/chrome --no-cache",
    "build:firefox": "node build-manifest.js firefox && parcel build src/manifest.json --dist-dir dist/firefox --no-cache",
    "watch:chrome": "node build-manifest.js chrome && parcel watch src/manifest.json --dist-dir dist/chrome --no-cache --no-hmr",
    "start:firefox": "node build-manifest.js firefox && web-ext run --firefox-preview --source-dir dist/firefox"
  }
}

执行对应命令即可生成适配不同浏览器的扩展包，规避工具校验冲突。

3. 临时禁用Parcel的Manifest校验（应急方案） #

若不想分环境构建，可通过Parcel配置跳过Manifest字段校验：
在项目根目录创建.parcelrc：

{
  "extends": "@parcel/config-webextension",
  "validators": {
    "manifest.json": false
  }
}

此方法会跳过所有Manifest配置校验，可能隐藏其他错误，仅作为临时应急使用。

补充说明 #

• Chrome已明确2024年6月终止V2扩展支持，Chrome版本必须使用service_worker
• Firefox稳定版预计2024年全面支持Manifest V3的service_worker，届时可统一配置无需分环境

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