跳转到主要内容
使用 install 把一个受管理的浏览器运行时加入 Extension.js 缓存。 当你希望在 dev、build、start 或 preview 中使用稳定一致的浏览器二进制时,这个命令最有用。它支持 Chrome for Testing、Chromium、Firefox 与 Edge。

什么时候使用 install

  • 你需要一致、可复现的浏览器二进制,用于持续集成(CI)、自动化或团队一致的本地运行。
  • 你想用 Chrome for Testing,而不是依赖你系统上恰好安装的某个 Chrome 版本。
  • 你正在用受管理的 Firefox 或者 Edge 搭建跨浏览器测试。

为什么 Extension.js 会下载一个浏览器

运行类命令优先使用受管理的浏览器运行时,而不是你日常使用的那个浏览器。
  • 受管理的二进制是版本固定的。dev、CI 运行和团队成员启动的都是同一个构建。
  • Chrome for Testing 是为自动化而构建的。较新的品牌版 Chrome 构建(150+)可能会丢弃用来加载你扩展的 --load-extension 开关。
  • 受管理的运行时在一个隔离的配置文件中运行。它永远不会碰你的个人浏览器、它的配置文件或它的设置。
你不必提前运行 install。当请求的目标没有可用的二进制时,运行类命令会打印出准确的安装命令。

跳过受管理下载

你可以直接针对一个已经安装的浏览器开发,无需任何下载:
  • 按名称运行一个分支浏览器:extension dev --browser=brave 会为你定位已安装的 Brave。见运行其他浏览器。
  • 固定任意二进制:给 dev、start 或 preview 传 --chromium-binary <path> 或 --gecko-binary <path>。固定值会覆盖所有定位器。
  • 设置一个二进制变量,例如 FIREFOX_BINARY。见运行哪个二进制。
  • 请求 edge 时,会启动你系统上已安装的 Edge。
  • 请求 chrome 时会拒绝品牌版的系统 Chrome,并要求改用 Chrome for Testing。
  • 如果无论如何都要运行品牌版 Chrome,用 --chromium-binary 固定它。

Edge 安装在你的系统上

extension install edge 会运行 playwright install msedge,它把 Microsoft Edge 安装到你的系统上。Extension.js 的缓存里没有固定版本的 Edge 副本。--browser=edge 会自己找到系统 Edge,所以 Edge 已经安装时你可以跳过这条命令。 在 Linux 上,这次安装需要一个有 sudo 权限的交互会话。当安装失败且系统中存在 Edge 时,安装器会报告系统二进制并以它成功完成。 从 4.2.0 起,当 install 找到的 Edge 位于运行命令不会搜索的位置时,消息会打印它的路径,并请你用 --chromium-binary 传入这个路径。

运行哪个二进制

从 4.1.39 之后的版本起,dev、start 和 preview 对每个浏览器都按同一个顺序选定二进制:
  1. flag:--chromium-binary 或 --gecko-binary。
  2. 该浏览器的环境变量。
  3. 来自 extension install 的受管理二进制。
  4. 系统安装。
变量指向不存在的路径或无法运行的文件时,启动会以 E_BROWSER_BINARY_INVALID 失败。出错的变量绝不会被跳过。 身份卡会说明是哪一步给出了结果。(pinned with FIREFOX_BINARY) 写明那个 flag 或变量,(system install) 表示浏览器来自你的系统。受管理的二进制没有任何标注。ready.json 用 binaryProvenance 和 binaryPinnedBy 记录同一件事。 对 Firefox 来说,受管理这一步会优先选择稳定版,而不是同一个缓存里的 nightly。运行的是 nightly 时,卡片会显示 Firefox Nightly。 请求 chrome 时仍然会拒绝品牌版的系统 Chrome。指向品牌版 Chrome 的变量不会被采用,运行会继续使用受管理的二进制。见二进制如何选定。

标准用法

针对单个浏览器,使用位置参数形式:
只有在需要多个目标、浏览器家族或 all 时才使用 --browser。

install 命令的能力

用法

参数与 flag

这里的 all 指什么

extension install --browser all 会安装 chrome、chromium、edge 与 firefox。这和运行类命令上的 --browser all 不同,后者只展开为 chrome、edge 与 firefox。安装集合还包含 Chromium,因为它是 dev 与 start 的默认启动目标。

用 --output json 输出机器可读结果

--output json 会在 stdout 上打印一个 schema-1 信封:
  • 成功的安装会打印一个 status: "installed" 帧,安装好的浏览器在 value.browsers 中。
  • --where 会打印一个 status: "located" 帧,解析出的路径在 value.paths 中。
  • 下载失败会在进程以 1 退出前打印 ok: false,其 error.code: "E_BROWSER_DOWNLOAD"。
  • 下载结束了却没有留下可用的浏览器二进制时,也以同样的方式失败。见行为说明。
  • 从 4.1.41 之后的版本起,缺少包运行器时改为以 E_BROWSER_INSTALLER_NOT_FOUND 失败。
  • 从 4.2.0 之后的版本起,存在但无法启动的包运行器会以 E_BROWSER_DOWNLOAD 失败。消息会点名运行器和系统错误代码,并说明什么都没有下载。
  • 从 4.2.0 之后的版本起,类型未知的安装故障会以 E_INTERNAL 失败。提示会请你重新运行安装,并在同样失败时报告这条消息。
从 4.2.0 起,这些失败有各自的代码:

示例

安装 Chrome for Testing

一条命令安装多个目标

显示 Chrome 的受管理安装路径

缓存位置

默认情况下,Extension.js 把受管理的浏览器存放在每用户的稳定缓存中:
  • macOS:~/Library/Caches/extension.js/browsers
  • Linux:~/.cache/extension.js/browsers 或 $XDG_CACHE_HOME/extension.js/browsers
  • Windows:%LOCALAPPDATA%\extension.js\browsers
你可以用 EXT_BROWSERS_CACHE_DIR 覆盖缓存根目录。

缓存里放了什么

每个浏览器在缓存根目录下都有自己的目录,但目录内部的布局取决于下载引擎:
  • chrome、chromium 与 firefox 来自 @puppeteer/browsers。每个浏览器目录里会有它那套嵌套的平台与版本子目录。
  • edge 不在缓存里。playwright install msedge 会把 Microsoft Edge 安装到你的系统上。
  • safari 没有可下载的东西。Safari 随 macOS 一起提供,构建还需要完整的 Xcode app,所以 extension install safari 会带着解释拒绝执行。
  • 像 Brave 这样的具名分支永远不会被下载。请改用 --chromium-binary 或 --gecko-binary 指向它们。
请用 --where 而不要把路径写死,因为嵌套布局可能随下载引擎变化。

项目本地的二进制

设置 EXTENSIONJS_BINARIES_IN_DIST=1,可以让运行类命令在项目内的 dist/extension-js/binaries 下解析受管理的二进制,而不是使用共享的每用户缓存。这适合沙箱化或完全自包含的项目配置。

最佳实践

  • 在 CI 中使用 install,固定一个稳定的浏览器二进制,而不是依赖 runner 提供的版本。
  • 优先使用 chrome 而不是 chromium:Chrome for Testing 更贴近稳定版 Chrome 的行为。
  • 使用 --where 在围绕受管理浏览器做脚本化自动化之前先确认缓存路径。
  • install 把 chrome、chromium 和 firefox 放在 Extension.js 缓存里,不会改动这些浏览器的系统安装。
  • edge 是例外。它会把 Microsoft Edge 安装到你的系统上。

行为说明

  • chrome 会安装 Chrome for Testing,而不是依赖系统中的 Google Chrome app。
  • 在 Linux 上,edge 可能需要一个有权限的交互会话。
  • install 在报告成功之前会检查目标目录。当安装器正常退出,但目录里没有一个非空且可执行的浏览器二进制文件时(比如下载被中断之后),命令会以 E_BROWSER_DOWNLOAD 失败并以 1 退出。它会删掉不完整的文件,所以下一次 extension install 从干净的状态开始。
  • 从 4.2.0 起,EXTENSION_INSTALL_TIMEOUT_MS 设置安装器可以运行多久,默认 30 分钟。值是一个整数毫秒数。任何其他值,比如 30s,都表示默认值。
  • 从 4.2.0 起,同一个浏览器一次只运行一个安装。安装会在缓存根目录中持有一个以浏览器命名的锁文件夹,比如 .chrome.lock。同一浏览器的第二次安装会等待它,最长等到安装超时,然后以 E_BROWSER_INSTALL_BUSY 失败。消息会点名在没有这样的安装运行时可以删除的锁文件夹。持有者进程已经不在的锁会被接管。
  • 从 4.2.0 起,install 在下载开始之前会把一个 .extension-install.json 标记写入浏览器文件夹。带有该标记的文件夹,或者只包含下载引擎所写文件的文件夹,属于 Extension.js。同时还包含浏览器 profile 的带标记文件夹则不属于。install 与 uninstall 不会从不属于 Extension.js 的文件夹中移除任何内容。
  • 在 Deno 上,install 需要 PATH 里有 Node.js。浏览器安装器会调用 npx(或启动 CLI 的那个包管理器)来运行下载引擎,而 deno 没有这样的运行器。没有 Node.js 时,命令会在下载步骤失败。其他命令只靠 Deno 就能运行。

下一步