深入解析 @puppeteer/browsers 的 InstallOptions 接口：浏览器安装参数全景指南

2026-09-07 14:58:15作者：庞眉杨Will

导读

InstallOptions 是 Puppeteer 生态中 @puppeteer/browsers 包提供给 install() 程序化安装 API 的核心入参类型，它决定了下载哪个浏览器、哪个构建版本、从哪个镜像源下载、安装到哪个目录，以及是否校验文件完整性、是否自动补齐系统依赖等关键行为。本文以 browsers.installoptions.md 为骨架，结合仓库内 install.ts 的实现与测试用例，逐字段拆解每个属性的含义、默认值与底层影响，帮助你写出可精确复现、可离线部署、可自定义下载源的安装脚本。

InstallOptions 在浏览器安装链路中的位置

@puppeteer/browsers 是 Puppeteer 独立维护的浏览器下载与启动工具包，它的主入口在 packages/browsers/src/main.ts，对外导出 install、uninstall、getInstalledBrowsers、canDownload、launch 等函数。其中 install() 负责"下载并解压浏览器归档到本地缓存目录"，而 InstallOptions 就是描述"装什么、从哪装、装到哪、怎么校验"的唯一参数对象。

在 install.ts 的实现中，install() 会对参数做三层归一化，随后进入真正安装流程：

options.platform ??= detectBrowserPlatform(); // 未显式指定平台时自动探测
options.unpack ??= true;                       // 默认解压并安装
options.logger ??= debug;                      // 默认走 debug 日志通道
if (!options.platform) {
  throw new Error(`Cannot download a binary for the provided platform: ...`);
}
options.providers ??= [];
return await installWithProviders(options);

可以看到：文档接口中的绝大多数字段都带有默认值或自动探测行为，只有三个字段是必填的。理解了这一点，就掌握了整个安装管线的骨架。

必填三要素：cacheDir、browser、buildId

InstallOptions 中共有三个无 optional 修饰符的属性，它们共同构成一次安装任务的"最小描述"。

cacheDir：浏览器安装目录（即缓存根目录）

类型为 string，含义是"下载浏览器到哪个路径"。安装产物并非平铺在 cacheDir 下，而是遵循一套严格的分层缓存结构。在 Cache.ts 的注释与实现中可以确认：

<cacheDir>                       （缓存根目录，对应 cacheDir）
  └── <browser>                  （browserRoot：按浏览器品种分目录）
        └── <platform>-<buildId> （installationDir：按"平台-构建号"分目录）
              └── 浏览器二进制与目录结构

对应到代码中就是 browserRoot(browser) = path.join(rootDir, browser)，installationDir(browser, platform, buildId) = path.join(browserRoot, \ $p l a t f o r m -$ {buildId}`)（见 [Cache.ts](https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer/blob/57b44b7d8d596f3b759d9dee56e90dcbf33fc0d6/packages/browsers/src/Cache.ts?utm_source=gitcode_repo_files#L133-L135) 与 [Cache.ts](https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer/blob/57b44b7d8d596f3b759d9dee56e90dcbf33fc0d6/packages/browsers/src/Cache.ts?utm_source=gitcode_repo_files#L195-L201)）。在浏览器目录下还会生成一个 .metadataJSON 文件，用于保存别名（aliases）与自定义可执行文件路径（executablePaths）等元数据，这正是buildIdAlias与自定义providers得以在launch` 阶段生效的基础。

browser：要安装的浏览器品种

类型为 Browser 枚举，参考 browsers.browser.md。从 browser-data 目录以及各浏览器独立测试文件（如 chrome、chromedriver、chrome-headless-shell、firefox、chromium）可以看出，仓库对不同浏览器实现了各自的下载地址与可执行文件路径映射。选择不同浏览器会联动影响默认下载源（见下文 baseUrl）与归档文件名。

buildId：唯一标识构建版本

类型为 string。文档明确指出：BuildId 应能唯一标识二进制文件，并且被用作缓存键。这一点在代码中得到完整印证：installationDir 直接以 ${platform}-${buildId} 作为目录名，安装目录一旦存在且可执行文件完整，install() 会跳过重复下载直接复用（见 install.ts 的缓存命中分支）。因此 buildId 的选取必须能稳定区分不同的二进制内容——例如 Chrome for Testing 的完整版本号 120.0.6099.109，或 Firefox 的具体版本号。

典型的最小调用如下：

import {install, Browser, BrowserPlatform} from '@puppeteer/browsers';

const browser = await install({
  cacheDir: '/tmp/puppeteer-cache',
  browser: Browser.CHROME,
  buildId: '120.0.6099.109',
});
console.log(browser.executablePath);

platform：默认自动探测，也可显式指定

platform 为可选属性，类型是 BrowserPlatform，文档标注的默认值是 Auto-detected（自动探测）。安装流程开头的 options.platform ??= detectBrowserPlatform() 即基于当前 os.platform() 与 os.arch() 探测目标平台；若探测失败（例如平台/架构组合不在支持列表内），install() 会抛出 Cannot download a binary for the provided platform 错误。

尽管可以省略，生产中建议显式传入 platform，理由如下：

保证在不同机器、不同 CI 环境下安装结果可复现；
支持交叉场景（如为某个平台的产物离线准备缓存）；
installationDir 以 platform 为路径组成部分，显式指定可避免探测歧义。

代码中可确认的取值包括 BrowserPlatform.LINUX、BrowserPlatform.LINUX_ARM、BrowserPlatform.WIN32、BrowserPlatform.WIN64（在 install.ts 的平台分支与 Windows setup.exe 逻辑中被实际引用）。

unpack：控制"下载"还是"下载并安装"

unpack 是布尔类型、可选、默认 true，对应 install() 的两个函数重载（见 install.md）：

unpack 取值	行为	install() 返回类型
`true`（默认，等价于省略）	下载归档、解压到 `cacheDir/<browser>/<platform>-<buildId>`、执行 setup	`Promise<InstalledBrowser>`（含 `executablePath`、`path` 等）
`false`	只下载不解压	`Promise<string>`（归档文件的绝对路径）

只下载归档文件的场景典型用途是构建离线安装源：先在联网环境把各平台归档拉全，再分发到内网。install({unpack: false}) 会把归档保存为 <browserRoot>/<buildId>-<fileName>，并直接返回该路径而不触发解压（见 install.ts）。InstalledBrowser 的具体能力可以参考 installedbrowser.md。

baseUrl：自定义下载镜像/源

baseUrl 为可选 string，决定下载使用的主机（host），文档给出的默认值是二选一：

Chrome 系列：https://storage.googleapis.com/chrome-for-testing-public
Firefox：https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central

在实现层面，DefaultProvider 构造器接收可选的 baseUrl，并在构造下载 URL 时透传给 downloadUrlsbrowser（见 DefaultProvider.ts）。因此 baseUrl 的本质是"替换默认下载源的 host 前缀"，常用于企业内网镜像或国内加速源。注意：由于不同浏览器品种共享 DefaultProvider，替换 baseUrl 时应确保镜像同时托管了你需要的全部浏览器归档。

providers：自定义下载源提供者（插件式架构）

providers 是 BrowserProvider[]，类型定义见 browserprovider.md 与 provider.ts。这是该接口在近期架构升级中引入的插件式下载能力：不再只有单一下载通道，而是让多个来源按顺序"接力"尝试。

从 install.ts 的 installWithProviders 实现可以还原完整规则：

候选列表 = 显式传入的自定义 providers + 若提供了 baseUrl 则追加一个 new DefaultProvider(baseUrl)；
默认 provider 永远作为最终兜底被追加到队尾（除非显式传入 baseUrl 且内部测试标志关闭，见 install.ts）；
对每个 provider 依次执行 supports(downloadOptions)（过滤是否支持该浏览器/平台/构建组合）、getDownloadUrl(...)（拿到下载 URL）与 getExecutablePath(...)（拿到归档内可执行文件的相对路径）；
某个 provider 抛错或返回空 URL 就记录错误并尝试下一个；
全部失败时抛出 All providers failed for ... 的聚合错误，其中按行列出每个 provider 的名字与失败原因。

仓库文档自带了一个链式回退的典型示例——优先尝试 Electron 发布源、失败后自动回退到 Chrome for Testing（见 install.ts）：

import {install, Browser} from '@puppeteer/browsers';
import {ElectronProvider} from './puppeteer-browser-provider-electron.js';

await install({
  browser: Browser.CHROMEDRIVER,
  buildId: '142.0.7444.175',
  cacheDir: './cache',
  providers: [
    new ElectronProvider(), // 先尝试 Electron 发布源
    // 失败时自动回退到 Chrome for Testing
  ],
});

对应的测试 installWithProviders.test.ts 中分别验证了"自定义 provider 失败后回退默认 provider 成功"与"多个 provider 依次尝试、取第一个成功者"两条行为路径。

必须重点提示：接口文档与源码都反复强调——自定义 provider 不受 Puppeteer 官方支持。选择自定义 provider 意味着你需要自行承担：不同平台可能拿到不同二进制版本的一致性风险、归档内部结构须与 Puppeteer 预期一致（否则 getExecutablePath 指向错误）、启动等 Puppeteer 功能可能失效，以及你必须自行验证下载产物可用。Puppeteer 只对默认二进制做兼容性测试与保证。BrowserProvider 接口本身只要求四个方法：supports、getDownloadUrl、getExecutablePath、getName，其中 getName 用于错误信息与日志（provider.ts）。

downloadProgressCallback：下载进度反馈

可选，类型为 'default' | ((downloadedBytes: number, totalBytes: number) => void)。两种取值行为不同：

'default'：使用内置的进度条回调。实现位于 makeProgressCallback（install.ts），它借助 ProgressBar.ts 创建一个标题形如 Downloading chrome 120.0.6099.109 - xxx MB 的进度条 ticker，并增量汇报下载字节数。
自定义函数：形如 (downloadedBytes, totalBytes) => void，适合接入 CI 日志、第三方进度组件或静默安装。

从 install.ts 可以看到，该回调最终会被注入底层 downloadFile 的下载流程中（'default' 在构建 downloadOptions 时即被解析为真实函数）。

expectedHash：下载完整性校验（SHA-256）

expectedHash 为可选 string，语义是"期望的归档 SHA-256 校验和（小写十六进制）"：

提供时：下载完成后计算文件哈希，不匹配则安装失败，可有效拦截中间人篡改或镜像源坏档；
省略时：直接下载不做完整性验证。

在实现中，expectedHash 从 install() 一路透传到 downloadFile(url, archivePath, progressCallback, options.expectedHash)（见 install.ts），在下载阶段完成边下边校验。对于安全敏感的生产环境与离线镜像分发场景，建议优先提供该字段。

installDeps：自动安装系统依赖（仅限 Linux 下的 Chrome）

installDeps 为可选 boolean，默认 false，用于"是否尝试安装浏览器运行所需的系统级依赖"。文档明确了两条硬性限制：

仅支持 Debian / Ubuntu 下的 Chrome；
需要系统级权限运行 apt-get（即需要 root）。

实现细节位于 installDeps（install.ts）：它要求 process.platform === 'linux' 且平台为 LINUX/LINUX_ARM，然后读取解压产物中随包生成的 deb.deps 文件（路径为可执行文件同目录下），拼接为逗号分隔的包列表；随后校验 process.getuid?.() === 0，并依次执行 apt-get -v（探测可用性）与 apt-get satisfy -y <packages> --no-install-recommends 完成安装。任一步骤失败都会抛出带明细的错误。因此在使用该选项前请确认：目标机器是 Debian/Ubuntu、具备 root 权限、且网络可访问 apt 源。

buildIdAlias：为构建号建立本地别名

buildIdAlias 为可选 string，作用是"为传入的 buildId 维护一个本地别名，供 launch 命令在后续启动时引用"。文档中的示例是 'canary' 这类人类可读别名。

其落盘逻辑在解压完成后（install.ts）：

if (options.buildIdAlias) {
  const metadata = installedBrowser.readMetadata();
  metadata.aliases[options.buildIdAlias] = options.buildId;
  installedBrowser.writeMetadata(metadata);
}

别名被写入浏览器目录下的 .metadata 文件。之后 Cache.resolveAlias（Cache.ts）在计算可执行文件路径时会将别名解析为具体 buildId；该逻辑同时处理特殊值 latest——在所有已记录别名指向的 buildId 中按版本比较器取最高者。这样即便 buildId 是晦涩的长版本号，也可以用 canary、latest 之类的别名在启动阶段引用，launch 命令（launch.ts）因此支持"别名启动"。

logger：安装过程日志通道

logger 为可选字段，类型是 Logger。默认值为模块导出的 debug 函数（options.logger ??= debug）。日志以 DEBUG_PREFIXES.install 等前缀区分命名空间，可通过环境变量按需开启（见 debug.ts），例如观察 provider 尝试顺序、下载耗时（Duration for download: xxxms）、归档解压进度与依赖安装明细。传自定义 logger 时，应兼容 (message: string, ...args: unknown[]) => void 的签名以便接收格式化消息。

下载之外：install() 的后续动作与异常语义

InstallOptions 的每个字段最终都汇入 installUrl 的完整执行链路（install.ts），可以总结为如下流程：

计算 browserRoot 与归档路径 <browserRoot>/<buildId>-<fileName>；
若目标安装目录已存在且可执行文件完整，则跳过下载直接复用（真正意义上的缓存命中）；
目录存在但可执行文件缺失时，抛出 IncompleteInstallationError，提示"上一次安装未完成，请删除该目录后重试"（install.ts）；
否则走下载 → unpackArchive 解压 → （有 alias 时写 .metadata）→ runSetup → （可选 installDeps）→ 返回 InstalledBrowser；
默认（unpack: true）流程结束时会在 finally 中删除临时归档文件，避免占用磁盘空间；
Windows 平台安装 Chrome 时，runSetup（install.ts）会调用归档内的 setup.exe --configure-browser-in-directory=<dir> 配置沙箱权限。

关于自定义 provider 与默认路径的差异：当 provider 不是 DefaultProvider 时，其 getExecutablePath 返回的相对路径会被写入 .metadata 的 executablePaths[platform-buildId]（install.ts），而默认 provider 则使用内置的 executablePathByBrowser 静态映射。这一点解释了为什么换用自定义 provider 安装后，launch/computeExecutablePath 仍能正确定位二进制。