Puppeteer 中 ChromeReleaseChannel 类型详解：用 launch({ channel }) 启动系统安装的 Chrome 通道版

本文围绕 Puppeteer API 文档中的 ChromeReleaseChannel 类型展开：它是一个由四个字符串字面量组成的联合类型，决定了 puppeteer.launch() 在找不到 bundled 浏览器时，去系统已知安装位置定位哪个 Chrome 通道（Stable / Beta / Dev / Canary）的可执行文件。读完本文，你能掌握 channel 选项的正确用法、四个通道值与底层 @puppeteer/browsers 枚举的映射关系，以及 Puppeteer 在各操作系统下解析系统 Chrome 路径和默认用户数据目录的源码级实现。

一、类型签名与取值范围

Puppeteer 官方 API 文档 ChromeReleaseChannel type 给出的定义非常简短：

export type ChromeReleaseChannel =
  'chrome' | 'chrome-beta' | 'chrome-canary' | 'chrome-dev';

这是一个纯字符串联合类型，四个取值分别对应 Chrome 的四条发布通道：

取值	对应通道	典型用途
'chrome'	Stable（稳定版）	日常开发、与最终用户环境保持一致
'chrome-beta'	Beta（测试版）	提前验证即将发布的特性
'chrome-dev'	Dev（开发版）	跟踪较新的 Chromium 特性
'chrome-canary'	Canary（每日构建版）	实验性 API 的尝鲜验证

该类型在 LaunchOptions 中作为 channel 选项的类型声明：

export interface LaunchOptions extends ConnectOptions {
  /**
   * If specified for Chrome, looks for a regular Chrome installation at a known
   * system location instead of using the bundled Chrome binary.
   */
  channel?: ChromeReleaseChannel;
  // ...
}

注意 LaunchOptions 继承自 ConnectOptions，因此 channel 不仅适用于 launch()，也出现在连接配置 ConnectOptions 中——它同样会用于推断“指定通道对应的默认用户数据目录”。

二、基本用法：启动系统安装的 Chrome

不传 channel 时，Puppeteer 使用安装时下载的 bundled Chrome（Chrome for Testing）。指定 channel 后，它会改为在操作系统的已知安装位置寻找对应通道的 Chrome：

import puppeteer from 'puppeteer';

// 启动系统安装的 Chrome 稳定版
const browser = await puppeteer.launch({channel: 'chrome'});

// 启动 Chrome Canary，验证某个实验性特性
const canary = await puppeteer.launch({channel: 'chrome-canary'});

console.log(await canary.version());
await canary.close();

各平台下“已知安装位置”的来源，由 resolveSystemExecutablePaths 决定，源码中给出的候选路径如下（以 Linux 为例，见 chrome.ts）：

通道	Linux 路径	macOS 路径	Windows 路径（相对环境变量）
chrome（Stable）	/opt/google/chrome/chrome	/Applications/Google Chrome.app/Contents/MacOS/Google Chrome	Google\Chrome\Application\chrome.exe
chrome-beta	/opt/google/chrome-beta/chrome	/Applications/Google Chrome Beta.app/...	Google\Chrome Beta\Application\chrome.exe
chrome-canary	/opt/google/chrome-canary/chrome	/Applications/Google Chrome Canary.app/...	Google\Chrome SxS\Application\chrome.exe
chrome-dev	/opt/google/chrome-unstable/chrome	/Applications/Google Chrome Dev.app/...	Google\Chrome Dev\Application\chrome.exe

Windows 上的具体搜索逻辑见 getChromeWindowsLocation：它遍历 PROGRAMFILES、ProgramW6432、ProgramFiles(x86)、LOCALAPPDATA 等环境变量并附加通道对应的目录后缀；若环境变量都缺失，resolveSystemExecutablePaths 还会回退到 C:\Program Files、D:\Program Files 等常见前缀。此外该函数对 WSL 场景做了专门处理（getWslLocation），通过 cmd.exe 读取 Windows 环境变量、再用 wslpath 把 Windows 路径转换为挂载盘路径，因此在 WSL 中也可以直接命中 Windows 侧安装的 Chrome。

一个值得注意的细节：Canary 在 Windows/Linux 上的目录名并不叫 Chrome Canary——Windows 侧是 Google\Chrome SxS（SxS 即 side-by-side 的遗留命名），Linux 侧则是 chrome-canary；而 Dev 通道在 Linux 上的目录名是 chrome-unstable。这些差异都原样保留在源码的 switch 分支里，排查“为什么找不到浏览器”时可以直接对照上表。

三、puppeteer-core 中的强制约束

使用官方 puppeteer 包时 bundled 浏览器会自动下载；而 puppeteer-core 不附带任何浏览器，channel 成为指定浏览器的主要方式之一。这一点在 ChromeLauncher 中有硬性校验：

channel || !this.puppeteer._isPuppeteerCore,
`An \`executablePath\` or \`channel\` must be specified for \`puppeteer-core\``,
// ...
chromeExecutable = channel
  ? await this.executablePath(channel)
  : executablePath;

也就是说，在 puppeteer-core 场景下 executablePath 与 channel 二选一必填：前者指向任意自定义二进制文件，后者则交给上述系统路径解析流程。若两处解析都失败，launch.ts 会抛出形如 Could not find Google Chrome executable for channel 'chrome-canary' at: ... 的错误，并列出所有已尝试的候选路径，方便按图索骥。

四、通道值的内部映射：从字符串联合类型到枚举

Puppeteer 对外暴露的是字符串联合类型，而浏览器下载/解析模块 @puppeteer/browsers 内部使用枚举 ChromeReleaseChannel：

export enum ChromeReleaseChannel {
  STABLE = 'stable',
  DEV = 'dev',
  CANARY = 'canary',
  BETA = 'beta',
}

两者之间的换算集中在 convertPuppeteerChannelToBrowsersChannel：

export function convertPuppeteerChannelToBrowsersChannel(
  channel: ChromeReleaseChannel,
): BrowsersChromeReleaseChannel {
  switch (channel) {
    case 'chrome':
      return BrowsersChromeReleaseChannel.STABLE;
    case 'chrome-dev':
      return BrowsersChromeReleaseChannel.DEV;
    case 'chrome-beta':
      return BrowsersChromeReleaseChannel.BETA;
    case 'chrome-canary':
      return BrowsersChromeReleaseChannel.CANARY;
  }
}

可以看出命名规则的差异：Puppeteer 层的值以 chrome 为前缀（如 'chrome-beta'），而 browsers 层是裸的通道名（'beta'）。browsers 包还提供了 verifyChromeReleaseChannel 做运行时校验，非法取值会抛出 Invalid Chrome channel: ... 错误。

五、通道到具体版本号的解析

除了定位“已安装”的 Chrome，通道值还可以用于查询 Chrome for Testing 的线上版本。getLastKnownGoodReleaseForChannel 会请求 Chrome for Testing 的版本清单 last-known-good-versions.json，并把清单中的通道键统一转成小写（接口返回的是 Stable、Beta 这类首字母大写写法）后取出对应条目的 version 与 revision：

export async function getLastKnownGoodReleaseForChannel(
  channel: ChromeReleaseChannel,
): Promise<{version: string; revision: string}> {
  const data = (await getJSON(
    new URL(`${baseVersionUrl}/last-known-good-versions.json`),
  )) as {channels: Record<string, {version: string}>};

  for (const channel of Object.keys(data.channels)) {
    data.channels[channel.toLowerCase()] = data.channels[channel]!;
    delete data.channels[channel];
  }
  // ...
}

基于它，resolveBuildId 支持三种输入形态，这也是理解通道语义的好入口：

• 传入一个合法的通道名（如 'chrome-beta' 对应的枚举）：走 getLastKnownGoodReleaseForChannel，返回该通道当前最新的 version；
• 传入纯数字字符串（如 '120'）：视为 milestone，走 getLastKnownGoodReleaseForMilestone；
• 传入三段式前缀（如 '112.0.23'）：视为 build 前缀，走 getLastKnownGoodReleaseForBuild。

也就是说，ChromeReleaseChannel 并不只是“本地路径的索引”，它同时是向 Chrome for Testing 版本服务发起解析的查询键，下载 URL 的构造（resolveDownloadUrl）也依赖解析出的 buildId 与平台目录名。

六、通道与默认用户数据目录的关联

channel 的另一个影响面是默认 userDataDir 的推断。resolveDefaultUserDataDir 按“平台 × 通道”给出与真实 Chrome 安装一致的默认配置目录，例如：

• Linux：$XDG_CONFIG_HOME/google-chrome（Stable）与 .../google-chrome-beta、.../google-chrome-canary、.../google-chrome-unstable（其余通道），其中配置根目录可通过 CHROME_CONFIG_HOME 或 XDG_CONFIG_HOME 环境变量覆盖；
• macOS：~/Library/Application Support/Google/Chrome、.../Chrome Beta、.../Chrome Dev、.../Chrome Canary；
• Windows：%LOCALAPPDATA%\Google\Chrome\User Data 及对应 Chrome Beta、Chrome SxS、Chrome Dev 子目录。

这与第五节中的 WSL 支持配合使用，可以在 Linux/WSL 上复用 Windows 侧 Chrome 通道的数据目录约定。

七、实践要点小结

• 何时用 channel：希望测试脚本运行在用户真实安装的 Chrome 通道上（而不是 bundled 的 Chrome for Testing）时使用；puppeteer-core 场景下它与 executablePath 至少填一个，否则直接抛错。
• 命名差异要记牢：Puppeteer 层是 'chrome' | 'chrome-beta' | 'chrome-canary' | 'chrome-dev'，@puppeteer/browsers 层是 'stable' | 'beta' | 'canary' | 'dev'，映射逻辑见 convertPuppeteerChannelToBrowsersChannel。
• 找不到浏览器时：错误信息会列出全部候选路径，可对照 resolveSystemExecutablePaths 中各通道的目录约定（尤其 Windows 的 Chrome SxS 与 Linux 的 chrome-unstable 这类非直觉命名）人工确认安装位置。
• 通道还能查版本：getLastKnownGoodReleaseForChannel / resolveBuildId 表明通道值同时是 Chrome for Testing 版本清单的查询键，可用于获取某个通道当前的最新版本号。

以上所有结论均可在当前仓库中验证：类型定义见 docs/api/puppeteer.chromereleasechannel.md，选项声明见 LaunchOptions，路径解析实现见 chrome.ts，浏览器包侧的通道文档另见 browsers.chromereleasechannel.md。