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 对每个浏览器都按同一个顺序选定二进制:
- flag:
--chromium-binary或--gecko-binary。 - 该浏览器的环境变量。
- 来自
extension install的受管理二进制。 - 系统安装。
变量指向不存在的路径或无法运行的文件时,启动会以
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失败。提示会请你重新运行安装,并在同样失败时报告这条消息。
示例
安装 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 就能运行。

