6. 调试技巧与日志分析 - Puppeteer 速读教程

调试 Puppeteer 脚本时，常常会陷入一种"黑盒"困境：代码在跑，浏览器在动，但具体发生了什么，只能凭想象猜测。页面为什么没加载出来？点击为什么没生效？数据为什么没抓到？这些问题像一团乱麻，让人无从下手。

好在 Puppeteer 提供了一套完整的调试工具链，从可视化界面到协议级日志，从慢动作回放到底层流量分析，让我们能够像剥洋葱一样，一层层揭开问题的真相。这一章，我们就把这些调试技巧系统地梳理一遍。

可视化调试无头浏览器

无头模式是 Puppeteer 的默认工作方式，它让浏览器在后台静默运行，不显示任何界面。这种模式在服务器环境下很高效，但在开发调试阶段，看不见浏览器窗口就等于失去了最重要的视觉反馈。所以，调试的第一步往往是：先把浏览器"请"出来，让它可见。

从"看不见"到"看得见"

最简单的可视化调试方法，就是在启动浏览器时关闭无头模式。只需要把 headless 选项设为 false，就能看到真实的浏览器窗口弹出，实时观察页面的加载和交互过程。

const browser = await puppeteer.launch({
  headless: false
});

这行代码会启动一个完整的 Chrome 浏览器，包括地址栏、标签页、开发者工具等所有界面元素。脚本执行时，可以亲眼看到页面如何跳转、元素如何被点击、数据如何被填充。很多显而易见的问题，比如选择器写错了、页面结构变了、网络请求失败了，在这种模式下会立刻暴露出来。

不过要注意，有界面模式会消耗更多系统资源，执行速度也会稍慢一些。所以这只适合开发和调试阶段，在生产环境还是建议使用无头模式。

新旧无头模式的差异

Puppeteer 在 v22 版本之后，默认使用 Chrome 的新无头模式（New Headless）。这个模式相比旧版无头模式（现在称为 chrome-headless-shell）更接近真实浏览器的行为，支持更多现代 Web API，但性能上略有损失。

如果调试时发现某些功能在无头模式下表现异常，可以尝试切换回旧版无头模式，看看问题是否依然存在。这有助于判断问题是出在浏览器内核还是 Puppeteer 本身。

// 使用旧版无头模式（性能更好，但功能有裁剪）
const browser = await puppeteer.launch({
  headless: 'shell'
});

旧版无头模式是一个独立的二进制文件，体积更小，启动更快，特别适合对性能敏感但不需要完整浏览器功能的场景。不过，由于它裁剪了一些功能，某些网站可能会检测到它是自动化工具，从而返回不同的内容。

自动打开开发者工具

有时候，仅仅看到浏览器界面还不够，还需要深入页面内部，查看 DOM 结构、网络请求、控制台输出等信息。这时可以让 Puppeteer 在启动时自动打开 Chrome 开发者工具。

const browser = await puppeteer.launch({
  headless: false,
  devtools: true
});

设置 devtools: true 后，每个新标签页都会自动打开开发者工具窗口。这相当于给每个页面都配备了一个实时监控面板，可以随时查看元素属性、调试 JavaScript、分析网络性能。

不过，开发者工具窗口会占用额外的屏幕空间，如果同时打开多个标签页，可能会让桌面变得拥挤。所以建议在调试特定页面时再启用这个选项。

慢动作模式与断点

浏览器窗口弹出来了，但脚本执行得太快，眼睛跟不上怎么办？这时候就需要慢动作模式和断点调试了。这两个技术一个让时间"减速"，一个让时间"暂停"，让我们能够从容地观察每一个细节。

慢动作模式：让自动化"减速"

Puppeteer 的 slowMo 选项可以让所有操作都延迟指定的毫秒数。这就像给脚本加上了一个"减速器"，让每个动作都变得清晰可见。

const browser = await puppeteer.launch({
  headless: false,
  slowMo: 250  // 每个操作延迟250毫秒
});

设置 slowMo: 250 后，无论是页面跳转、元素点击还是键盘输入，每个操作之间都会插入 250 毫秒的延迟。这样就有足够的时间观察页面变化，确认操作是否按预期执行。

这个参数的值可以根据需要调整。如果只是想稍微放慢速度，可以设为 100 毫秒；如果需要仔细研究某个复杂交互，可以设为 500 毫秒甚至更高。不过要注意，过大的延迟会让测试执行时间变得很长，所以建议在定位具体问题时再增大数值。

慢动作模式特别适合调试时序相关的问题。比如，页面元素是动态加载的，脚本可能在元素还没出现时就尝试点击，导致操作失败。通过慢动作回放，可以清楚地看到页面元素何时出现，脚本何时尝试操作，从而判断是否需要增加等待时间。

在浏览器端设置断点

慢动作模式虽然能让时间减速，但无法让时间暂停。如果想在特定位置暂停执行，检查页面状态，就需要使用断点。Puppeteer 支持在页面上下文中设置断点，就像在普通网页调试一样。

首先，启动浏览器时启用开发者工具：

const browser = await puppeteer.launch({
  devtools: true
});

然后，在 page.evaluate 中插入 debugger 语句：

await page.evaluate(() => {
  // 其他代码...
  debugger;  // 在这里暂停
  // 其他代码...
});

当脚本执行到 debugger 语句时，浏览器会自动暂停，开发者工具会切换到 Sources 面板，并高亮显示断点位置。此时可以查看变量值、调用栈、作用域链，也可以单步执行代码，观察每一步的变化。

这种方式特别适合调试在页面上下文中执行的复杂逻辑。比如，需要提取页面数据，但结果不符合预期，可以在数据处理的关键步骤设置断点，检查中间结果，找出问题所在。

需要注意的是，debugger 语句只在开发者工具打开时才会生效。如果开发者工具没有打开，浏览器会忽略这个语句，继续执行。所以记得先设置 devtools: true。

在 Node.js 端设置断点

浏览器端的代码可以断点调试，Node.js 端的代码当然也可以。Puppeteer 的 Node.js 端调试和普通的 Node.js 调试没有太大区别，只是多了一个浏览器窗口作为"可视化输出"。

首先，在脚本中添加 debugger 语句：

debugger;
await page.click('a[target=_blank]');

然后，使用 --inspect-brk 参数启动 Node.js 进程：

node --inspect-brk path/to/script.js

--inspect-brk 参数会让 Node.js 在启动后立即暂停，等待调试器连接。接着，在 Chrome 浏览器中打开 chrome://inspect/#devices 页面，会看到当前可调试的 Node.js 进程列表，点击对应的 "inspect" 链接，就能打开 DevTools for Node.js。

在 DevTools 中按 F8 继续执行，脚本会运行到第一个 debugger 语句处再次暂停。此时可以单步执行代码，观察变量变化，同时也能看到浏览器窗口中的实时变化。

这种调试方式非常强大，可以同时在 Node.js 端和浏览器端设置断点，观察数据如何在两个环境之间传递。比如，可以在 page.evaluate 前后设置断点，检查传入的参数和返回的值，确保数据序列化没有问题。

不过要注意，由于 Chromium 的一个 bug，在 DevTools 控制台中无法直接执行 await page.click() 这样的命令。如果想在控制台中测试某个 Puppeteer API，需要把代码写到脚本文件中再执行。

捕获页面 console 日志

页面中的 console.log、console.error 等输出默认不会显示在 Node.js 终端中，这给调试带来了很大不便。Puppeteer 提供了事件监听机制，可以捕获页面的所有控制台输出，转发到 Node.js 端。

监听 console 事件

通过监听页面的 console 事件，可以获取页面中所有的 console.* 调用：

page.on('console', msg => {
  console.log('PAGE LOG:', msg.text());
});

await page.evaluate(() => {
  console.log(`当前URL是 ${location.href}`);
  console.error('这是一个错误信息');
});

page.on('console', ...) 会注册一个事件处理器，每当页面中调用 console.* 方法时，这个处理器就会被触发。msg 参数是一个 ConsoleMessage 对象，包含了日志的文本内容、类型、位置等信息。

msg.text() 方法返回日志的文本内容，msg.type() 返回日志类型（如 log、error、warning 等），msg.location() 返回日志在页面中的位置（文件名、行号、列号）。

这种方式特别适合调试页面中的 JavaScript 代码。比如，在 page.evaluate 中执行了一段复杂的数据处理逻辑，可以在关键位置插入 console.log，通过事件监听查看输出结果，就像在前端开发中调试一样自然。

处理不同类型的日志输出

除了普通的日志，页面中还可能输出警告、错误、调试信息等。可以根据日志类型做不同的处理：

page.on('console', msg => {
  const type = msg.type();
  const text = msg.text();
  
  if (type === 'error') {
    console.error('页面错误:', text);
  } else if (type === 'warning') {
    console.warn('页面警告:', text);
  } else {
    console.log('页面日志:', text);
  }
});

这样可以把页面的错误信息用红色显示，警告信息用黄色显示，普通日志用默认颜色显示，让终端输出更清晰易读。

另外，页面中的 console.log 可以接收多个参数，比如 console.log('data:', obj)。msg.text() 会把所有参数拼接成一个字符串。如果需要获取原始参数，可以使用 msg.args()，它返回一个 JSHandle 数组，代表每个参数的句柄，可以通过 page.evaluate 进一步处理。

捕获页面日志不仅能帮助调试自己的代码，还能发现页面本身的问题。比如，有些网站会在控制台输出错误信息，这些信息可能反映了页面的兼容性问题或功能缺陷，对爬虫开发很有参考价值。

DevTools 协议流量分析

如果前面的方法都无法定位问题，那就需要深入最底层，查看 Puppeteer 和浏览器之间的通信细节。Puppeteer 通过 DevTools 协议控制浏览器，所有操作最终都会转化为协议命令。通过分析协议流量，可以精确地看到 Puppeteer 发送了什么命令，浏览器返回了什么结果。

开启协议流量日志

Puppeteer 使用 debug 模块输出内部日志，可以通过设置 DEBUG 环境变量来开启：

# 开启所有 Puppeteer 日志
env DEBUG="puppeteer:*" node script.js

执行后，终端会输出大量的协议通信细节，包括发送的命令、接收的事件、参数、返回值等。这些信息非常详细，可以帮助理解 Puppeteer 的内部工作原理。

协议日志可能会很长，默认情况下，长消息会被截断。如果想查看完整内容，可以设置 DEBUG_MAX_STRING_LENGTH：

# 不截断长消息
env DEBUG="puppeteer:*" env DEBUG_MAX_STRING_LENGTH=null node script.js

这样就能看到完整的协议消息，不会被 ... 省略号截断。

过滤和解读协议消息

协议流量日志非常详细，但也因此非常嘈杂。如果只想关注特定类型的消息，可以使用 grep 过滤：

# 过滤掉所有 Network 域的消息（通常很多）
env DEBUG="puppeteer:*" node script.js 2>&1 | grep -v '"Network'

# 只保留包含特定关键词的消息
env DEBUG="puppeteer:*" node script.js 2>&1 | grep 'Page.navigate'

2>&1 是把标准错误重定向到标准输出，因为 debug 模块默认输出到标准错误。

如果想过滤掉所有协议消息，只保留其他日志，可以使用负向匹配：

# 过滤掉协议消息，保留其他日志
env DEBUG="puppeteer:*,-puppeteer:protocol:*" node script.js

-puppeteer:protocol:* 表示排除所有协议相关的日志，这样就能看到更简洁的输出，专注于高层逻辑。

解读协议消息需要一些背景知识。每条消息通常包含 method（方法名）、params（参数）、id（请求ID）等字段。比如，Page.navigate 消息表示导航到某个 URL，DOM.querySelector 表示查询 DOM 元素。通过分析这些消息，可以精确地追踪 Puppeteer 的每一步操作。

排查异步调用问题

有时候会遇到这样的情况：某个 Puppeteer API 调用后，Promise 一直不 resolve，脚本卡住了。这可能是由于浏览器没有返回响应，或者协议层出现了异常。这时可以查看待处理的协议调用，找出卡住的原因。

Puppeteer 的 Browser 对象提供了一个 debugInfo 属性，可以获取当前待处理的协议错误：

console.log(browser.debugInfo.pendingProtocolErrors);

这个属性返回一个错误对象数组，每个对象包含堆栈跟踪，指示哪个代码触发了协议调用。通过分析这些错误，可以定位到具体的 API 调用，进而排查问题。

比如，如果 page.click() 卡住了，查看 pendingProtocolErrors 可能会发现浏览器没有响应点击命令，或者返回了错误状态。这可能是由于页面结构变化、元素被遮挡、浏览器崩溃等原因造成的。

协议流量分析是最后的手段，通常只在其他方法都无效时才使用。但它也是最强大的工具，能够揭示 Puppeteer 和浏览器交互的所有细节，帮助解决最棘手的问题。

浏览器进程日志

除了协议流量，浏览器进程本身的输出也可能包含重要信息。如果浏览器启动失败、意外崩溃或行为异常，查看浏览器进程的 stdout 和 stderr 可能会找到线索。

捕获浏览器进程输出

启动浏览器时设置 dumpio: true，可以把浏览器进程的输出转发到 Node.js 进程的标准输出：

const browser = await puppeteer.launch({
  dumpio: true
});

这样，浏览器的日志会直接显示在终端中。这些日志包括 Chromium 的启动信息、渲染进程的状态、GPU 加速情况、沙箱配置等。如果浏览器启动失败，这里通常会显示错误原因，比如缺少依赖库、权限不足、端口被占用等。

在 Linux 服务器上运行 Puppeteer 时，经常会遇到沙箱相关的问题。浏览器日志中可能会显示 [ERROR:browser_main_loop.cc(...)] 或 [FATAL:zygote_host_impl_linux.cc(...)] 这样的错误，提示需要配置系统或禁用沙箱。这些信息对排查部署问题非常有帮助。

不过要注意，dumpio: true 会让终端输出变得非常嘈杂，因为浏览器进程会输出大量信息。所以建议在遇到浏览器启动或崩溃问题时再启用这个选项，平时保持关闭。

总结

调试 Puppeteer 脚本是一个多层次的过程，从可视化界面到慢动作回放，从日志捕获到协议分析，每种方法都有其适用场景。开发阶段，优先使用 headless: false 和 slowMo 快速定位问题；调试页面逻辑时，用 console 事件和 debugger 语句深入分析；遇到疑难杂症时，再用协议流量日志和浏览器进程输出挖掘根本原因。

掌握这些调试技巧，就像给 Puppeteer 开发配备了一套完整的工具箱。无论是简单的脚本错误，还是复杂的时序问题，都能找到对应的工具来解决。调试能力的高低，往往决定了开发效率的上限。

下一章，我们将探讨 Cookie、存储与状态管理，看看如何在自动化过程中保持登录状态、管理用户数据，以及控制浏览器权限。这些知识对构建健壮的自动化流程至关重要。