Puppeteer 调试日志体系DebugPrefix 通道前缀与 Logger 机制深度解析【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer在 Puppeteer 中DebugPrefix是调试日志体系的类型骨架它将 CDP 协议收发、WebDriver BiDi 收发、内部错误、FFmpeg 输出等不同事件划分到相互独立的“调试通道”中每个通道对应一个固定的字符串前缀。读完本文你将理解DebugPrefix类型与DEBUG_PREFIXES常量的完整定义、六个调试通道各自在源码中的接入位置以及如何通过launch/connect的logger选项或环境变量控制日志输出从而对浏览器自动化过程中的协议交互进行精准排查。DebugPrefix 类型定义DebugPrefix本身是一个由常量对象推导出的字面量联合类型其完整签名如下见 API 文档 与 类型定义源码// 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; export type DebugPrefix (typeof DEBUG_PREFIXES)[keyof typeof DEBUG_PREFIXES];也就是说DebugPrefix等价于以下六个字符串字面量之一的联合type DebugPrefix | puppeteer:protocol:SEND ► | puppeteer:protocol:RECV ◀ | puppeteer:webDriverBiDi:SEND ► | puppeteer:webDriverBiDi:RECV ◀ | puppeteer:error | puppeteer:ffmpeg;as const声明配合索引访问类型保证了新增通道时 TypeScript 会自动将新前缀纳入联合类型——类型与运行时常量不会失配。该类型与DEBUG_PREFIXES均标注为public experimental意味着 API 在未来版本中可能调整。六个调试通道前缀值与源码接入位置DEBUG_PREFIXES中的六个键值对就是 Puppeteer 内建的全部调试通道。下表列出每个通道的键、前缀值以及在puppeteer-core源码中的实际使用位置通道键前缀值用途源码接入位置cdpSendpuppeteer:protocol:SEND ►CDP 命令发送日志cdp/Connection.tscdpReceivepuppeteer:protocol:RECV ◀CDP 事件/响应接收日志cdp/Connection.tsbidiSendpuppeteer:webDriverBiDi:SEND ►WebDriver BiDi 命令发送日志bidi/Connection.tsbidiReceivepuppeteer:webDriverBiDi:RECV ◀WebDriver BiDi 事件/响应接收日志bidi/Connection.tserrorpuppeteer:error内部被捕获的错误日志Browser.ts、Page.ts、locators.ts 等多处ffmpegpuppeteer:ffmpeg屏幕录制FFmpeg子进程输出ScreenRecorder.ts从源码结构看两个协议通道的接入方式完全一致连接类在构造时调用logger工厂获取对应通道专用函数并缓存之后在每条消息的收发路径上调用。以 CDP 连接为例cdp/Connection.tsthis.#debugProtocolSend logger?.(DEBUG_PREFIXES.cdpSend); this.#debugProtocolReceive logger?.(DEBUG_PREFIXES.cdpReceive);BiDi 连接bidi/Connection.ts同样缓存bidiSend/bidiReceive两个通道函数。error通道则被广泛散布在 API 层如Browser、BrowserContext、Page、JSHandle、HTTPRequest以及 Locator 内部用于记录那些被吞掉但值得排查的异步错误。ffmpeg通道则专门承载screencast()录制时 FFmpeg 进程的 stderr 输出。通道如何被使用Logger 与 LoggerFunction 两个函数类型DebugPrefix的前缀值通过两个函数类型流入日志系统定义于 Debug.tsLoggerFunction(…args: unknown[]) void向单个通道输出日志的具体函数Logger(prefix: string) LoggerFunction | undefined通道工厂。传入一个通道前缀若该通道启用则返回对应的LoggerFunction返回undefined即表示该通道日志被关闭。这种“工厂 每通道函数”的设计有两个好处调用方只需一次logger(prefix)判断即可知道通道是否启用未启用时函数为undefined配合可选链?.零成本短路同时日志框架的选择权完全交给用户。Logger通过launch/connect的logger选项传入。该选项定义在 ConnectOptions.ts 中/** * When provided, Puppeteer calls the logger with a debug channel prefix * {link DebugPrefix}. If the logger returns a * {link LoggerFunction}, Puppeteer uses it to log details for that channel. * * example * ts * const browser await puppeteer.connect({ * browserWSEndpoint, * logger: prefix { * return (...args) console.log([${prefix}], ...args); * }, * }); * * * experimental The API may change in future releases. */ logger?: Logger;上面的示例中connect传入的logger会对所有到达的DebugPrefix通道返回一个console.log包装函数因此 CDP 与 BiDi 的全部协议收发、内部错误、录制输出都会带上各自的方括号前缀打印出来。puppeteer-core导出的Logger类型同样适用于launch可以只放行部分通道import puppeteer from puppeteer; const browser await puppeteer.launch({ logger: prefix { // 只关注 CDP 协议通道其余通道返回 undefined 即关闭 if (prefix.includes(protocol)) { return (...args: unknown[]) console.log([DEBUG: ${prefix}], ...args); } return undefined; }, });这段过滤写法直接取自 Logger 类型的 TSDoc 示例展示了按前缀内容选择性开启通道的标准做法。内建 debug() 实现Node 与浏览器双环境适配puppeteer-core内部自带一个跨环境的debug函数Debug.ts标注为internal其行为因运行环境而异Node 环境回退到 Node 内建的util.debuglog。debug(prefix)会先查询该前缀对应的通道是否启用未启用直接返回undefined启用时返回的函数会在记录日志的同时支持内部的日志捕获供测试断言使用见下文。此时通过环境变量控制通道NODE_DEBUG* # 记录所有通道 NODE_DEBUGfoo # 只记录 foo 通道 NODE_DEBUGfoo* # 记录所有以 foo 开头的通道浏览器环境读取全局变量window.__PUPPETEER_DEBUG源码中声明为globalThis.__PUPPETEER_DEBUG见 Debug.ts未设置则所有通道关闭。匹配规则与 Node 保持一致window.__PUPPETEER_DEBUG *; // 记录所有通道 window.__PUPPETEER_DEBUG foo; // 只记录 foo 通道 window.__PUPPETEER_DEBUG foo*; // 前缀匹配 foo 开头的通道其匹配逻辑值得注意结尾带*时按前缀匹配prefix.startsWith(debugLevel.slice(0, -1))否则要求完全相等。匹配成功的通道debug()返回一个console.log(${prefix}:, ...logArgs)包装函数输出形如puppeteer:protocol:SEND ► ...。此外源码还暴露了setLogCapture/getCapturedLogs两个内部辅助函数Debug.ts用于在测试中断言“某条调试日志确实被触发”这也侧面印证了各通道在内部逻辑中的真实调用路径。实战查看 CDP / BiDi 协议交互调试 Puppeteer 时最有价值的场景就是观察“Puppeteer 到底向浏览器发了什么、收到了什么”。两种接入方式对比如下方式一NODE_DEBUG环境变量零代码改动由于内建debug函数在 Node 下直接使用util.debuglog而前缀是带特殊字符的完整字符串实际过滤时需要用完整前缀或其开头片段做匹配。最简做法是全量开启NODE_DEBUG* node script.js输出中即可看到形如puppeteer:protocol:SEND ►的 CDP 消息流。注意该方式只覆盖 Puppeteer 内建debug()的通道若你希望通过logger选项注入自定义日志例如同时写文件仍应使用方式二。方式二logger选项可编程、可按通道过滤import puppeteer from puppeteer; const browser await puppeteer.launch({ logger: prefix { switch (prefix) { case puppeteer:protocol:SEND ►: return (...args) console.log([CDP OUT], ...args); case puppeteer:protocol:RECV ◀: return (...args) console.log([CDP IN], ...args); case puppeteer:error: return (...args) console.error([ERROR], ...args); default: return undefined; // 关闭其余通道 } }, });在puppeteer-core中logger还可以配合connect使用ConnectOptions 示例用于排查连接远端浏览器时的协议层问题若使用 WebDriver BiDi 协议则对应放行puppeteer:webDriverBiDi:SEND ►/RECV ◀两个通道。补充browsers 包有自己的一组调试前缀需要区分的是puppeteer/browsers负责浏览器下载、安装、缓存管理维护了独立的一套前缀常量browsers/src/debug.tsexport const DEBUG_PREFIXES { cache: puppeteer:browsers:cache, fileUtil: puppeteer:browsers:fileUtil, install: puppeteer:browsers:install, launcher: puppeteer:browsers:launcher, } as const;这些前缀同样走util.debuglog可在执行浏览器安装/启动时通过NODE_DEBUGpuppeteer:browsers:*之类的模式开启排查下载与缓存问题。它们与本文聚焦的puppeteer-core的DebugPrefix是两套并列体系不要混用——DebugPrefix类型只涵盖协议、错误与录制六通道。小结DebugPrefix是从DEBUG_PREFIXES推导的字面量联合类型代表 Puppeteer 内建调试通道的全部前缀值类型定义六个通道分工明确CDP 收发、BiDi 收发、内部错误、FFmpeg 录制各自在 cdp/Connection.ts、bidi/Connection.ts、ScreenRecorder.ts 及 API 层被接入通过launch/connect的logger选项Logger工厂 LoggerFunction输出函数可按通道精细控制日志的去向与开关不写代码时Node 环境用NODE_DEBUG、浏览器环境用window.__PUPPETEER_DEBUG也可开启内建通道的console.log输出该 API 标注为experimental使用前请以当前仓库 Debug.ts 的实际定义为准。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puppeteer 调试日志体系DebugPrefix 通道前缀与 Logger 机制深度解析【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer在 Puppeteer 中DebugPrefix是调试日志体系的类型骨架它将 CDP 协议收发、WebDriver BiDi 收发、内部错误、FFmpeg 输出等不同事件划分到相互独立的“调试通道”中每个通道对应一个固定的字符串前缀。读完本文你将理解DebugPrefix类型与DEBUG_PREFIXES常量的完整定义、六个调试通道各自在源码中的接入位置以及如何通过launch/connect的logger选项或环境变量控制日志输出从而对浏览器自动化过程中的协议交互进行精准排查。DebugPrefix 类型定义DebugPrefix本身是一个由常量对象推导出的字面量联合类型其完整签名如下见 API 文档 与 类型定义源码// 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; export type DebugPrefix (typeof DEBUG_PREFIXES)[keyof typeof DEBUG_PREFIXES];也就是说DebugPrefix等价于以下六个字符串字面量之一的联合type DebugPrefix | puppeteer:protocol:SEND ► | puppeteer:protocol:RECV ◀ | puppeteer:webDriverBiDi:SEND ► | puppeteer:webDriverBiDi:RECV ◀ | puppeteer:error | puppeteer:ffmpeg;as const声明配合索引访问类型保证了新增通道时 TypeScript 会自动将新前缀纳入联合类型——类型与运行时常量不会失配。该类型与DEBUG_PREFIXES均标注为public experimental意味着 API 在未来版本中可能调整。六个调试通道前缀值与源码接入位置DEBUG_PREFIXES中的六个键值对就是 Puppeteer 内建的全部调试通道。下表列出每个通道的键、前缀值以及在puppeteer-core源码中的实际使用位置通道键前缀值用途源码接入位置cdpSendpuppeteer:protocol:SEND ►CDP 命令发送日志cdp/Connection.tscdpReceivepuppeteer:protocol:RECV ◀CDP 事件/响应接收日志cdp/Connection.tsbidiSendpuppeteer:webDriverBiDi:SEND ►WebDriver BiDi 命令发送日志bidi/Connection.tsbidiReceivepuppeteer:webDriverBiDi:RECV ◀WebDriver BiDi 事件/响应接收日志bidi/Connection.tserrorpuppeteer:error内部被捕获的错误日志Browser.ts、Page.ts、locators.ts 等多处ffmpegpuppeteer:ffmpeg屏幕录制FFmpeg子进程输出ScreenRecorder.ts从源码结构看两个协议通道的接入方式完全一致连接类在构造时调用logger工厂获取对应通道专用函数并缓存之后在每条消息的收发路径上调用。以 CDP 连接为例cdp/Connection.tsthis.#debugProtocolSend logger?.(DEBUG_PREFIXES.cdpSend); this.#debugProtocolReceive logger?.(DEBUG_PREFIXES.cdpReceive);BiDi 连接bidi/Connection.ts同样缓存bidiSend/bidiReceive两个通道函数。error通道则被广泛散布在 API 层如Browser、BrowserContext、Page、JSHandle、HTTPRequest以及 Locator 内部用于记录那些被吞掉但值得排查的异步错误。ffmpeg通道则专门承载screencast()录制时 FFmpeg 进程的 stderr 输出。通道如何被使用Logger 与 LoggerFunction 两个函数类型DebugPrefix的前缀值通过两个函数类型流入日志系统定义于 Debug.tsLoggerFunction(…args: unknown[]) void向单个通道输出日志的具体函数Logger(prefix: string) LoggerFunction | undefined通道工厂。传入一个通道前缀若该通道启用则返回对应的LoggerFunction返回undefined即表示该通道日志被关闭。这种“工厂 每通道函数”的设计有两个好处调用方只需一次logger(prefix)判断即可知道通道是否启用未启用时函数为undefined配合可选链?.零成本短路同时日志框架的选择权完全交给用户。Logger通过launch/connect的logger选项传入。该选项定义在 ConnectOptions.ts 中/** * When provided, Puppeteer calls the logger with a debug channel prefix * {link DebugPrefix}. If the logger returns a * {link LoggerFunction}, Puppeteer uses it to log details for that channel. * * example * ts * const browser await puppeteer.connect({ * browserWSEndpoint, * logger: prefix { * return (...args) console.log([${prefix}], ...args); * }, * }); * * * experimental The API may change in future releases. */ logger?: Logger;上面的示例中connect传入的logger会对所有到达的DebugPrefix通道返回一个console.log包装函数因此 CDP 与 BiDi 的全部协议收发、内部错误、录制输出都会带上各自的方括号前缀打印出来。puppeteer-core导出的Logger类型同样适用于launch可以只放行部分通道import puppeteer from puppeteer; const browser await puppeteer.launch({ logger: prefix { // 只关注 CDP 协议通道其余通道返回 undefined 即关闭 if (prefix.includes(protocol)) { return (...args: unknown[]) console.log([DEBUG: ${prefix}], ...args); } return undefined; }, });这段过滤写法直接取自 Logger 类型的 TSDoc 示例展示了按前缀内容选择性开启通道的标准做法。内建 debug() 实现Node 与浏览器双环境适配puppeteer-core内部自带一个跨环境的debug函数Debug.ts标注为internal其行为因运行环境而异Node 环境回退到 Node 内建的util.debuglog。debug(prefix)会先查询该前缀对应的通道是否启用未启用直接返回undefined启用时返回的函数会在记录日志的同时支持内部的日志捕获供测试断言使用见下文。此时通过环境变量控制通道NODE_DEBUG* # 记录所有通道 NODE_DEBUGfoo # 只记录 foo 通道 NODE_DEBUGfoo* # 记录所有以 foo 开头的通道浏览器环境读取全局变量window.__PUPPETEER_DEBUG源码中声明为globalThis.__PUPPETEER_DEBUG见 Debug.ts未设置则所有通道关闭。匹配规则与 Node 保持一致window.__PUPPETEER_DEBUG *; // 记录所有通道 window.__PUPPETEER_DEBUG foo; // 只记录 foo 通道 window.__PUPPETEER_DEBUG foo*; // 前缀匹配 foo 开头的通道其匹配逻辑值得注意结尾带*时按前缀匹配prefix.startsWith(debugLevel.slice(0, -1))否则要求完全相等。匹配成功的通道debug()返回一个console.log(${prefix}:, ...logArgs)包装函数输出形如puppeteer:protocol:SEND ► ...。此外源码还暴露了setLogCapture/getCapturedLogs两个内部辅助函数Debug.ts用于在测试中断言“某条调试日志确实被触发”这也侧面印证了各通道在内部逻辑中的真实调用路径。实战查看 CDP / BiDi 协议交互调试 Puppeteer 时最有价值的场景就是观察“Puppeteer 到底向浏览器发了什么、收到了什么”。两种接入方式对比如下方式一NODE_DEBUG环境变量零代码改动由于内建debug函数在 Node 下直接使用util.debuglog而前缀是带特殊字符的完整字符串实际过滤时需要用完整前缀或其开头片段做匹配。最简做法是全量开启NODE_DEBUG* node script.js输出中即可看到形如puppeteer:protocol:SEND ►的 CDP 消息流。注意该方式只覆盖 Puppeteer 内建debug()的通道若你希望通过logger选项注入自定义日志例如同时写文件仍应使用方式二。方式二logger选项可编程、可按通道过滤import puppeteer from puppeteer; const browser await puppeteer.launch({ logger: prefix { switch (prefix) { case puppeteer:protocol:SEND ►: return (...args) console.log([CDP OUT], ...args); case puppeteer:protocol:RECV ◀: return (...args) console.log([CDP IN], ...args); case puppeteer:error: return (...args) console.error([ERROR], ...args); default: return undefined; // 关闭其余通道 } }, });在puppeteer-core中logger还可以配合connect使用ConnectOptions 示例用于排查连接远端浏览器时的协议层问题若使用 WebDriver BiDi 协议则对应放行puppeteer:webDriverBiDi:SEND ►/RECV ◀两个通道。补充browsers 包有自己的一组调试前缀需要区分的是puppeteer/browsers负责浏览器下载、安装、缓存管理维护了独立的一套前缀常量browsers/src/debug.tsexport const DEBUG_PREFIXES { cache: puppeteer:browsers:cache, fileUtil: puppeteer:browsers:fileUtil, install: puppeteer:browsers:install, launcher: puppeteer:browsers:launcher, } as const;这些前缀同样走util.debuglog可在执行浏览器安装/启动时通过NODE_DEBUGpuppeteer:browsers:*之类的模式开启排查下载与缓存问题。它们与本文聚焦的puppeteer-core的DebugPrefix是两套并列体系不要混用——DebugPrefix类型只涵盖协议、错误与录制六通道。小结DebugPrefix是从DEBUG_PREFIXES推导的字面量联合类型代表 Puppeteer 内建调试通道的全部前缀值类型定义六个通道分工明确CDP 收发、BiDi 收发、内部错误、FFmpeg 录制各自在 cdp/Connection.ts、bidi/Connection.ts、ScreenRecorder.ts 及 API 层被接入通过launch/connect的logger选项Logger工厂 LoggerFunction输出函数可按通道精细控制日志的去向与开关不写代码时Node 环境用NODE_DEBUG、浏览器环境用window.__PUPPETEER_DEBUG也可开启内建通道的console.log输出该 API 标注为experimental使用前请以当前仓库 Debug.ts 的实际定义为准。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
