Puppeteer DEBUG_PREFIXES：六大调试通道前缀定义与协议级日志排查实战

Puppeteer DEBUG_PREFIXES六大调试通道前缀定义与协议级日志排查实战【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本文以 Puppeteer 公开 API 常量DEBUG_PREFIXES为研究对象它在 packages/puppeteer-core/src/common/Debug.ts 中定义了puppeteer:protocol:SEND ►、puppeteer:webDriverBiDi:RECV ◀等 6 个调试通道前缀是 Puppeteer 内部调试日志体系debug logging的通道注册表。读完本文你将掌握每个前缀对应的日志内容CDP 命令收发、WebDriver BiDi 命令收发、运行时错误、录屏 ffmpeg 输出、在 Node 与浏览器两种环境下如何按前缀开启日志以及如何通过connect()/launch()的logger选项接入自定义日志系统。一、DEBUG_PREFIXES 常量定义与完整签名官方 API 文档 docs/api/puppeteer.debug_prefixes.md 给出的完整签名如下与源码 Debug.ts 中的定义逐字一致DEBUG_PREFIXES: { readonly cdpSend: puppeteer:protocol:SEND ►; readonly cdpReceive: puppeteer:protocol:RECV ◀; readonly bidiSend: puppeteer:webDriverBiDi:SEND ►; readonly bidiReceive: puppeteer:webDriverBiDi:RECV ◀; readonly error: puppeteer:error; readonly ffmpeg: puppeteer:ffmpeg; }源码中的实际声明带有as const修饰并标注public experimental// packages/puppeteer-core/src/common/Debug.ts export const DEBUG_PREFIXES { cdpSend: puppeteer:protocol:SEND ►, cdpReceive: puppeteer:protocol:RECV ◀, bidiSend: puppeteer:webDriverBiDi:SEND ►, bidiReceive: puppeteer:webDriverBiDi:RECV ◀, error: puppeteer:error, ffmpeg: puppeteer:ffmpeg, } as const;由as const派生的DebugPrefix类型见 docs/api/puppeteer.debugprefix.md 及 Debug.ts#L29保证只有这 6 个字面量值可以用作调试通道前缀export type DebugPrefix (typeof DEBUG_PREFIXES)[keyof typeof DEBUG_PREFIXES];箭头符号►SEND与◀RECV是刻意设计的方向标识在终端翻查海量协议日志时可以凭方向符一眼区分Puppeteer 发往浏览器的命令与浏览器回传的响应/事件。二、六大调试通道的职责划分从源码中各前缀的实际调用点可以确认每个通道的语义边界1. cdpSend / cdpReceive —— CDP 协议命令收发在 cdp/Connection.ts 中Connection构造函数通过Logger工厂为收发两个方向各获取一个日志函数this.#debugProtocolSend logger?.(DEBUG_PREFIXES.cdpSend); this.#debugProtocolReceive logger?.(DEBUG_PREFIXES.cdpReceive);puppeteer:protocol:SEND ►Puppeteer 侧通过 CDPChrome DevTools Protocol向浏览器发出的每一条命令包括method、params与调用栈位置puppeteer:protocol:RECV ◀浏览器回传的响应与事件。这是排查某个 API 到底发了哪条 CDP 命令的第一手依据。2. bidiSend / bidiReceive —— WebDriver BiDi 协议命令收发在 bidi/Connection.ts 中BidiConnection采用完全对称的接法this.#debugProtocolSend logger?.(DEBUG_PREFIXES.bidiSend); this.#debugProtocolReceive logger?.(DEBUG_PREFIXES.bidiReceive);当使用protocol: webDriverBiDi模式驱动浏览器时命令流走的是 WebDriver BiDi 而非 CDP此时应观察puppeteer:webDriverBiDi:SEND ►/puppeteer:webDriverBiDi:RECV ◀两个通道。两条协议通道在命名上刻意区分protocolvswebDriverBiDi便于按前缀过滤避免两种协议的日志互相混杂。3. error —— 运行时内部错误puppeteer:error通道被大量核心类复用用于输出内部未捕获错误或协议回调失败信息。源码中可见的调用点包括cdp/Connection.ts连接层错误api/Page.ts、api/Browser.ts、api/BrowserContext.ts页面与浏览器上下文生命周期错误common/CallbackRegistry.tsCDP 命令回调被拒绝时输出原始错误common/BrowserWebSocketTransport.tsWebSocket 传输层错误。4. ffmpeg —— 录屏管线日志puppeteer:ffmpeg专属 node/ScreenRecorder.ts在Page.screencast()录屏流程中透传 ffmpeg 子进程的标准输出this.#logger?.(DEBUG_PREFIXES.ffmpeg)?.(data.toString(utf8));当录屏产出异常黑屏、格式错误时这条通道是定位 ffmpeg 参数的直接入口。三、开启日志的三种方式方式一Node 环境下的 NODE_DEBUG 环境变量Debug.ts 中的内部debug()函数在 Node 下直接委托给 Node 内置的util.debuglogif (isNode) { const nodeDebug environment.value.debuglog?.(prefix); if (!nodeDebug || !nodeDebug.enabled) { return; } return (...logArgs: unknown[]) { if (captureLogs) { capturedLogs.push(prefix logArgs); } (nodeDebug as LoggerFunction)(...logArgs); }; }因此遵循 NodeNODE_DEBUG的标准匹配规则前缀匹配、*通配# 只记录 CDP 双向协议 NODE_DEBUGpuppeteer:protocol* node app.js # 只记录错误通道 NODE_DEBUGpuppeteer:error node app.js # 记录所有 puppeteer 通道 NODE_DEBUGpuppeteer:* node app.js注意 Node 的debuglog按**段segment**匹配puppeteer:protocol*能覆盖SEND ►与RECV ◀两条通道。方式二浏览器环境下的 __PUPPETEER_DEBUG 全局变量同一debug()函数在浏览器分支Debug.ts#L119-L143读取globalThis.__PUPPETEER_DEBUG匹配逻辑为*记录全部foo*前缀匹配foo精确匹配window.__PUPPETEER_DEBUG puppeteer:protocol*; // 仅记录 CDP 协议 window.__PUPPETEER_DEBUG *; // 记录全部通道输出走console.log(${prefix}:, ...logArgs)。该变量在 Debug.ts#L9-L11 以declare global声明在浏览器端注入调试时无需引入额外依赖。方式三connect() 的 logger 选项程序化接入common/ConnectOptions.ts 中定义了实验性的logger选项其文档示例可直接复制const browser await puppeteer.connect({ browserWSEndpoint, logger: prefix { return (...args) console.log([${prefix}], ...args); }, });配套的Logger与LoggerFunction类型Debug.ts#L39-L65语义为工厂函数接收一个通道前缀返回该通道的日志函数返回undefined则表示该通道关闭日志。利用这一点可以精确订阅子集import {DEBUG_PREFIXES} from puppeteer-core; const browser await puppeteer.connect({ browserWSEndpoint, logger: prefix { if (prefix ! DEBUG_PREFIXES.error) { return undefined; // 除错误外全部静默 } return (...args) myTelemetry.report(puppeteer-error, args); }, });由于Logger是experimentalAPI官方提示未来版本可能调整签名生产接入时应做好兼容层。四、内部日志捕获机制setLogCapture 与测试断言源码还暴露了一个面向测试的内部能力Debug.ts#L149-L168let capturedLogs: string[] []; let captureLogs false; export function setLogCapture(value: boolean): void { capturedLogs []; captureLogs value; } export function getCapturedLogs(): string[] { return capturedLogs; }开启setLogCapture(true)后Node 分支的每条调试消息在输出前会追加进capturedLogs。从源码结构看这是 Puppeteer 自身集成测试用来断言某次调用应触发/不应触发特定错误日志的基础设施——例如 common/BrowserConnector.test.ts 等测试即为不同构造路径注入自定义logger进行验证。五、使用建议与限制协议通道日志量极大SEND ►/RECV ◀会记录每一条 CDP/BiDi 命令及其完整参数生产环境应保持关闭排查时建议叠加 API 调用点缩小时间窗口。方向前缀是过滤关键NODE_DEBUGpuppeteer:protocol*已足够覆盖双向协议若只想看错误用puppeteer:error即可。ffmpeg 通道仅在 Node 端录屏场景产生ScreenRecorder位于 node/ 目录浏览器端构建不会用到该通道。适用前提以上均基于当前仓库的puppeteer-core实现logger、DEBUG_PREFIXES均标注experimental升级大版本后建议重新核对前缀字面量是否变更。参考文件API 文档docs/api/puppeteer.debug_prefixes.md、docs/api/puppeteer.debugprefix.md核心实现packages/puppeteer-core/src/common/Debug.ts接入点cdp/Connection.ts、bidi/Connection.ts、node/ScreenRecorder.ts、common/ConnectOptions.ts【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考