Firefox插件发布报错：/background格式不支持问题排查

问题描述 #

发布Firefox插件时触发错误：Error: "/background" is in an unsupported format。原本以为是Manifest V2迁移到V3的问题，但报错指向background字段，不确定是否需要创建background文件夹，或是存在其他配置问题。

当前文件结构 #

┣ 📂.vscode
 ┃ ┗ 📜settings.json
 ┣ 📂css
 ┃ ┣ 📜options.css
 ┃ ┗ 📜popup.css
 ┣ 📂html
 ┃ ┣ 📜options.html
 ┃ ┗ 📜popup.html
 ┣ 📂icons
 ┃ ┣ 📂128
 ┃ ┃ ┣ 📜error.png
 ┃ ┃ ┣ 📜operational.png
 ┃ ┃ ┗ 📜warning.png
 ┃ ┣ 📂feather
 ┃ ┃ ┣ 📜help-circle.svg
 ┃ ┃ ┣ 📜refresh-cw.svg
 ┃ ┃ ┗ 📜settings.svg
 ┃ ┣ 📜.DS_Store
 ┃ ┣ 📜green_icon.png
 ┃ ┣ 📜red_icon.png
 ┃ ┗ 📜yellow_icon.png
 ┣ 📂js
 ┃ ┣ 📂node_modules
 ┃ ┃ ┣ 📂@types
 ┃ ┃ ┃ ┗ 📂firefox-webext-browser
 ┃ ┃ ┃ ┃ ┣ 📜LICENSE
 ┃ ┃ ┃ ┃ ┣ 📜README.md
 ┃ ┃ ┃ ┃ ┣ 📜index.d.ts
 ┃ ┃ ┃ ┃ ┗ 📜package.json
 ┃ ┃ ┗ 📜.package-lock.json
 ┃ ┣ 📜common.js
 ┃ ┣ 📜options.js
 ┃ ┣ 📜package-lock.json
 ┃ ┣ 📜package.json
 ┃ ┣ 📜popup.js
 ┃ ┗ 📜test.js
 ┣ 📜.DS_Store
 ┣ 📜LICENSE
 ┣ 📜README.md
 ┣ 📜jsconfig.json
 ┗ 📜manifest.json

当前manifest.json配置 #

{
  "manifest_version": 3,
  "name": "GPTstatus",
  "version": "1.0",

  "browser_specific_settings": {
    "gecko": {
      "id": "gptstatus@example.org"
    }
  },

  "description": "A browser extension that changes its icon depending on the status of ChatGPT.",
  "homepage_url": "https://github.com/Zev18/gptstatus",
  "icons": {
    "128": "icons/128/operational.png"
  },

  "action": {
    "default_icon": "icons/128/operational.png",
    "default_title": "GPTstatus",
    "default_popup": "html/popup.html"
  },

  "background": {
    "service_worker": "js/common.js"
  },

  "options_ui": {
    "page": "html/options.html",
    "browser_style": true
  },

  "permissions": ["storage", "tabs"]
}

问题分析与解决方案 #

不需要创建background文件夹，当前文件结构无问题，错误根源在于Manifest V3与Firefox的兼容性及配置细节：

1. Firefox版本要求
   Firefox 109及以上版本才正式支持Manifest V3的service_worker字段。若你的Firefox版本低于此，会因无法识别该字段报错。解决方式二选一：

   • 升级Firefox至109或更高版本；
   • 回退到Manifest V2：将manifest_version改为2，同时把background字段修改为V2格式：

     "background": {
       "scripts": ["js/common.js"]
     }
     

2. 完善Gecko配置
   在browser_specific_settings.gecko中添加最低版本限制，明确插件依赖的Firefox版本，避免低版本浏览器加载出错：

   "browser_specific_settings": {
     "gecko": {
       "id": "gptstatus@example.org",
       "strict_min_version": "109.0"
     }
   }
   

3. 验证Service Worker脚本
   确保js/common.js是合法的Service Worker脚本：

   • 不能包含DOM操作（Service Worker运行在无DOM环境中）；
   • 若原脚本包含Popup/Options页面的DOM逻辑，需拆分代码，将后台逻辑单独放在Service Worker中，DOM相关代码保留在对应页面的脚本里。

4. 清理冗余文件
   发布插件时，需排除.vscode、node_modules、.DS_Store等开发无关文件，避免打包后路径混乱或文件冗余引发错误。

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