如何编写Chrome与Firefox兼容的Manifest V3扩展？解决配置冲突

以下是几个无需符号链接、能让两款浏览器共用核心代码的实用方案：

方法1：分目录存放浏览器专属Manifest（最适合开发阶段） #

直接创建两个子目录分别存放Chrome和Firefox的Manifest，所有核心代码放在根目录，通过相对路径引用即可：

1. 在项目根目录下创建chrome和firefox两个子目录
2. 分别编写对应浏览器的manifest.json：
   • Chrome版（chrome/manifest.json）：

     {
       "manifest_version": 3,
       "name": "你的扩展名称",
       "version": "1.0",
       "background": {
         "service_worker": "../background.js"
       },
       "content_scripts": [
         {
           "matches": ["<all_urls>"],
           "js": ["../content.js"]
         }
       ],
       "action": {
         "default_popup": "../popup.html"
       }
     }
     

   • Firefox版（firefox/manifest.json）：

     {
       "manifest_version": 3,
       "name": "你的扩展名称",
       "version": "1.0",
       "background": {
         "scripts": ["../background.js"],
         "type": "module"
       },
       "content_scripts": [
         {
           "matches": ["<all_urls>"],
           "js": ["../content.js"]
         }
       ],
       "action": {
         "default_popup": "../popup.html"
       }
     }
     

3. 开发时，Chrome加载chrome目录作为扩展，Firefox加载firefox目录即可，所有核心代码共用根目录的文件，无需任何复制或链接操作。

方法2：用构建脚本动态生成Manifest（适合发布阶段） #

如果需要打包发布，可写一个简单的脚本根据目标浏览器生成对应的Manifest：

1. 先创建一个基础模板manifest.base.json，包含所有通用配置，背景部分用占位符：

   {
     "manifest_version": 3,
     "name": "你的扩展名称",
     "version": "1.0",
     "background": "{{BACKGROUND_CONFIG}}",
     "content_scripts": [
       {
         "matches": ["<all_urls>"],
         "js": ["content.js"]
       }
     ]
   }
   

2. 写一个Node.js脚本（build-manifest.js）替换占位符：

   const fs = require('fs');
   const baseManifest = fs.readFileSync('./manifest.base.json', 'utf8');
   
   // 生成Chrome版Manifest
   const chromeBackground = JSON.stringify({
     "service_worker": "background.js"
   });
   const chromeManifest = baseManifest.replace('{{BACKGROUND_CONFIG}}', chromeBackground);
   fs.writeFileSync('./chrome/manifest.json', chromeManifest);
   
   // 生成Firefox版Manifest
   const firefoxBackground = JSON.stringify({
     "scripts": ["background.js"],
     "type": "module"
   });
   const firefoxManifest = baseManifest.replace('{{BACKGROUND_CONFIG}}', firefoxBackground);
   fs.writeFileSync('./firefox/manifest.json', firefoxManifest);
   

3. 运行脚本即可生成两个浏览器的Manifest，后续打包时分别处理chrome和firefox目录即可。

方法3：单一Manifest兼容（利用浏览器注释差异） #

Firefox支持在Manifest中使用HTML注释，而Chrome会直接忽略，因此可以写一个包含两种配置的Manifest：

{
  "manifest_version": 3,
  "name": "你的扩展名称",
  "version": "1.0",
  // Chrome会读取这个配置
  "background": {
    "service_worker": "background.js"
  },
  <!-- Firefox会读取这个注释内的配置 -->
  <!--
  "background": {
    "scripts": ["background.js"],
    "type": "module"
  }
  -->,
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"]
    }
  ]
}

注意：这种方式需要测试兼容性，部分版本的浏览器可能存在解析差异，适合快速验证场景。

补充：背景脚本本身的环境适配 #

不管用哪种Manifest加载方式，背景脚本可以通过环境判断兼容两种模式：

// background.js
if ('ServiceWorkerGlobalScope' in self && self instanceof ServiceWorkerGlobalScope) {
  // Chrome Service Worker 逻辑
  self.addEventListener('install', () => {
    console.log('Chrome service worker installed');
  });
} else {
  // Firefox 背景脚本逻辑
  browser.runtime.onInstalled.addListener(() => {
    console.log('Firefox background script installed');
  });
}

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