@puppeteer/browsers computeSystemExecutablePath 解析：如何精确定位系统中已安装的 Chrome 可执行文件

computeSystemExecutablePath() 是 Puppeteer 浏览器管理工具链（@puppeteer/browsers，本仓库位于 packages/browsers）中负责"复用系统里已经装好的 Chrome，而不是下载 Chrome for Testing"的核心入口函数。本文围绕该函数的功能签名、SystemOptions 参数体系、各平台已知安装路径的判定规则、validatePath 校验语义、CLI 与 Puppeteer 上层集成方式展开，帮助你理解 puppeteer.launch({channel: ...}) 与 npx @puppeteer/browsers launch chrome@stable --system 背后"按发布渠道探测系统浏览器"的完整实现机制。

函数定位：在系统全局安装中按渠道定位 Chrome

根据本仓库的 API 文档（docs/browsers-api/browsers.computesystemexecutablepath.md）与源码注释（packages/browsers/src/launch.ts#L96-L100），该函数的行为可以概括为：

给定一个发布渠道（release channel）名称，通过检查各操作系统上已知的 Chrome 安装位置，返回一个系统级（system-wide）Chrome 安装的可执行文件路径；如果在该函数预期的路径上找不到 Chrome 实例，则会抛出错误。

它与同一模块中的 computeExecutablePath 形成互补：后者解析的是由本工具下载、存放在本地 cache 目录中的浏览器二进制；前者解析的则是用户自己通过 Chrome 官方安装包安装到系统目录（如 /Applications/、C:\Program Files、/opt/google/）的普通 Chrome。它不会执行下载，也不会向网络发起任何请求，只做纯本地的路径探测。

函数签名与完整语义

该函数是 @puppeteer/browsers 公开 API 的一部分（从 packages/browsers/src/main.ts#L15 可看到它被统一 re-export），完整类型签名如下：

export declare function computeSystemExecutablePath(
  options: SystemOptions,
  validatePath?: boolean,
): string;

参数一览

参数	类型	是否可选	说明
options	SystemOptions	必填	指定要查找的浏览器、发布渠道与目标平台
validatePath	boolean	可选（默认 true）	是否对候选路径做真实存在性校验；为 false 时直接返回"最可能"的第一个候选路径，不做文件系统检查

返回值类型为 string，即解析出的 Chrome 可执行文件绝对路径；若找不到且 validatePath 为 true，则抛出 Error。

SystemOptions：三个字段的职责划分

对照 SystemOptions 接口文档 与源码中的接口定义（packages/browsers/src/launch.ts#L79-L94），options 对象共包含三个属性：

属性	类型	说明
browser	Browser（必填）	决定要查找哪个浏览器
channel	ChromeReleaseChannel（必填）	决定在系统上查找哪个发布渠道
platform	BrowserPlatform（可选）	决定适配哪个操作系统平台，默认自动探测（Auto-detected）

其中 Browser 枚举包含 chrome、chromedriver、chrome-headless-shell、chromium、firefox 五种取值；ChromeReleaseChannel 枚举固定为四个字符串值："stable"、"beta"、"dev"、"canary"。注意：platform 的自动探测在解析失败时会抛出明确错误，例如：

Cannot download a binary for the provided platform: linux (x64)

（此消息源自 packages/browsers/src/launch.ts#L108-L113。）

典型用法

直接以编程方式调用：

import {
  Browser,
  ChromeReleaseChannel,
  computeSystemExecutablePath,
} from '@puppeteer/browsers';

const executablePath = computeSystemExecutablePath({
  browser: Browser.CHROME,           // 仅 Chrome 支持系统探测
  channel: ChromeReleaseChannel.STABLE, // 也可以写 'beta' / 'dev' / 'canary'
});

console.log(executablePath);

在 CI / 打包脚本等场景中，如果希望"Chrome 存在就用系统的、不存在就返回首选路径以便随后给出可读错误"，可以关闭校验：

const executablePath = computeSystemExecutablePath(
  {
    browser: Browser.CHROME,
    channel: ChromeReleaseChannel.BETA,
    platform: BrowserPlatform.LINUX, // 手动指定平台，跳过自动探测
  },
  false, // validatePath = false：不检查文件是否存在
);

平台 × 渠道：已知安装位置的判定规则

这是整个函数的核心价值所在：无需在 PATH 中查找、无需调用 which，而是依据一份"操作系统已知的 Chrome 安装约定表"直接推断。从源码结构看，该逻辑被拆成两层：

1. 顶层分发函数 resolveSystemExecutablePaths（内部标记，@internal）：根据 browser 参数做分发，非 Chrome 类型一律抛错；
2. 平台级实现 chrome.resolveSystemExecutablePaths：按 Windows / macOS / Linux（含 WSL）分别枚举候选路径。

Linux（含 WSL 场景）

Linux 上每个渠道对应 /opt/google/ 下的一个固定目录（packages/browsers/src/browser-data/chrome.ts#L249-L279）：

渠道	Linux 候选路径
stable	/opt/google/chrome/chrome
beta	/opt/google/chrome-beta/chrome
dev	/opt/google/chrome-unstable/chrome
canary	/opt/google/chrome-canary/chrome

如果当前环境是 WSL（检测到 wslinfo --version 可用），还会通过 cmd.exe /c echo %VARIABLE% 读取 Windows 侧的 PROGRAMFILES、ProgramW6432、ProgramFiles(x86)、LOCALAPPDATA 环境变量，再用 wslpath 将 Windows 路径转换为 WSL 挂载路径（如 /mnt/c/...），并追加到候选列表末尾，实现"在 WSL 里驱动宿主机安装的 Windows 版 Chrome"。WSL 探测失败会被静默忽略，不影响原生 Linux 路径的解析。

macOS

macOS 每个渠道对应 /Applications 下的一个 .app 包，且只返回唯一候选路径（packages/browsers/src/browser-data/chrome.ts#L301-L320）：

渠道	macOS 候选路径
stable	/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
beta	/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta
dev	/Applications/Google Chrome Dev.app/Contents/MacOS/Google Chrome Dev
canary	/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary

Windows

Windows 端候选列表最为复杂。它以环境变量 PROGRAMFILES、ProgramW6432、ProgramFiles(x86)、LOCALAPPDATA 的取值为前缀（去重后保持读取顺序），并兜底追加 C:\Program Files、C:\Program Files (x86)、D:\Program Files、D:\Program Files (x86) 四个常见目录，最后拼接各渠道的子路径（packages/browsers/src/browser-data/chrome.ts#L165-L200）：

渠道	追加的相对子路径
stable	Google\Chrome\Application\chrome.exe
beta	Google\Chrome Beta\Application\chrome.exe
dev	Google\Chrome Dev\Application\chrome.exe
canary	Google\Chrome SxS\Application\chrome.exe

该枚举行为被单元测试锁定在 packages/browsers/test/src/chrome/chrome-data.test.ts#L91-L135：测试把上述环境变量改成 C:\ProgramFiles 等假值后，断言 DEV 渠道会依次产出 7 个候选路径——环境变量前缀优先、硬编码兜底路径在后；macOS BETA 与 Linux CANARY 则各自断言了单一/首个路径。

返回值与错误处理：validatePath 到底校验了什么

候选路径生成之后，真正的返回与报错逻辑在 packages/browsers/src/launch.ts#L114-L137：

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(
    path => {
      return `\n - ${path}`;
    },
  )}.`,
);

这里包含三条值得注意的执行路径：

1. 按序探测并返回第一个存在的路径：函数对候选路径列表逐一调用 Node 的 accessSync()，命中即返回。这解释了 Windows 上为什么候选列表排序重要——排在最前、最"权威"的安装位置（环境变量所指目录）会优先被采用。

2. 全部未命中时的两种结局：

   • validatePath = true（默认）→ 抛出错误，错误消息会逐行列出所有已检查的候选路径，便于排查，例如：

     Could not find Google Chrome executable for channel 'canary' at:
      - /opt/google/chrome-canary/chrome.
     

   • validatePath = false → 放弃文件系统校验，直接返回列表首个候选路径。此时即便 Chrome 并未安装，函数也不会抛错，适合上层自行拼接更友好的报错信息。

3. 探测属于纯本地操作：校验只依赖 accessSync，不会启动 Chrome 进程，也不会读取注册表之外的网络资源。

使用限制：为什么只有 Chrome 能走"系统探测"

computeSystemExecutablePath 名称中虽未限定浏览器，但其底层分发表 resolveSystemExecutablePaths 对 chromedriver、chrome-headless-shell、chromium、firefox 一律直接抛出如下错误：

System browser detection is not supported for ${browser} yet.

只有 Browser.CHROME 会进入 chrome.resolveSystemExecutablePaths 做真正的路径解析。这一点与 browsers-api 总览文档 中"仅 Chrome/Chromium 支持启动系统浏览器"的 Known limitations 声明一致；严格来说，当前源码中系统级路径探测仅对 Browser.CHROME 完成实现。若需要查找 Firefox、Chromium 等浏览器，应当改用 computeExecutablePath 配合 cacheDir（指向已下载的缓存目录）。

在 CLI 中的落地：launch --system

@puppeteer/browsers 自带 CLI（总览见 docs/browsers-api/index.md），launch 子命令提供了 --system 开关，其官方示例为：

npx @puppeteer/browsers launch chrome@canary --system
# 尝试定位系统中已安装的 Canary 版 Chrome 并启动它

从实现看（packages/browsers/src/CLI.ts#L406-L444），--system 为布尔选项，说明为"Search for a browser installed on the system instead of the cache folder"；当它被置位时，CLI 会把 chrome@<channel> 中的渠道标签通过 verifyChromeReleaseChannel() 校验后，转交给 computeSystemExecutablePath() 求得路径，再调用 launch() 启动进程；否则走 computeExecutablePath() 从缓存目录解析。因此 CLI 支持的全部组合形如：

# 启动系统中安装的稳定版 Chrome
npx @puppeteer/browsers launch chrome@stable --system

# 启动系统中安装的 Dev / Beta 版 Chrome
npx @puppeteer/browsers launch chrome@dev --system
npx @puppeteer/browsers launch chrome@beta --system

若在未安装对应渠道 Chrome 的机器上执行，会得到与上文一致的"Could not find Google Chrome executable for channel ..."报错，同时逐条列出被检查过的路径。

在 Puppeteer 中的落地：channel 参数的后端

对绝大多数 Puppeteer 用户而言，并不会直接调用本函数，而是通过 Puppeteer 的 channel 启动选项间接触发。在 puppeteer-core 的 ChromeLauncher 中（packages/puppeteer-core/src/node/ChromeLauncher.ts#L299-L314），executablePath(channel) 方法在收到渠道参数时，会把 Puppeteer 侧的渠道枚举转换为 @puppeteer/browsers 的 ChromeReleaseChannel，随后调用：

return computeSystemExecutablePath(
  {
    browser: SupportedBrowsers.CHROME,
    channel: convertPuppeteerChannelToBrowsersChannel(channel),
  },
  validatePath, // 默认 true，可被调用方关闭
);

因此，日常项目中的这段代码之所以能够"直接用电脑上已装的 Chrome，而不下载浏览器"，底层执行的正是本文介绍的路径探测逻辑：

import puppeteer from 'puppeteer';

// 使用系统已安装的稳定版 Chrome（不下载 Chrome for Testing）
const browser = await puppeteer.launch({channel: 'chrome'});

// 也可以指定其他渠道：'chrome-beta'、'chrome-dev'、'chrome-canary'
const browser2 = await puppeteer.launch({channel: 'chrome-canary'});

与 computeExecutablePath 的选择建议

最后用一张对照表帮助你在实际项目中快速决策（两份 API 文档分别位于 docs/browsers-api/browsers.computeexecutablepath.md 与 docs/browsers-api/browsers.computesystemexecutablepath.md）：

对比维度	computeExecutablePath	computeSystemExecutablePath
查找目标	本地缓存目录（cacheDir）中已下载的浏览器	系统全局安装的 Chrome
输入核心	cacheDir + buildId	channel（+ 可选 platform）
是否联网/下载	否（仅路径计算）	否（仅本地路径探测 + accessSync）
支持的浏览器	chrome / chromium / firefox / chromedriver / chrome-headless-shell	当前仅 chrome
找不到时行为	仅返回拼接路径，不校验	默认抛错并列出全部候选路径；validatePath=false 时返回首选候选

在 Puppeteer 自动化与 CI 场景中，经验法则是：希望行为可复现、环境干净，用 computeExecutablePath（配合自动下载）；希望复用开发者或服务器上已装的 Chrome、省去下载与磁盘占用，用 computeSystemExecutablePath（通过 channel 指定渠道）。若宿主机的安装位置偏离官方默认路径（例如 macOS 下的非 /Applications 安装），该函数将无法命中——这是其"按已知安装位置探测"设计边界的固有体现。