@puppeteer/browsers 的 CDP_WEBSOCKET_ENDPOINT_REGEX：从浏览器输出中解析 CDP 调试端点的正确姿势

本文聚焦 @puppeteer/browsers 包的公共常量 CDP_WEBSOCKET_ENDPOINT_REGEX（对应 API 索引文档 中所描述的浏览器管理/启动模块），讲解它的定义、它在 Process 启动管道中如何工作、如何用于"启动即连接"，以及实测可验证的匹配形态。读完你可以在自己的启动流程里用 launch() + waitForLineOutput(CDP_WEBSOCKET_ENDPOINT_REGEX) 稳定拿到浏览器暴露出的 ws://... 调试地址。

背景：为什么要"从命令行输出里抓 WebSocket 地址"

Chrome/Chromium 以可调试模式启动时（例如带上 --remote-debugging-port），并不会通过文件或退出码把调试地址交给你，而是在标准输出/标准错误中打印一行形如：

DevTools listening on ws://127.0.0.1:9222/devtools/browser/xxxx

自动化工具若想立刻通过 CDP（Chrome DevTools Protocol）接管该浏览器，就必须先"听懂"这行输出、把其中的 WebSocket 端点提取出来。@puppeteer/browsers 把这一职责下沉到了启动层：Process 类会边读浏览器输出边做正则匹配，匹配成功即把捕获到的 URL 返回给调用方。

常量定义与仓库位置

在 API 文档 中，该变量的签名被描述为：

CDP_WEBSOCKET_ENDPOINT_REGEX: RegExp;

其真实实现位于源码 packages/browsers/src/launch.ts：

export const CDP_WEBSOCKET_ENDPOINT_REGEX =
  /^DevTools listening on (ws:\/\/.*)$/;

拆解这个模式可以得到三条关键语义：

• ^ 锚定行首：浏览器必须先打印 "DevTools listening on"，其它无关日志行会被直接忽略；
• (ws:\/\/.*) 是唯一的捕获组，Process 类取 match[1] 即得到完整端点；
• .* 贪婪匹配到行尾，因此端点若带 UUID 路径段（如 ws://127.0.0.1:9222/devtools/browser/<uuid>）也能被完整捕获。

它是从 main.ts 通过包入口导出的公共符号，因此你可以这样引入使用：

import {
  CDP_WEBSOCKET_ENDPOINT_REGEX,
  install,
  launch,
  computeExecutablePath,
  Browser,
} from '@puppeteer/browsers';

机制：Process 如何消费这个正则

从源码结构看，正则的消费路径清晰可循：

1. Process 构造时通过 launch.ts 的 child_process.spawn 启动浏览器进程，并对 stdout/stderr 调用 #recordStream；
2. #recordStream（launch.ts）用 Node 的 readline 接口把输出逐行缓冲进内部日志 #logs，并触发 #lineEmitter 的 'line' 事件；
3. waitForLineOutput(regex, timeout)（launch.ts）订阅 'line' 事件，逐行执行 line.match(regex)，一旦命中就 resolve(match[1])——也就是捕获组里的 WebSocket URL。

需要注意一个工程细节：#recordStream 同时挂接了 stdout 与 stderr，而 waitForLineOutput 只是按行做正则匹配，并不关心这行来自哪个流。之所以这样设计，可以从 Chrome 的实际行为推断：不同版本/通道的 Chrome 会把 "DevTools listening on ..." 打到 stdout 或 stderr，用"双流都录、按行匹配"的策略能天然规避流归属的差异，保证 CDP_WEBSOCKET_ENDPOINT_REGEX 总能命中。

waitForLineOutput 还内置了失败兜底：若浏览器进程提前退出（'exit'/'error' 事件），会以进程退出码与最近日志拼出错误信息拒绝 Promise；若超过 timeout（默认 0 表示不设超时）仍无匹配行，则抛出 TimeoutError，错误文案为 "Timed out ... while waiting for the WS endpoint URL to appear in stdout!"。

完整实操：安装、启动并解析出 CDP 端点

下面给出可直接运行的 TypeScript/ESM 流程。先保证 @puppeteer/browsers 已安装，并以浏览器缓存目录、构建号与平台参数计算可执行路径：

import {
  CDP_WEBSOCKET_ENDPOINT_REGEX,
  install,
  computeExecutablePath,
  launch,
  Browser,
  BrowserPlatform,
} from '@puppeteer/browsers';

const cacheDir = '/tmp/browsers-test';
const buildId = '118.0.5993.70'; // 换成你需要的版本，或用通道别名如 'stable'

// 1. 下载浏览器（已存在则跳过）
await install({
  cacheDir,
  browser: Browser.CHROME,
  buildId,
});

// 2. 计算可执行文件路径
const executablePath = computeExecutablePath({
  cacheDir,
  browser: Browser.CHROME,
  buildId,
  platform: BrowserPlatform.LINUX, // 按实际平台指定
});

// 3. 启动并等待 "DevTools listening on ws://..." 出现
const browser = launch({
  executablePath,
  args: ['--remote-debugging-port=9222', '--no-sandbox'],
});

try {
  const wsEndpoint = await browser.waitForLineOutput(
    CDP_WEBSOCKET_ENDPOINT_REGEX,
    30_000, // 可选超时（毫秒），避免永久挂起
  );
  console.log('CDP endpoint:', wsEndpoint);
  // 输出形如 ws://127.0.0.1:9222/devtools/browser/xxx
} finally {
  await browser.close(); // 优雅关闭（对应 Process.close，见浏览器进程 API 文档）
}

拿到 wsEndpoint 之后，即可把它交给任何 CDP 客户端（包括 Puppeteer 自身的 puppeteer.connect({browserWSEndpoint}) 一类连接逻辑）去建立会话。注意平台差异：在 browsers-api/index.md 的已知限制中写明，系统浏览器的启动目前仅支持 Chrome/Chromium，这一点对 launch 的使用同样适用。

配套的正则：WebDriver BiDi 端点解析

CDP_WEBSOCKET_ENDPOINT_REGEX 并非孤例。紧挨着它，launch.ts 定义了姊妹常量：

export const WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX =
  /^WebDriver BiDi listening on (ws:\/\/.*)$/;

两者共用同一套 Process.waitForLineOutput 匹配机制，唯一的区别是行前缀：

常量	匹配的前缀文本	典型输出示例
CDP_WEBSOCKET_ENDPOINT_REGEX	DevTools listening on	DevTools listening on ws://127.0.0.1:9222/devtools/browser/<uuid>
WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX	WebDriver BiDi listening on	WebDriver BiDi listening on ws://127.0.0.1:9222/session/<uuid>

因此，如果你的目标是把控制协议换成 WebDriver BiDi，只需把传给 waitForLineOutput 的正则换成后者，其余代码结构完全一致。

测试用例中的可验证证据

仓库测试对这一常量的行为给出了明确预期，是验证"它到底能抓到什么"的第一手依据：

• packages/browsers/test/src/chrome/launch.test.ts 先安装真实 Chrome，再 launch 并 await process.waitForLineOutput(CDP_WEBSOCKET_ENDPOINT_REGEX)，随后断言 url.startsWith('ws://127.0.0.1:9222/devtools/browser')——这与 Chrome 默认远程调试端口的形态一致；
• 同文件 L121-L140 进一步验证 getRecentLogs() 中确实包含包含该 URL 的原始输出行，交叉印证 #recordStream 的行缓冲确实落到了与正则同源的数据上；
• L162-L177 演示了启动后用 AbortController 终止进程、并以 hasClosed() 等待其退出的完整生命周期管理。

Chromium 侧的等价测试（packages/browsers/test/src/chromium/launch.test.ts）也以相同方式使用 CDP_WEBSOCKET_ENDPOINT_REGEX，说明该常量对 Chrome/Chromium 两个浏览器族都有效。

常见问题与排查思路

• 一直等不到匹配行（超时）：先确认启动参数确实带了远程调试开关（如 --remote-debugging-port），且版本属于"可通过外部进程调试"的构建。若浏览器进程在打印该行前就崩溃，waitForLineOutput 会因 'exit' 事件立即 reject，错误信息中会携带 getRecentLogs() 的近期输出，直接阅读这些日志即可定位崩溃原因。
• 正则对不上：CDP_WEBSOCKET_ENDPOINT_REGEX 要求行首严格为 DevTools listening on。若你的浏览器改造过、换了提示语（例如走 WebDriver BiDi），请换用 WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX，或仿照源码自行定义 ^<你的前缀> (ws:\/\/.*)$ 交给 waitForLineOutput。
• 端点是空字符串或残缺：请确认没有在正则层之外截断输出；捕获组是从 DevTools listening on 之后到行尾的全部内容，只要取 match[1] 并不过度做字符串处理即可拿到完整 URL。
• 清理子进程：Process 默认以独立进程组方式启动浏览器（构造时默认 detached: true，见 launch.ts），关闭时应对整个进程组做处理；使用完毕务必调用 browser.close()，避免残留孤儿浏览器进程。

小结

CDP_WEBSOCKET_ENDPOINT_REGEX 看似只是 launch.ts 中一行正则导出，但它背后是一套完整、可测试的"读输出 → 逐行匹配 → 提取调试端点"的启动协议，由 Process#recordStream 与 Process#waitForLineOutput（launch.ts）共同实现，并有真实 Chrome 启动测试（chrome/launch.test.ts）背书。掌握它与配套的 WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX，就掌握了在 @puppeteer/browsers 中程序化接管浏览器控制面的钥匙。