dev、start 与 preview 中通过二进制 flag 与 extension.config.* 指向任意自定义二进制。
按名称运行分支
这些分支是一等公民的浏览器目标。把名称传给--browser,Extension.js 会自动在你的系统上找到已安装的二进制,并通过其引擎家族的启动器运行:
chromium:/firefox: 前缀的字段会被正确解析(参见 按浏览器划分的 manifest 字段)。
dev、build、start 与 preview 的帮助输出都会列出全部分支名称。start
与 preview 的列表里没有 safari 和 webkit-based,因为这两个命令按设计就拒绝
Safari 目标。运行自定义二进制
要运行没有内置定位器的浏览器,或覆盖已定位到的二进制,请使用以下任一 flag:--chromium-binary <path>--gecko-binary <path>(别名:--firefox-binary <path>)
二进制能力
CLI 示例
start 和 preview 搭配使用。
按操作系统找到二进制路径
二进制 flag 期望的是一个可执行文件。无效的路径会立即以错误失败,而不会启动。macOS
在 macOS 上,/Applications/Brave Browser.app 这样的 app 是一个文件夹,不是可执行文件。请传入 bundle 内部 Contents/MacOS 下的可执行文件:
Windows
给路径加引号并使用正斜杠,所有 shell 都接受这种写法:C:\\Program Files\\...。
Linux
传入你的包管理器安装的可执行文件:PATH 上时,运行 which brave-browser 打印它的路径。
在 extension.config.* 中配置
目标映射行为
二进制提示会映射到引擎目标:chromiumBinary→chromium-basedgeckoBinary/firefoxBinary→gecko-based
可用浏览器
带内置定位器的分支可按名称运行;其他任何浏览器则通过二进制 flag 运行:重要约束
-
chromium-based需要--chromium-binary(或配置中的chromiumBinary)。没有它,启动会直接以错误退出,不会回退到系统浏览器。 -
gecko-based/firefox-based需要一个有效的geckoBinary路径。 -
librewolf需要在每台机器上开启一次远程调试。LibreWolf 每次启动都会把devtools.debugger.remote-enabled重置为false,覆盖 Extension.js 创建的配置文件,因此启动前会检查~/.librewolf/librewolf.overrides.cfg(Windows 上为%USERPROFILE%\.librewolf\librewolf.overrides.cfg),缺少时会停止并给出需要加入的两行: - 无效路径会以清晰的 CLI / 运行时错误立即失败。
-
build不接受二进制 flag。基于二进制的启动只能配合dev、start与preview使用。
二进制变量
设置一个环境变量,可以在不改动配置的情况下用指定的二进制启动某个具名目标:
从 4.1.39 之后的版本起,每个浏览器都按同一个顺序解析二进制。先是 flag,然后是变量、受管理的二进制,最后是系统安装。
如果该路径不存在或无法运行,启动会以
E_BROWSER_BINARY_INVALID 失败,而不会静默回退。身份卡会写明选定二进制的那个变量,例如 (pinned with EDGE_BINARY)。见二进制如何选定。
不启动浏览器运行
有时候正确的浏览器数量是零,比如在容器里、通过 SSH,或者你自己驱动一个浏览器时。 给dev、start 或 preview 传 --no-browser:
(no-browser mode) 横幅,指出输出文件夹。
把那个 dist/<browser> 文件夹加载进你已经在运行的浏览器。在 Chromium 系浏览器中,开启开发者模式后在 chrome://extensions 选择 “Load unpacked”。加载的扩展会随保存持续更新。关于用 --wait 做就绪同步,见 dev。
要把它设为某个命令的默认行为,在配置中设置 noBrowser。CLI flag 优先于配置值:
退出注入的默认值
dev、start 与 preview 会向每个会话注入启动默认值。一个肉眼可见的默认值是深色外观。Chromium 目标会得到 --force-dark-mode 与 --enable-features=WebUIDarkMode flag。Gecko 目标会得到对应的深色 preferences。
要保留你的系统外观,把该 flag 列入 excludeBrowserFlags:
--force-dark-mode 会丢弃整个外观包,包括 Gecko 的 preferences。排除条目也按开关名匹配,所以 --enable-features 会移除 --enable-features=WebUIDarkMode。默认 flag 清单和完整排除规则见浏览器 flag。
最佳实践
- 二进制与显式浏览器目标搭配:使用
--browser=chromium-based或--browser=gecko-based,让意图更可预期。 - 使用绝对路径:避免与 shell 相关的路径解析问题。
- 在 CI runner 上锁定版本:让浏览器二进制路径在自动化检查中保持确定性。
- 谨慎与 profile / flag 组合:复用与具名浏览器目标相同的 profile 与 flag 策略。
下一步
- 进一步了解 浏览器 preferences。
- 进一步了解 浏览器 profile。

