puppeteer/browsers DownloadOptions 详解浏览器 Provider 下载参数契约【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerDownloadOptions是 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三个字段均无默认值、无修饰符属于调用方必须完整提供的必选项属性类型说明默认值browserBrowser目标浏览器种类无必填buildIdstring目标构建标识Build ID须唯一标识一份二进制无必填platformBrowserPlatform目标操作系统 × 架构平台无必填browser下载哪种浏览器browser的类型是 Browser 枚举其取值在 types.ts 中定义枚举成员字符串值含义Browser.CHROMEchromeChromeChrome for TestingBrowser.CHROMEHEADLESSSHELLchrome-headless-shell独立的 headless Chrome 精简版Browser.CHROMIUMchromiumChromiumBrowser.FIREFOXfirefoxFirefoxBrowser.CHROMEDRIVERchromedriverChromeDriverWebDriver 驱动该字段直接决定了后续 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.LINUXlinuxLinux x64BrowserPlatform.LINUX_ARMlinux_armLinux ARMBrowserPlatform.MACmacmacOSIntel x64BrowserPlatform.MAC_ARMmac_armmacOSApple Silicon ARMBrowserPlatform.WIN32win32Windows 32 位BrowserPlatform.WIN64win64Windows 64 位注意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 依次被询问provider.supports(downloadOptions)是否支持该浏览器/平台组合见 install.tsprovider.getDownloadUrl(downloadOptions)是否解析得出下载地址install.ts下载成功后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 中示例改造的镜像下载器完整展示了如何消费DownloadOptionsimport { 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 支持别名需自行解析否则返回nullgetExecutablePath()返回的是归档内的相对路径非绝对路径多个 Provider 可以链式传入install()它们会按顺序尝试内置默认 Provider 兜底见 install.ts 中 Provider 列表构建逻辑。使用注意事项与源码路径索引围绕DownloadOptions有几点事实值得牢记它不由用户在install()中直接提供完整的安装选项是InstallOptionsDownloadOptions三字段会被自动提取并附加进度回调后传给 Provider从源码看install()的入口实现见 install.ts其中还会用detectBrowserPlatform()为缺失的platform兜底。Puppeteer 官方不保证自定义 Provider 的兼容性自定义来源的二进制可能与本仓库的目录结构与版本模型不符需自行承担版本一致性、可执行文件兼容、特性集成与测试的全部责任。官方只对 Chrome for Testing 默认二进制做测试与兼容保证详见 BrowserProvider 接口文档。公共导出DownloadOptions与BrowserProvider、DefaultProvider、buildArchiveFilename一同从 main.ts 作为公共 API 导出可放心以import {DownloadOptions} from puppeteer/browsers方式使用。实用辅助函数若需自行构造归档文件名可直接使用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考