Puppeteer Browsers 包中的 ChromeReleaseChannel 枚举：四个发布通道的解析与实战用法

ChromeReleaseChannel 是 @puppeteer/browsers 子包（位于本仓库 packages/browsers）对外公开的核心枚举类型，用于描述 Google Chrome 的四种发布通道（Release Channel）。它贯穿浏览器的下载解析与系统安装定位两条关键链路：既是把 chrome@stable、chrome@canary 这类标签解析为具体 buildId 的依据，也是让工具在操作系统上找到指定通道 Chrome 可执行文件的依据。读完本文，你将掌握该枚举四个成员的取值、底层定义位置、在 CLI 与源码 API 中的实际用法，以及各平台下每个通道对应的默认安装路径。

枚举概览：四个成员与字符串值

根据官方 API 文档 browsers.chromereleasechannel.md 的定义，ChromeReleaseChannel 是一个带字符串值的 TypeScript 枚举（export declare enum ChromeReleaseChannel），共包含 4 个成员：

成员	值	对应 Chrome 发布线
STABLE	"stable"	Chrome 正式版（稳定版）
BETA	"beta"	Chrome Beta 测试版
DEV	"dev"	Chrome Dev 开发者版
CANARY	"canary"	Chrome Canary 金丝雀版（每日构建）

这四个值在设计上全部使用小写字符串作为取值，方便直接用于 CLI 参数（如 chrome@stable）、HTTP 请求的 JSON 序列化以及版本服务数据的键名匹配。文档本身是 API 参考的自动生成页，只给出了签名与成员表；要理解它的完整语义，需要进入其源码定义与消费方。

源码中的正式定义与校验逻辑

枚举的真正定义位于 packages/browsers/src/browser-data/types.ts#L65-L70，与文档展示的成员一一对应：

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

同一个文件中还提供了配套的运行时校验函数 verifyChromeReleaseChannel：它遍历 Object.values(ChromeReleaseChannel) 判断传入值是否属于合法通道，不合法时抛出 Invalid Chrome channel: ${value} 错误。CLI 在解析用户输入的 channel 字符串后会调用该校验，例如 CLI.ts 中 --system 启动流程通过 verifyChromeReleaseChannel(args.browser.buildId) 把输入转换为枚举实例。

该枚举对外导出链为：main.ts 的公共导出 从 browser-data 模块统一 re-export 了 ChromeReleaseChannel、resolveBuildId、Browser、BrowserPlatform 等符号，再经由 browser-data.ts 的 聚合导出 与 CLI 保持同一数据源，确保文档、CLI、API 三类入口行为一致。

用法一：把通道解析为可下载的 buildId

ChromeReleaseChannel 最常见的用途，是指定要下载哪一个发布线的 Chrome。

在 packages/browsers/src/browser-data/chrome.ts#L137-L164 中，resolveBuildId(channel) 采用了重载签名，接受 ChromeReleaseChannel 枚举或普通字符串：

• 传入合法的枚举值时，调用 getLastKnownGoodReleaseForChannel 去拉取 Chrome for Testing 的 last-known-good-versions.json 清单，把 stable/beta/dev/canary 解析为形如 115.0.5790.98 的具体版本号（"last known good"，即该通道最近一次通过验证的构建）；
• 传入纯数字字符串时按 Milestone（里程碑版本，如 115）处理，查询 latest-versions-per-milestone.json；
• 传入 x.y.z 三段式字符串时按 Build 前缀处理，查询 latest-patch-versions-per-build.json；
• 均不匹配则返回 undefined。

而更上层的聚合入口 browser-data.ts 的 resolveBuildId(browser, platform, tag) 会把 BrowserTag（如 LATEST、BETA）与 ChromeReleaseChannel 打通。例如 resolveBuildIdForBrowserTag 中的 Chrome 分支：

• LATEST 与 CANARY → chrome.resolveBuildId(ChromeReleaseChannel.CANARY)；
• BETA → ChromeReleaseChannel.BETA；
• DEV → ChromeReleaseChannel.DEV；
• STABLE → ChromeReleaseChannel.STABLE。

同样的映射也作用于 chromedriver 与 chrome-headless-shell 的解析逻辑（同一文件 L109-L152）。注意 Chromium 并不走通道体系——其分支明确要求仅使用 latest，其余标签一律报错，这也是区分「Chromium（按快照号）」与「Chrome（按发布通道）」两种下载模型的关键。

用法二：定位系统已安装的指定通道 Chrome

第二个高频场景是本机已安装 Chrome，按通道找到它的可执行文件。这一步由 launch.ts 中的 computeSystemExecutablePath 完成，其 SystemOptions 接口的第 93 行明确指出 channel 字段即 ChromeReleaseChannel：

export interface SystemOptions {
  browser: Browser;
  channel: ChromeReleaseChannel;  // 要查找的发布通道
  platform?: BrowserPlatform;     // 默认自动检测
}

实现细节在 resolveSystemExecutablePaths：它会按平台与通道拼接候选路径，返回后逐个用 accessSync 探测是否存在。以下是源码中写死的各平台通道路径（Linux 与 macOS 部分）：

通道	Linux（/opt/google）	macOS（/Applications）
STABLE	/opt/google/chrome/chrome	Google Chrome.app/Contents/MacOS/Google Chrome
BETA	/opt/google/chrome-beta/chrome	Google Chrome Beta.app/.../Google Chrome Beta
CANARY	/opt/google/chrome-canary/chrome	Google Chrome Canary.app/.../Google Chrome Canary
DEV	/opt/google/chrome-unstable/chrome	Google Chrome Dev.app/.../Google Chrome Dev

Windows 侧（getChromeWindowsLocation）则从 PROGRAMFILES、ProgramFiles(x86)、LOCALAPPDATA 等环境变量前缀推导，目录名同样随通道区分：Chrome、Chrome Beta、Chrome SxS（Canary）、Chrome Dev。若所有候选路径都不存在，会抛出包含完整候选列表的错误信息；此外 resolveDefaultUserDataDir 也按通道返回不同的用户数据目录，保证多个通道可并行安装、互不覆盖配置。

CLI 层对这套能力的封装体现在 CLI.ts 的 launch 子命令：当传入 --system（其选项说明为"Search for a browser installed on the system instead of the cache folder"）时，用 verifyChromeReleaseChannel 校验后调用 computeSystemExecutablePath 定位系统 Chrome；否则回退到 computeExecutablePath 从缓存目录按 buildId 找浏览器。

用法三：CLI 中直接以 chrome@<channel> 选择通道

对于不写代码、只做运维或 CI 集成的情况，@puppeteer/browsers 提供的 CLI 命令把枚举值直接作为浏览器标签使用。在 CLI.ts 的 install 命令示例 中可以看到一整套按通道安装的写法：

# 安装 Chrome 稳定版（当前最新可用构建）
npx @puppeteer/browsers install chrome@stable

# 安装 Chrome Beta 测试版
npx @puppeteer/browsers install chrome@beta

# 安装 Chrome Dev 开发者版
npx @puppeteer/browsers install chrome@dev

# 安装 Chrome Canary 金丝雀版
npx @puppeteer/browsers install chrome@canary

# 其它支持形式：最新版 / 里程碑 / 精确前缀
npx @puppeteer/browsers install chrome@latest
npx @puppeteer/browsers install chrome@115

该通道标签体系同样覆盖 chromedriver@canary、chrome-headless-shell@beta 等衍生浏览器——它们内部都会被映射到本文所讲的四个 ChromeReleaseChannel 枚举值。CLI 参数解析后通过 resolveBuildId 得到真实版本号再执行下载，与纯 JS API 走的是同一条解析管线，因此在 Puppeteer 脚本、CI 脚本与手工调试之间可以无缝切换。

与相邻概念的边界

• 与 Firefox 通道区分：ChromeReleaseChannel 只描述 Chrome 系浏览器。Firefox 有自己独立的 FirefoxChannel 枚举（nightly/beta/stable/devedition/esr，见 firefox.ts），两者在聚合层分别处理，不能混用。若对 Chrome 传入 nightly 这类标签，源码会在 resolveBuildIdForBrowserTag 中直接抛错（... is not available for Chrome）。
• 与 BrowserTag 区分：BrowserTag（见 types.ts#L43-L52）是跨浏览器、跨通道的"标签"层抽象，包含 canary/nightly/beta/dev/devedition/stable/esr/latest；ChromeReleaseChannel 则是 Chrome 专有的"通道"层。二者的对应关系正是在 resolveBuildIdForBrowserTag 中建立的。
• 与 BrowserPlatform 区分：通道决定"要哪条发布线"，平台（linux/mac/win64 等）决定"为哪个操作系统取包"，二者共同决定最终的下载 URL 与本地路径，任何一方缺失都会导致解析失败。

小结

ChromeReleaseChannel 虽然只是一个四成员的字符串枚举，却是 Chrome 相关下载与启动逻辑的枢纽：在 types.ts 定义并被校验函数约束，在 chrome.ts 中驱动版本解析与系统路径映射，在 launch.ts 中决定查找哪个通道的本地安装，最终统一暴露给 CLI 的 chrome@stable/chrome@beta/chrome@dev/chrome@canary 形式。理解它，就把握住了 Puppeteer Browsers 子包中"用哪个版本线、去哪里找、装到哪里"这条主脉络。

想要进一步查阅完整 API，可参考 browsers-api/index.md 中与 install、resolveBuildId、computeSystemExecutablePath 等相关的页面，或在 packages/browsers 中直接阅读上述源码文件验证各通道映射细节。