Puppeteer browsers 库 SystemOptions 全解精准定位系统已安装浏览器与发布通道【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerSystemOptions 是 Puppeteer 浏览器管理包puppeteer/browsers中用于描述「系统级已安装浏览器」的配置接口是computeSystemExecutablePath()的唯一入参类型。本文基于本仓库 packages/browsers/src/launch.ts 及其类型文档系统讲解 SystemOptions 的字段语义、配套枚举、底层平台路径探测逻辑与真实错误行为帮助你跳过「自己下载浏览器」的环节直接复用手头机器上已装好的 Chrome / Chromium。SystemOptions 是什么面向「系统已装浏览器」的定位描述在puppeteer/browsers的下载与启动体系中存在两类获取浏览器可执行文件的途径下载缓存型通过install()下载到自定义缓存目录再用computeExecutablePath()拼接缓存路径系统探测型直接在当前操作系统已知的安装目录中查找已经安装好的浏览器由computeSystemExecutablePath()完成。SystemOptions 正是第二种途径的参数类型它只需三个信息即可唯一定位一台机器上的某个浏览器用哪个浏览器browser、找哪个发布通道channel、跑在哪个平台platform。其完整的接口签名在 packages/browsers/src/launch.ts 中定义export interface SystemOptions { /** * Determines which platform the browser will be suited for. * * defaultValue **Auto-detected.** */ platform?: BrowserPlatform; /** * Determines which browser to launch. */ browser: Browser; /** * Release channel to look for on the system. */ channel: ChromeReleaseChannel; }该接口被computeSystemExecutablePath()消费后者会根据SystemOptions遍历已知安装位置并返回真实存在的可执行文件路径接口本身的完整说明见 browsers.systemoptions.md函数行为见 browsers.computesystemexecutablepath.md。三个字段逐一拆解SystemOptions 是相当精简的接口其属性表如下PropertyModifiersTypeDescriptionDefaultbrowser—BrowserDetermines which browser to launch.—channel—ChromeReleaseChannelRelease channel to look for on the system.—platformoptionalBrowserPlatformDetermines which platform the browser will be suited for.Auto-detected.其中browser与channel是必填项platform可省略——省略时会调用自动检测逻辑见下文「平台自动检测」因此跨平台脚本只需提供browser与channel两个字段即可开箱即用。browser选择要探测的浏览器字段类型为Browser枚举定义见 docs/browsers-api/browsers.browser.md表示当前支持的浏览器种类成员值CHROMEchromeCHROMEDRIVERchromedriverCHROMEHEADLESSSHELLchrome-headless-shellCHROMIUMchromiumFIREFOXfirefox需要说明的是从 launch.ts 与 browser-data/chrome.ts 的源码结构看resolveSystemExecutablePaths()当前按browser / platform / channel三个维度分发Chrome 相关通道stable/beta/dev/canary的各平台安装位置映射实现得最为完整。channel决定扫描哪个发布通道字段类型为ChromeReleaseChannel枚举见 docs/browsers-api/browsers.chromereleasechannel.md对应 Chrome 的四种发布通道成员值典型用途STABLEstable生产环境的稳定版本BETAbeta提前体验次版本功能DEVdev更早的开发通道构建CANARYcanary每日构建的尝鲜版本channel直接决定了函数「去哪找、找什么后缀的目录」例如 Linux 上 stable 对应/opt/google/chrome而 canary 对应/opt/google/chrome-canary。platform需要时可覆盖的架构维度字段类型为BrowserPlatform枚举见 docs/browsers-api/browsers.browserplatform.md枚举值即操作系统与 CPU 架构的组合标识成员值语义LINUXlinuxLinux x64LINUX_ARMlinux_armLinux arm64MACmacmacOS x64MAC_ARMmac_armmacOS arm64Apple SiliconWIN32win3232 位 WindowsWIN64win6464 位 Windows该字段是可选项默认值在文档与源码注释中均标注为Auto-detected。通常只有在「本机运行、但目标定位另一平台安装路径」这类交叉场景下才需要显式传入。平台自动检测的底层实现当SystemOptions.platform未传时computeSystemExecutablePath()会调用 detectPlatform.ts 中的detectBrowserPlatform()完成推断export function detectBrowserPlatform(): BrowserPlatform | undefined { const platform os.platform(); const arch os.arch(); switch (platform) { case darwin: return arch arm64 ? BrowserPlatform.MAC_ARM : BrowserPlatform.MAC; case linux: return arch arm64 ? BrowserPlatform.LINUX_ARM : BrowserPlatform.LINUX; case win32: return arch x64 || // Windows 11 for ARM supports x64 emulation (arch arm64 isWindows11(os.release())) ? BrowserPlatform.WIN64 : BrowserPlatform.WIN32; default: return undefined; } }值得注意的两个实现细节macOS arm64 优先识别为MAC_ARMApple Silicon 上自动落入 arm64 专用平台标识Windows on ARM 特判若运行 Windows 11版本号10.0.22000及以上即使 CPU 架构是 arm64也因系统具备 x64 模拟能力而被归类为WIN64见同文件 isWindows11()。如果平台既无法自动检测、用户也未显式指定computeSystemExecutablePath()会抛出如下错误launch.tsCannot download a binary for the provided platform: ${os.platform()} (${os.arch()})computeSystemExecutablePathSystemOptions 的消费者SystemOptions 被 launch.ts 中的computeSystemExecutablePath(options, validatePath true)使用其工作流程如下export function computeSystemExecutablePath( options: SystemOptions, validatePath true, ): string { options.platform ?? detectBrowserPlatform(); if (!options.platform) { throw new Error( Cannot download a binary for the provided platform: ${os.platform()} (${os.arch()}), ); } const paths resolveSystemExecutablePaths( options.browser, options.platform, options.channel, ); for (const path of paths) { try { accessSync(path); return path; } catch {} } if (!validatePath) { return paths[0]; } throw new Error( Could not find Google Chrome executable for channel ${options.channel} at:${paths.map(...)}., ); }流程要点platform 兜底先执行platform ?? detectBrowserPlatform()补齐默认值保证后续路径解析有平台上下文解析候选路径列表由resolveSystemExecutablePaths(browser, platform, channel)返回一组该平台/通道的「已知安装位置」逐个用accessSync探活返回第一个真实存在的路径两个出口全部候选都不存在且validatePath false时直接返回第一个候选路径不抛错适合「只想要路径、是否安装由外部决定」的用法validatePath true默认时抛错错误信息会逐行列出全部被检查过的候选路径便于排查。各平台真实探测的候选安装位置SystemOptions 能「跨平台工作」的底气来自 browser-data/chrome.ts 中硬编码的已知安装位置表。以 Chrome 为例探测逻辑按平台分支如下Linux含 WSL按通道分别检查/opt/google/chrome/chromestable、/opt/google/chrome-beta/chromebeta、/opt/google/chrome-unstable/chromedev、/opt/google/chrome-canary/chromecanary随后还会尝试通过getWslLocation(channel)追加 WSL 环境下的候选位置macOS检查/Applications/Google Chrome.app/Contents/MacOS/Google Chromestable以及 Beta、Dev、Canary 对应命名*.app中的同名可执行文件Windows从一组环境变量源码中的WINDOWS_ENV_PARAM_NAMES读取安装根目录并内置C:\Program Files、C:\Program Files (x86)、D:\Program Files、D:\Program Files (x86)作为环境变量配置错误时的回退前缀再拼接出各通道目录下的chrome.exe。从源码结构可以推断这种「先收集一批候选路径 → accessSync 逐一验证 → 返回首个命中」的设计正是为了让platform自动检测与手动覆盖都能获得一致且可预期的结果。完整可运行示例把 SystemOptions 接入真实的浏览器启动流程可以这样写可直接在 Node 端运行import { computeSystemExecutablePath, Browser, ChromeReleaseChannel, launch, CDP_WEBSOCKET_ENDPOINT_REGEX, } from puppeteer/browsers; // 1. 组装 SystemOptions仅指定浏览器与通道platform 交给自动检测 const options { browser: Browser.CHROME, channel: ChromeReleaseChannel.STABLE, }; // 2. 定位系统已安装的 Chrome const executablePath computeSystemExecutablePath(options); console.log(Found Chrome at:, executablePath); // 3. 直接启动它并等待 CDP WebSocket 端点 const proc launch({ executablePath, args: [--remote-debugging-port0], }); const wsEndpoint await proc.waitForLineOutput(CDP_WEBSOCKET_ENDPOINT_REGEX); console.log(DevTools listening on, wsEndpoint);若机器上并未安装对应通道的浏览器默认会抛出带全部候选路径的错误例如Could not find Google Chrome executable for channel stable at: - /opt/google/chrome/chrome此时可以做两件事把channel换成实际安装的通道或在computeSystemExecutablePath(options, false)中关闭路径校验改为自行判断返回结果是否存在。启动细节进程信号处理、dumpio、pipe等可参考 Process 类与 launch() 实现。总结什么时候该用 SystemOptions优先复用系统浏览器不想为每个环境重新下载浏览器希望 CI/本地一致指向已安装的 Chrome 通道时多通道测试矩阵同一机器同时装有 stable 与 beta可通过channel快速切换被测版本交叉平台定位配合显式platform在打包/远程场景中描述目标平台的安装路径。使用时记住三件事browser与channel必填platform省略即自动检测darwin arm64 → MAC_ARM、Windows 11 on ARM → WIN64 等边界已内置处理拿到的路径默认是「已被accessSync验证真实存在」的路径必要时通过第二个参数validatePath关闭该校验。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Puppeteer browsers 库 SystemOptions 全解：精准定位系统已安装浏览器与发布通道
Puppeteer browsers 库 SystemOptions 全解精准定位系统已安装浏览器与发布通道【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerSystemOptions 是 Puppeteer 浏览器管理包puppeteer/browsers中用于描述「系统级已安装浏览器」的配置接口是computeSystemExecutablePath()的唯一入参类型。本文基于本仓库 packages/browsers/src/launch.ts 及其类型文档系统讲解 SystemOptions 的字段语义、配套枚举、底层平台路径探测逻辑与真实错误行为帮助你跳过「自己下载浏览器」的环节直接复用手头机器上已装好的 Chrome / Chromium。SystemOptions 是什么面向「系统已装浏览器」的定位描述在puppeteer/browsers的下载与启动体系中存在两类获取浏览器可执行文件的途径下载缓存型通过install()下载到自定义缓存目录再用computeExecutablePath()拼接缓存路径系统探测型直接在当前操作系统已知的安装目录中查找已经安装好的浏览器由computeSystemExecutablePath()完成。SystemOptions 正是第二种途径的参数类型它只需三个信息即可唯一定位一台机器上的某个浏览器用哪个浏览器browser、找哪个发布通道channel、跑在哪个平台platform。其完整的接口签名在 packages/browsers/src/launch.ts 中定义export interface SystemOptions { /** * Determines which platform the browser will be suited for. * * defaultValue **Auto-detected.** */ platform?: BrowserPlatform; /** * Determines which browser to launch. */ browser: Browser; /** * Release channel to look for on the system. */ channel: ChromeReleaseChannel; }该接口被computeSystemExecutablePath()消费后者会根据SystemOptions遍历已知安装位置并返回真实存在的可执行文件路径接口本身的完整说明见 browsers.systemoptions.md函数行为见 browsers.computesystemexecutablepath.md。三个字段逐一拆解SystemOptions 是相当精简的接口其属性表如下PropertyModifiersTypeDescriptionDefaultbrowser—BrowserDetermines which browser to launch.—channel—ChromeReleaseChannelRelease channel to look for on the system.—platformoptionalBrowserPlatformDetermines which platform the browser will be suited for.Auto-detected.其中browser与channel是必填项platform可省略——省略时会调用自动检测逻辑见下文「平台自动检测」因此跨平台脚本只需提供browser与channel两个字段即可开箱即用。browser选择要探测的浏览器字段类型为Browser枚举定义见 docs/browsers-api/browsers.browser.md表示当前支持的浏览器种类成员值CHROMEchromeCHROMEDRIVERchromedriverCHROMEHEADLESSSHELLchrome-headless-shellCHROMIUMchromiumFIREFOXfirefox需要说明的是从 launch.ts 与 browser-data/chrome.ts 的源码结构看resolveSystemExecutablePaths()当前按browser / platform / channel三个维度分发Chrome 相关通道stable/beta/dev/canary的各平台安装位置映射实现得最为完整。channel决定扫描哪个发布通道字段类型为ChromeReleaseChannel枚举见 docs/browsers-api/browsers.chromereleasechannel.md对应 Chrome 的四种发布通道成员值典型用途STABLEstable生产环境的稳定版本BETAbeta提前体验次版本功能DEVdev更早的开发通道构建CANARYcanary每日构建的尝鲜版本channel直接决定了函数「去哪找、找什么后缀的目录」例如 Linux 上 stable 对应/opt/google/chrome而 canary 对应/opt/google/chrome-canary。platform需要时可覆盖的架构维度字段类型为BrowserPlatform枚举见 docs/browsers-api/browsers.browserplatform.md枚举值即操作系统与 CPU 架构的组合标识成员值语义LINUXlinuxLinux x64LINUX_ARMlinux_armLinux arm64MACmacmacOS x64MAC_ARMmac_armmacOS arm64Apple SiliconWIN32win3232 位 WindowsWIN64win6464 位 Windows该字段是可选项默认值在文档与源码注释中均标注为Auto-detected。通常只有在「本机运行、但目标定位另一平台安装路径」这类交叉场景下才需要显式传入。平台自动检测的底层实现当SystemOptions.platform未传时computeSystemExecutablePath()会调用 detectPlatform.ts 中的detectBrowserPlatform()完成推断export function detectBrowserPlatform(): BrowserPlatform | undefined { const platform os.platform(); const arch os.arch(); switch (platform) { case darwin: return arch arm64 ? BrowserPlatform.MAC_ARM : BrowserPlatform.MAC; case linux: return arch arm64 ? BrowserPlatform.LINUX_ARM : BrowserPlatform.LINUX; case win32: return arch x64 || // Windows 11 for ARM supports x64 emulation (arch arm64 isWindows11(os.release())) ? BrowserPlatform.WIN64 : BrowserPlatform.WIN32; default: return undefined; } }值得注意的两个实现细节macOS arm64 优先识别为MAC_ARMApple Silicon 上自动落入 arm64 专用平台标识Windows on ARM 特判若运行 Windows 11版本号10.0.22000及以上即使 CPU 架构是 arm64也因系统具备 x64 模拟能力而被归类为WIN64见同文件 isWindows11()。如果平台既无法自动检测、用户也未显式指定computeSystemExecutablePath()会抛出如下错误launch.tsCannot download a binary for the provided platform: ${os.platform()} (${os.arch()})computeSystemExecutablePathSystemOptions 的消费者SystemOptions 被 launch.ts 中的computeSystemExecutablePath(options, validatePath true)使用其工作流程如下export function computeSystemExecutablePath( options: SystemOptions, validatePath true, ): string { options.platform ?? detectBrowserPlatform(); if (!options.platform) { throw new Error( Cannot download a binary for the provided platform: ${os.platform()} (${os.arch()}), ); } const paths resolveSystemExecutablePaths( options.browser, options.platform, options.channel, ); for (const path of paths) { try { accessSync(path); return path; } catch {} } if (!validatePath) { return paths[0]; } throw new Error( Could not find Google Chrome executable for channel ${options.channel} at:${paths.map(...)}., ); }流程要点platform 兜底先执行platform ?? detectBrowserPlatform()补齐默认值保证后续路径解析有平台上下文解析候选路径列表由resolveSystemExecutablePaths(browser, platform, channel)返回一组该平台/通道的「已知安装位置」逐个用accessSync探活返回第一个真实存在的路径两个出口全部候选都不存在且validatePath false时直接返回第一个候选路径不抛错适合「只想要路径、是否安装由外部决定」的用法validatePath true默认时抛错错误信息会逐行列出全部被检查过的候选路径便于排查。各平台真实探测的候选安装位置SystemOptions 能「跨平台工作」的底气来自 browser-data/chrome.ts 中硬编码的已知安装位置表。以 Chrome 为例探测逻辑按平台分支如下Linux含 WSL按通道分别检查/opt/google/chrome/chromestable、/opt/google/chrome-beta/chromebeta、/opt/google/chrome-unstable/chromedev、/opt/google/chrome-canary/chromecanary随后还会尝试通过getWslLocation(channel)追加 WSL 环境下的候选位置macOS检查/Applications/Google Chrome.app/Contents/MacOS/Google Chromestable以及 Beta、Dev、Canary 对应命名*.app中的同名可执行文件Windows从一组环境变量源码中的WINDOWS_ENV_PARAM_NAMES读取安装根目录并内置C:\Program Files、C:\Program Files (x86)、D:\Program Files、D:\Program Files (x86)作为环境变量配置错误时的回退前缀再拼接出各通道目录下的chrome.exe。从源码结构可以推断这种「先收集一批候选路径 → accessSync 逐一验证 → 返回首个命中」的设计正是为了让platform自动检测与手动覆盖都能获得一致且可预期的结果。完整可运行示例把 SystemOptions 接入真实的浏览器启动流程可以这样写可直接在 Node 端运行import { computeSystemExecutablePath, Browser, ChromeReleaseChannel, launch, CDP_WEBSOCKET_ENDPOINT_REGEX, } from puppeteer/browsers; // 1. 组装 SystemOptions仅指定浏览器与通道platform 交给自动检测 const options { browser: Browser.CHROME, channel: ChromeReleaseChannel.STABLE, }; // 2. 定位系统已安装的 Chrome const executablePath computeSystemExecutablePath(options); console.log(Found Chrome at:, executablePath); // 3. 直接启动它并等待 CDP WebSocket 端点 const proc launch({ executablePath, args: [--remote-debugging-port0], }); const wsEndpoint await proc.waitForLineOutput(CDP_WEBSOCKET_ENDPOINT_REGEX); console.log(DevTools listening on, wsEndpoint);若机器上并未安装对应通道的浏览器默认会抛出带全部候选路径的错误例如Could not find Google Chrome executable for channel stable at: - /opt/google/chrome/chrome此时可以做两件事把channel换成实际安装的通道或在computeSystemExecutablePath(options, false)中关闭路径校验改为自行判断返回结果是否存在。启动细节进程信号处理、dumpio、pipe等可参考 Process 类与 launch() 实现。总结什么时候该用 SystemOptions优先复用系统浏览器不想为每个环境重新下载浏览器希望 CI/本地一致指向已安装的 Chrome 通道时多通道测试矩阵同一机器同时装有 stable 与 beta可通过channel快速切换被测版本交叉平台定位配合显式platform在打包/远程场景中描述目标平台的安装路径。使用时记住三件事browser与channel必填platform省略即自动检测darwin arm64 → MAC_ARM、Windows 11 on ARM → WIN64 等边界已内置处理拿到的路径默认是「已被accessSync验证真实存在」的路径必要时通过第二个参数validatePath关闭该校验。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考