选择合适的目标
工作原理
在dev、start、preview 与 build 中使用 --browser 来选择目标。
如果不指定浏览器,CLI 默认使用 chromium。
--browser 只接受下面这些值,可以单独使用,也可以用逗号分隔:
--browser=all 也被接受,它会展开为 chrome, edge, firefox。
从 4.2.0 起,空值(比如 --browser=,或 --browser=chrome, 中的空项)会以 E_UNSUPPORTED_BROWSER 和退出码 1 被拒绝,什么都不会运行。消息为 --browser got an empty value.,并列出可选的值。在 --output json 下,这次拒绝的状态为 usage。
safari(以及它的别名 webkit-based)是个例外:它是仅在 macOS 可用的目标,build 与 dev 支持它,preview 与 start 不支持。Safari 的 dev 会话会输出日志,并在保存后重载。详见 构建 Safari 扩展。
chromium-emulator(从 4.1.38 起)同样是一个 dev 目标:dev 会打开一个模拟的 Chromium,在网页中运行你的扩展;build 会写出 dist/chromium-emulator。start 与 preview 会以 E_UNSUPPORTED_BROWSER 拒绝它,因为这个页面要从 dev 服务器读取你的构建。详见 dev 命令中的“模拟的 Chromium”一节。
请求的目标 vs. 启动的二进制
你请求的浏览器决定产物。二进制只是运行时。 当你运行extension dev --browser=chromium 时,Extension.js 始终会:
- 把输出写到
dist/chromium(目录以请求的目标命名,绝不会以启动它的二进制命名)。 - 为请求的目标解析浏览器特定的 manifest 字段。
chrome 与 chromium,它会寻找另一个受管理的 Chromium 家族二进制(此前由 npx extension install 下载的),并改用它作为运行时:
- 请求
chromium但缺失:回退到受管理的 Chrome,再回退到受管理的 Edge。 - 请求
chrome但缺失:回退到受管理的 Chromium,再回退到受管理的 Edge。
npx extension install chromium。这条警告刻意不写出替代二进制的路径。请从 ready.json 的 binary 读取这个路径。输出目录与产出的 manifest 与没有回退时完全一致。
--browser=edge 运行的是什么
edge 永远不会换成另一个浏览器,它也没有固定版本的受管理副本。npx extension install edge 通过 Playwright 把 Microsoft Edge 安装到你的系统上。Extension.js 按这个顺序解析 Edge 二进制:
--chromium-binary中的路径(如果传入了)。EDGE_BINARY环境变量中的路径(如果设置了)。- 你系统上已安装的 Edge。
Edge <version> (system install)。什么都解析不到时,命令会打印安装指引(npx extension install edge)并以退出码 1 退出。缺失的 Edge 不会被静默替换成 Chromium。
如果一个 Chromium 窗口仍然让你意外,请读取 ready.json 的 binary。它指明实际启动的确切二进制,binaryProvenance 说明原因。请求的 chrome 或 chromium 可以借用一个受管理的家族二进制(见上文),但请求的 edge 不行。无论哪种情况,输出契约都成立:只有当 edge 是请求的目标时,dist/edge 才会存在。
二进制如何选定
从 4.1.39 之后的版本起,dev、start 和 preview 对每个浏览器都按同一个顺序解析二进制:
- flag:
--chromium-binary或--gecko-binary。 - 该浏览器的环境变量。
- 来自
npx extension install <browser>的受管理二进制。 - 系统安装。
变量和 flag 一样,是你做出的选择。变量指向不存在的路径或无法运行的文件时,启动会以
E_BROWSER_BINARY_INVALID 失败。运行绝不会跳过它去走下一步。
请求 chrome 时仍然会拒绝品牌版的系统 Chrome。指向品牌版 Chrome 的变量不会被采用,运行会继续使用受管理的二进制。
对 Firefox 来说,受管理这一步会优先选择稳定版。同一个缓存里的 nightly 只有在没有稳定版时才会运行,这时卡片会显示 Firefox Nightly。
二进制来源标签
ready.json 用 binaryProvenance 记录本次会话的二进制来自哪里:
身份卡上没有 Binary 行。它的 Browser 行只为你能处理的两种情况加上标注:
(pinned with <flag 或变量>) 写明是什么选定了二进制。当二进制来自你的系统时,chrome、chromium、edge 和 firefox 会打印 (system install)。受管理的二进制和具名分支没有任何标注。
Chromium 快照 vs 稳定版
受管理的chromium 安装是主干(tip-of-tree)快照,而不是稳定版发布。当系统上存在稳定版 Chromium 时,Extension.js 会自动切换过去,并打印一条带有退出方式的警告。设置 EXTENSION_PREFER_CHROMIUM_SNAPSHOT=true 可以继续使用缓存的快照。
在 Chromium 家族内部,这种替换是安全的:dist/chrome 与 dist/chromium 逐字节相同,因为 manifest 前缀是按引擎家族解析的,而不是按厂商。前缀规则见浏览器特定的 manifest 字段。
如果想预先安装受管理的二进制以获得可复现的运行结果,使用 npx extension install <browser> 或 npx extension install all(后者也涵盖 chromium)。
支持的浏览器
具名浏览器目标:
具名分支(从你的系统自动定位,无需二进制路径):
如果具名分支未安装,Extension.js 会带上安装指引退出。参见 运行其他浏览器。
基于引擎的目标(需要自定义二进制):
Extension.js 内部把
firefox-based 视为 Gecko 引擎目标。
移动端浏览器,例如 Samsung Internet、Android 版 Chrome 和 Android 版 Firefox,不是启动目标。请构建 Firefox 产物,并按照该浏览器自己的侧载流程操作。
引擎目标是干什么用的
chromium-based 与 gecko-based 针对的是一个引擎家族,而不是某一家厂商。
在 dev、start 与 preview 中,它们运行一个没有具名目标的二进制。比如一个 nightly 分支、一个内部构建,或者内置定位器不认识的某个分支。
在 build 中,它们为分发而存在,完全不涉及任何二进制:
extension build --browser=chromium-based把一个面向整个家族的通用产物写入dist/chromium-based。- 该产物会解析
chromium:manifest 前缀,读取.env.chromium-based,并设置EXTENSION_BROWSER=chromium-based。 - 把这一个包发给使用 Chrome、Brave、Edge 或任何其他 Chromium 分支的用户。
chrome、edge)。当一个产物应当服务整个家族时,选择引擎目标。见引擎目标对 build 意味着什么。
Safari 与其他 WebKit 目标
除了 Chromium 家族与 Firefox(Gecko 引擎),Extension.js 还可以在 macOS 上把你的扩展构建成一个 Safari 应用。
Safari 是一个 dev 与构建目标:支持
build 与 dev,但不支持 preview 与 start。dev 会转换你的扩展、签名并打开一个 app、输出日志,并在你于 Safari 设置中启用一次扩展之后,每次保存都重载。它需要 macOS 与完整的 Xcode app。完整工作流、要求以及如何在 Safari 中启用扩展,请参见 构建 Safari 扩展。
多浏览器选择
可以在一个命令中运行多个具名浏览器:--browser=chrome,edge,firefox)。
约束与行为
- 在会启动浏览器的命令(
dev、start、preview)中,chromium-based需要配合--chromium-binary;build不需要二进制。 gecko-based/firefox-based在同样的前提下需要配合--gecko-binary。- 基于引擎的目标会被路由到同样的 Chromium / Firefox 运行器,并具有引擎感知的行为。
- 作为
build目标时,引擎目标拥有独立的dist/<target>目录、.env.<target>解析、EXTENSION_BROWSER值与 manifest 前缀——见引擎目标对build意味着什么。
Firefox 构建会对仅 Chromium 可用的 API 发出警告
从 4.1.18 开始,面向 Gecko 目标的生产构建会扫描输出的 bundle,查找两种会被 addons-linter 报告为UNSUPPORTED_API 的调用:任何 manifest 版本上的 chrome.sidePanel.*,以及 Manifest V2 上的 chrome.action.*。每次命中都会打印一条点名文件的警告。构建仍然成功。
chrome.sidePanel?.setPanelBehavior() 这样的运行时防护仍然会触发警告。
从 4.1.39 之后的版本起,Firefox 永远执行不到的调用不会触发警告。这包括位于 if (chrome.sidePanel) 之后的调用、写成 chrome.sidePanel?.setPanelBehavior() 的调用,以及位于 typeof chrome.sidePanel !== "undefined" 检查之后的调用。Safari 的警告识别同样的防护,见 Safari。
运行时防护只能让构建警告安静下来。addons-linter 匹配的是对命名空间的静态读取,而不是实际运行的代码。只有基于 import.meta.env.EXTENSION_PUBLIC_BROWSER 的构建时分支才会把这个调用从 Firefox 的 bundle 里去掉,而这正是消除商店检查里 UNSUPPORTED_API 发现的办法。各目标上 EXTENSION_PUBLIC_BROWSER 的取值见环境变量。
最佳实践
- 日常迭代用具名浏览器:
chrome、edge与firefox是常规测试中最快的路径。 - 有意识地使用引擎模式:在验证自定义二进制或需要家族通用构建时选用
chromium-based/gecko-based。 - 每个浏览器保持 profile 隔离:减少调试时的跨浏览器状态泄漏。
- 配合按浏览器划分的字段:用带浏览器前缀的 manifest 键处理真正的行为差异。

