Skip to main content
用同一套 CLI 工作流，在主流浏览器上运行并测试你的扩展。 通过一套 CLI 在 Chrome、Edge、Firefox 与自定义浏览器二进制上对同一个扩展进行验证。 当你需要在同一个 Extension.js 项目中测试 Chrome 扩展、Firefox 扩展或 Edge 扩展时，请参考本页。

​
选择合适的目标

​
工作原理

在 dev、start、preview 与 build 中使用 --browser 来选择目标。 如果不指定浏览器，CLI 默认使用 chromium。 --browser 只接受下面这些值，可以单独使用，也可以用逗号分隔：
--browser=all 也被接受，它会展开为 chrome, edge, firefox。
开发时请优先使用 chromium（或通过 npx extension install chrome 安装的 Chrome for Testing），而不是品牌版 Chrome。较新的品牌版 Chrome 构建（150+）会丢弃 --load-extension 开关，除非有策略禁用该行为。被丢弃的开关 看起来和一次正常启动完全一样。当 Extension.js 无法确认加载成功时，它会发出警告， 并指引你去 chrome://extensions。
safari（以及它的别名 webkit-based）是个例外：它是仅在 macOS 可用的构建目标，仅 build 与 dev 支持——不支持 preview 或 start。详见 构建 Safari 扩展。

​
请求的目标 vs. 启动的二进制

你请求的浏览器决定产物。二进制只是运行时。 当你运行 extension dev --browser=chromium 时，Extension.js 始终会：
  • 把输出写到 dist/chromium（目录以请求的目标命名，绝不会以启动它的二进制命名）。
  • 为请求的目标解析浏览器特定的 manifest 字段。
如果请求的浏览器没有安装，Extension.js 不会改变目标。对于 chrome 与 chromium，它会寻找另一个受管理的 Chromium 家族二进制（此前由 npx extension install 下载的），并改用它作为运行时：
  • 请求 chromium 但缺失：回退到受管理的 Chrome，再回退到受管理的 Edge。
  • 请求 chrome 但缺失：回退到受管理的 Chromium，再回退到受管理的 Edge。
发生这种情况时，CLI 会打印一条警告，说明缺失的浏览器以及修复方式，例如 npx extension install chromium。这条警告刻意不写出替代二进制的路径。会话的身份卡片里已经有一行 Binary 指明正在使用的确切二进制，所以这个事实只打印一次。输出目录与产出的 manifest 与没有回退时完全一致。

​
没有受管理 Edge 时 --browser=edge 会做什么

edge 永远不会换成另一个浏览器。Extension.js 按这个顺序解析 Edge 二进制：
  1. EDGE_BINARY 环境变量中的路径(如果设置了)。
  2. 来自 npx extension install edge 的受管理 Edge，或你系统上已安装的 Edge。
当两者都解析不到时，命令会打印安装指引(npx extension install edge)并以退出码 1 退出。缺失的 Edge 不会被静默替换成 Chromium。 如果一个 Chromium 窗口仍然让你意外，请查看身份卡片。它的 Binary 行指明实际启动的确切二进制，来源标签说明原因。请求的 chrome 或 chromium 可以借用一个受管理的家族二进制(见上文)，但请求的 edge 不行。无论哪种情况，输出契约都成立：只有当 edge 是请求的目标时，dist/edge 才会存在。

​
二进制来源标签

身份卡片会标注本次会话的二进制来自哪里：

​
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 引擎目标。

​
引擎目标是干什么用的

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 分支的用户。
当商店构建需要厂商特定的 manifest 字段时，选择具名目标(chrome、edge)。当一个产物应当服务整个家族时，选择引擎目标。见引擎目标对 build 意味着什么。

​
Safari 与其他 WebKit 目标

除了 Chromium 家族与 Firefox（Gecko 引擎），Extension.js 还可以在 macOS 上把你的扩展构建成一个 Safari 应用。 Safari 是一个 构建目标：支持 build 与 dev，但不支持 preview 与 start（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 意味着什么。

​
最佳实践

  • 日常迭代用具名浏览器：chrome、edge 与 firefox 是常规测试中最快的路径。
  • 有意识地使用引擎模式：在验证自定义二进制或需要家族通用构建时选用 chromium-based / gecko-based。
  • 每个浏览器保持 profile 隔离：减少调试时的跨浏览器状态泄漏。
  • 配合按浏览器划分的字段：用带浏览器前缀的 manifest 键处理真正的行为差异。

​
下一步