Puppeteer 如何进行错误处理和调试？

Puppeteer 在浏览器自动化场景下，错误类型多、调试链路长，从脚本层到浏览器层再到网络层都可能出问题。掌握系统的错误处理策略和调试手段，是写出可靠自动化脚本的关键。

Puppeteer 常见的错误类型有哪些？

Puppeteer 脚本运行时主要会遇到三类错误：

脚本层错误——语法错误、逻辑错误，这类错误 Node.js 会直接抛出栈信息，属于常规调试范畴。

协议层错误——Puppeteer 通过 CDP（Chrome DevTools Protocol）与浏览器通信，协议调用失败时会抛出特定错误类：

javascript
const { TimeoutError } = require('puppeteer').errors;

try {
  await page.waitForSelector('.dynamic-content', { timeout: 5000 });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.error('等待元素超时，可能页面未加载完成');
  }
}

浏览器层错误——页面内的 JS 运行时错误、资源加载失败、网络请求异常，需要通过事件监听捕获：

javascript
// 捕获页面未处理的 JS 错误
page.on('pageerror', error => {
  console.error('[页面错误]', error.message);
});

// 捕获资源加载失败
page.on('requestfailed', request => {
  console.error('[请求失败]', request.url(), request.failure().errorText);
});

怎样构建健壮的错误处理机制？

try-catch 配合 finally 管理生命周期

每个 Puppeteer 脚本都应确保浏览器实例被正确关闭，finally 块是关键：

javascript
async function runTask() {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  try {
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
    await page.click('#submit');
  } catch (error) {
    // 区分超时和其他错误
    if (error.name === 'TimeoutError') {
      console.error('操作超时:', error.message);
    } else {
      console.error('执行失败:', error.message);
    }
    // 出错时截图保存现场
    await page.screenshot({ path: `error-${Date.now()}.png`, fullPage: true });
  } finally {
    await browser.close();
  }
}

重试策略处理临时性故障

网络波动、页面加载慢等临时性问题，适合用重试机制解决：

javascript
async function withRetry(fn, maxRetries = 3, delay = 2000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      console.warn(`第 ${i + 1} 次尝试失败: ${error.message}`);
      if (i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, delay * (i + 1)));
      } else {
        throw error;
      }
    }
  }
}

// 使用：自动重试页面导航
const page = await withRetry(() => browser.newPage().then(p => p.goto(url).then(() => p)));

全局错误事件监听

在 page 级别设置错误监听，防止未捕获的异常导致脚本静默崩溃：

javascript
page.on('error', err => {
  console.error('[Page crash]', err.message);
});

page.on('console', msg => {
  if (msg.type() === 'error') {
    console.error('[Console Error]', msg.text());
  }
});

有哪些实用的调试手段？

headless: false + slowMo 可视化调试

最直接的方式是关掉无头模式，肉眼观察浏览器行为：

javascript
const browser = await puppeteer.launch({
  headless: false,
  slowMo: 100,   // 每步操作放慢 100ms
  devtools: true  // 自动打开 DevTools
});

slowMo 的值根据脚本复杂度调整，一般 50-250ms 之间。值太大会导致超时，太小来不及观察。

DEBUG 环境变量追踪协议通信

Puppeteer 内部基于 CDP 协议通信，通过 DEBUG 环境变量可以看到所有协议交互：

bash
# 查看所有 Puppeteer 内部通信
DEBUG="puppeteer:*" node script.js

# 只看 CDP 协议请求
DEBUG="puppeteer:protocol" node script.js

# 只看 API 调用
DEBUG="puppeteer:api" node script.js

这在排查"为什么操作没生效"时非常有效，能看到 Puppeteer 到底发送了什么指令、浏览器返回了什么。

截图和 HTML 快照保留现场

在关键步骤截图，配合 HTML 快照，可以还原出错时的完整页面状态：

javascript
async function debugCheckpoint(page, name) {
  const ts = new Date().toISOString().replace(/[:.]/g, '-');
  await page.screenshot({ path: `debug-${name}-${ts}.png`, fullPage: true });
  const html = await page.content();
  require('fs').writeFileSync(`debug-${name}-${ts}.html`, html);
  console.log(`[调试快照] ${name} 已保存`);
}

// 在关键步骤之间插入
await debugCheckpoint(page, 'after-login');
await page.click('#next-step');
await debugCheckpoint(page, 'after-click');

网络请求拦截与监控

拦截和记录网络请求，能定位接口异常、资源加载失败等问题：

javascript
// 监控所有请求的状态
page.on('response', response => {
  if (response.status() >= 400) {
    console.warn(`[HTTP ${response.status()}] ${response.url()}`);
  }
});

// 拦截并修改请求（模拟接口异常场景）
await page.setRequestInterception(true);
page.on('request', request => {
  if (request.url().includes('/api/user')) {
    // 模拟接口 500 错误
    request.abort();
  } else {
    request.continue();
  }
});

如何用 CDP Session 做高级调试？

Puppeteer 提供的 API 覆盖了大部分场景，但有些高级调试功能需要直接使用 CDP Session：

javascript
// 创建 CDP 会话
const client = await page.target().createCDPSession();

// 性能指标采集
await client.send('Performance.enable');
const { metrics } = await client.send('Performance.getMetrics');
console.log('性能指标:', metrics.filter(m => m.name === 'FirstMeaningfulPaint'));

// 追踪页面加载时间线
await page.tracing.start({ path: 'trace.json' });
await page.goto('https://example.com');
await page.tracing.stop();
// trace.json 可在 Chrome DevTools → Performance 面板中打开分析

// 模拟网络条件（测试弱网场景）
await client.send('Network.emulateNetworkConditions', {
  offline: false,
  latency: 200,     // 额外延迟 200ms
  downloadThroughput: 500 * 1024,  // 下载 500KB/s
  uploadThroughput: 250 * 1024,    // 上传 250KB/s
});

面试高频追问：常见踩坑与解决方案

导航超时怎么处理？ 默认超时 30 秒，可以用 waitUntil 参数降低等待条件，或针对性增加超时时间：

javascript
// 方案1：降低等待条件
await page.goto(url, { waitUntil: 'domcontentloaded' });

// 方案2：单独设置超时
await page.goto(url, { timeout: 60000, waitUntil: 'networkidle2' });

// 方案3：手动等待关键元素
await page.goto(url, { waitUntil: 'domcontentloaded' });
await page.waitForSelector('.main-content');

元素找不到或不可点击怎么办？ 大部分情况是元素还没渲染完成或被遮挡，按以下顺序排查：

javascript
// 1. 确认元素存在
const element = await page.$(selector);
if (!element) throw new Error(`元素不存在: ${selector}`);

// 2. 确认元素可见
const visible = await element.isIntersectingViewport();
if (!visible) {
  await element.scrollIntoView();
}

// 3. 等待元素可交互
await page.waitForSelector(selector, { visible: true });
await element.click();

内存泄漏怎么排查？ Puppeteer 脚本中最常见的泄漏是浏览器实例未关闭和事件监听器未移除：

javascript
// 始终用 finally 保证关闭
let browser;
try {
  browser = await puppeteer.launch();
  const page = await browser.newPage();
  // ... 操作
} finally {
  if (browser) await browser.close();
}

// 长时间运行的脚本，用完后移除监听
const handler = msg => console.log(msg.text());
page.on('console', handler);
// 用完后
page.off('console', handler);

如何调试 headless 模式下的脚本？ headless 环境无法可视化，靠截图和日志定位：

javascript
// 开启详细日志
process.env.DEBUG = 'puppeteer:*';

// 在出错时自动保存完整上下文
page.on('pageerror', async error => {
  const debugInfo = {
    url: page.url(),
    error: error.message,
    html: await page.content().catch(() => '获取失败'),
    screenshot: await page.screenshot({ encoding: 'base64' }).catch(() => null)
  };
  require('fs').writeFileSync('crash-debug.json', JSON.stringify(debugInfo, null, 2));
});

掌握以上错误处理和调试方法，可以在实际项目中快速定位 Puppeteer 脚本问题，写出更稳定的自动化流程。