跳转到主要内容
通过显式提供二进制路径，运行除默认具名目标之外的 Chromium 与 Gecko 家族浏览器。 在同一套 Extension.js 工作流中测试自定义浏览器二进制（例如 Brave、Vivaldi 或 Waterfox）。可在 dev、start 与 preview 中使用二进制 flag 与 extension.config.*。

​
工作原理

使用以下任一 flag：
  • --chromium-binary <path>
  • --gecko-binary <path>（别名：--firefox-binary <path>）
无论你选择了哪个具名浏览器目标，这些二进制 flag 都会覆盖 Extension.js 实际启动的浏览器二进制。

​
二进制能力

选项 / 键作用
--chromium-binary <path>启动自定义的 Chromium 家族浏览器二进制。
--gecko-binary <path>启动自定义的 Gecko 家族浏览器二进制。
--firefox-binary <path>--gecko-binary 的别名。
browser.<target>.chromiumBinary在配置中设置默认的自定义 Chromium 二进制。
browser.<target>.geckoBinary在配置中设置默认的自定义 Gecko 二进制。
commands.<name>.chromiumBinary为特定命令设置自定义 Chromium 二进制。
commands.<name>.geckoBinary为特定命令设置自定义 Gecko 二进制。

​
CLI 示例

extension dev --browser=chromium-based --chromium-binary="/path/to/brave"

extension dev --browser=firefox --gecko-binary="/path/to/firefox-developer-edition"
它们也可以与 start 和 preview 搭配使用。

​
在 extension.config.* 中配置

export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    "gecko-based": {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};
你也可以把二进制路径放在命令块中： 
export default {
  commands: {
    dev: {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    preview: {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};

​
目标映射行为

二进制提示会映射到引擎目标：
  • chromiumBinary → chromium-based
  • geckoBinary / firefoxBinary → gecko-based
如果两者都提供，Extension.js 会先解析 Chromium 二进制。

​
可用浏览器

可通过二进制 flag 运行的常见浏览器：
浏览器名称类型CLI flag官方网站
BraveChromium-based 浏览器--chromium-binarybrave.com
OperaChromium-based 浏览器--chromium-binaryopera.com
VivaldiChromium-based 浏览器--chromium-binaryvivaldi.com
WaterfoxGecko-based 浏览器--gecko-binaryWaterfox
Firefox Developer EditionGecko-based 浏览器--gecko-binaryfirefox.com

​
重要约束

  • chromium-based 需要一个有效的 chromiumBinary 路径。
  • gecko-based / firefox-based 需要一个有效的 geckoBinary 路径。
  • 无效路径会以清晰的 CLI / 运行时错误立即失败。
  • build 不接受二进制 flag。基于二进制的启动只能配合 dev、start 与 preview 使用。

​
最佳实践

  • 二进制与显式浏览器目标搭配：使用 --browser=chromium-based 或 --browser=gecko-based，让意图更可预期。
  • 使用绝对路径：避免与 shell 相关的路径解析问题。
  • 在 CI runner 上锁定版本：让浏览器二进制路径在自动化检查中保持确定性。
  • 谨慎与 profile / flag 组合：复用与具名浏览器目标相同的 profile 与 flag 策略。

​
下一步