企业官网建设流程全解析

@puppeteer/browsers DownloadOptions 详解：浏览器 Provider 下载参数契约

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer

DownloadOptions是 Puppeteer 仓库内@puppeteer/browsers子包中定义的一个精简接口，描述"传给一个 Provider（下载提供者）的最小下载参数集合"。当你通过程序化 API 安装浏览器、或自定义镜像源实现BrowserProvider时，该接口就是贯穿整个下载流程的统一参数契约。读完本文，你将掌握DownloadOptions三个字段的确切含义与取值范围，理解它如何从install()入口被构造并流向底层 Provider，并能据此写出可正确分辨平台与浏览器类型的自定义下载 Provider。

DownloadOptions 是什么

在@puppeteer/browsers的源码设计中，浏览器下载被抽象为"Provider 模式"：install()负责编排流程，而"从哪里下载、怎么取可执行文件路径"由BrowserProvider决定。为了让 Provider 与编排逻辑解耦，两者之间传递统一的结构化参数——这就是 DownloadOptions 接口 的职责，其官方描述只有一句话："Options passed to a provider."（传给 Provider 的选项）。

从 源码定义 看，该接口只包含三个必填字段：

/** * Options passed to a provider. * @public */ export interface DownloadOptions { browser: Browser; platform: BrowserPlatform; buildId: string; }

它同属于BrowserProvider接口的核心签名：Provider 的supports()、getDownloadUrl()等方法都以DownloadOptions作为入参，见 BrowserProvider 接口文档 及 源码。

属性一览与逐项解析

按 官方 API 文档 的属性表，DownloadOptions三个字段均无默认值、无修饰符，属于调用方必须完整提供的必选项：

browser：下载哪种浏览器

browser的类型是 Browser 枚举，其取值在 types.ts 中定义：

该字段直接决定了后续 URL 构造与可执行文件路径解析走哪条下载链路。在 browser-data.ts 中可以看到，downloadUrls是一个以Browser为键的分发表，每种浏览器映射到各自的resolveDownloadUrl实现：

export const downloadUrls = { [Browser.CHROMEDRIVER]: chromedriver.resolveDownloadUrl, [Browser.CHROMEHEADLESSSHELL]: chromeHeadlessShell.resolveDownloadUrl, [Browser.CHROME]: chrome.resolveDownloadUrl, [Browser.CHROMIUM]: chromium.resolveDownloadUrl, [Browser.FIREFOX]: firefox.resolveDownloadUrl, };

同理，downloadPaths与executablePathByBrowser也按浏览器分派解压路径与可执行文件相对路径。这意味着DownloadOptions.browser一处改动，会连锁影响"下载地址、归档文件名、解压目录、可执行文件定位"四个环节。

platform：面向哪个操作系统与架构

platform的类型是 BrowserPlatform 枚举，官方描述为"以浏览器下载相关的方式标识 OS 平台 × 架构组合的名称"。取值见 types.ts：

注意BrowserPlatform是"平台×架构"组合粒度（mac与mac_arm是两条独立取值），与 Node 侧os.platform()/os.arch()的粗粒度划分不同。因此当你在代码里手动构造DownloadOptions而非依赖自动探测时，必须按此枚举精确指定；日常开发中也可以调用detectBrowserPlatform()（在 detectPlatform.ts 实现，经 main.ts 导出）由库自动推导当前机器对应的平台值。

buildId：精确定位一份二进制

buildId是字符串类型的构建标识，官方强调其必须唯一标识二进制文件，并被用作缓存键。从使用场景看，buildId有两种常见形态：

• 精确版本号：例如 Chrome for Testing 的完整版本"116.0.5793.0"；
• 标签/别名：例如"stable"、"canary"、"latest"（由BrowserTag枚举表示）。install()会在执行前通过resolveBuildId()把标签解析成具体版本号再进入下载环节，相关分发表见 browser-data.ts 中对各浏览器BrowserTag→ 频道映射的处理逻辑。

值得一提的是 provider.ts 注释 明确指出：getDownloadUrl()收到的buildId可能是别名也可能是精确版本，自定义 Provider 若要支持别名，需在内部自行完成版本解析；无法解析时返回null。

DownloadOptions 在 install 流程中的真实流转

DownloadOptions并非用户直接面向install()的完整入参——它通常由内部从InstallOptions提取而来。查看 install.ts 中installWithProviders()的构造逻辑即可印证：

const downloadOptions = { browser: options.browser, platform: options.platform, buildId: options.buildId, progressCallback: options.downloadProgressCallback === 'default' ? await makeProgressCallback( options.browser, options.buildIdAlias ?? options.buildId, ) : options.downloadProgressCallback, };

也就是说：InstallOptions（含cacheDir、unpack、baseUrl、providers等更丰富的字段）是用户层的"完整安装意图"，而从中抽取出的{browser, platform, buildId}三元组就是逐 Provider 试下载用的"最小请求"DownloadOptions（进度回调属于附加运行时参数，不在接口三字段内）。随后在 Provider 试错循环中，每个 Provider 依次被询问：

1. provider.supports(downloadOptions)是否支持该浏览器/平台组合（见 install.ts）；
2. provider.getDownloadUrl(downloadOptions)是否解析得出下载地址（install.ts）；
3. 下载成功后provider.getExecutablePath({browser, buildId, platform})定位归档内的可执行文件（install.ts）。

supports()与getDownloadUrl()的签名都以DownloadOptions为唯一参数，见 provider.ts 与 provider.ts。内置的 DefaultProvider 对任意浏览器平台一律返回supports() === true（见 DefaultProvider.ts），并通过downloadUrlsbrowser把DownloadOptions三个字段拼进官方下载源 URL。

编写自定义 Provider 时的最佳实践

当默认源不可用时（如内网镜像、私有制品库），可自实现BrowserProvider。由于DownloadOptions是方法入参，你通常需要同时依据browser与platform分支处理。下面是基于 docs/browsers-api/index.md 中示例改造的"镜像下载器"，完整展示了如何消费DownloadOptions：

import { BrowserProvider, DownloadOptions, Browser, BrowserPlatform, } from '@puppeteer/browsers'; class SimpleMirrorProvider implements BrowserProvider { constructor(private mirrorUrl: string) {} supports(options: DownloadOptions): boolean { // 仅声明支持 Chrome，其余浏览器交给链路上的其他 Provider return options.browser === Browser.CHROME; } getDownloadUrl(options: DownloadOptions): URL | null { const {buildId, platform} = options; // 依据 DownloadOptions.platform 决定归档文件名 const filenameMap = { [BrowserPlatform.LINUX]: 'chrome-linux64.zip', [BrowserPlatform.MAC]: 'chrome-mac-x64.zip', [BrowserPlatform.MAC_ARM]: 'chrome-mac-arm64.zip', [BrowserPlatform.WIN32]: 'chrome-win32.zip', [BrowserPlatform.WIN64]: 'chrome-win64.zip', }; const filename = filenameMap[platform]; if (!filename) return null; return new URL(`${this.mirrorUrl}/chrome/${buildId}/${filename}`); } getExecutablePath(options: DownloadOptions): string { const {platform} = options; if ( platform === BrowserPlatform.MAC || platform === BrowserPlatform.MAC_ARM ) { return 'chrome-mac/Chromium.app/Contents/MacOS/Chromium'; } else if (platform === BrowserPlatform.LINUX) { return 'chrome-linux64/chrome'; } else if (platform.includes('win')) { return 'chrome-win64/chrome.exe'; } throw new Error(`Unsupported platform: ${platform}`); } }

在supports()中判browser、在getDownloadUrl()/getExecutablePath()中判platform，正是这三个字段各自职责的最佳体现。需要说明的是：

• getDownloadUrl()的buildId可能是别名，若你的 Provider 支持别名需自行解析，否则返回null；
• getExecutablePath()返回的是归档内的相对路径，非绝对路径；
• 多个 Provider 可以链式传入install()，它们会按顺序尝试，内置默认 Provider 兜底（见 install.ts 中 Provider 列表构建逻辑）。

使用注意事项与源码路径索引

围绕DownloadOptions，有几点事实值得牢记：

1. 它不由用户在install()中直接提供：完整的安装选项是InstallOptions，DownloadOptions三字段会被自动提取并附加进度回调后传给 Provider；从源码看install()的入口实现见 install.ts，其中还会用detectBrowserPlatform()为缺失的platform兜底。
2. Puppeteer 官方不保证自定义 Provider 的兼容性：自定义来源的二进制可能与本仓库的目录结构与版本模型不符，需自行承担版本一致性、可执行文件兼容、特性集成与测试的全部责任。官方只对 Chrome for Testing 默认二进制做测试与兼容保证，详见 BrowserProvider 接口文档。
3. 公共导出：DownloadOptions与BrowserProvider、DefaultProvider、buildArchiveFilename一同从 main.ts 作为公共 API 导出，可放心以import {DownloadOptions} from '@puppeteer/browsers'方式使用。
4. 实用辅助函数：若需自行构造归档文件名，可直接使用buildArchiveFilename(browser, platform, buildId, extension = 'zip')，其实现见 provider.ts，生成的browser-platform-buildId.zip命名规则与DownloadOptions三字段一一对应。

关键文件路径

• DownloadOptions 官方 API 文档
• BrowserProvider 接口文档
• Browser 枚举文档
• BrowserPlatform 枚举文档
• 接口源码定义
• install() 中 DownloadOptions 的构造与 Provider 试错循环
• downloadUrls 浏览器分发映射
• Browser / BrowserPlatform 枚举实现
• 默认 Provider 实现
• 自定义 Provider 使用示例

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer