Puppeteer调用page.screenshot时挂起超时，求解决方案

A) 可能导致截图挂起的情况 #

• 页面未进入稳定状态：页面存在持续加载的资源（如轮询接口、未完成的异步请求），或动态元素一直在更新，Puppeteer判定页面还未准备好执行截图
• 页面JS陷入无限循环：页面中的JavaScript代码出现死循环，阻塞浏览器主线程，无法响应截图指令
• 浏览器进程异常：Chrome实例后台卡死（比如内存过载），导致Puppeteer无法获取截图结果
• 页面渲染异常：存在超大尺寸元素、布局BUG等，导致截图渲染过程卡住
• 版本兼容性问题：Puppeteer与自带的Chrome版本不匹配，引发底层通信故障

B) 解决方法 #

1. 手动给截图添加超时机制 #

由于page.screenshot本身不支持timeout参数，可以用Promise.race实现手动超时：

async function withTimeout(promise, timeoutMs) {
  return Promise.race([
    promise,
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('截图超时')), timeoutMs)
    )
  ]);
}

// 使用示例
console.log(1);
try {
  // 设置10秒超时
  await withTimeout(page.screenshot({ path: 'screenshot.png' }), 10000);
  console.log(2);
} catch (err) {
  console.error('截图失败:', err.message);
}

2. 确保页面稳定后再截图 #

截图前等待页面加载完成或关键元素出现，避免页面处于动态状态：

// 等待网络空闲（500ms内没有新请求）
await page.waitForNavigation({ waitUntil: 'networkidle0' });
// 或者等待指定元素加载完成
await page.waitForSelector('#target-element', { timeout: 5000 });

3. 排查页面JS错误 #

监听页面控制台错误，排查是否有代码异常导致主线程阻塞：

const pageErrors = [];
page.on('console', msg => {
  if (msg.type() === 'error') {
    pageErrors.push(`[${msg.type()}] ${msg.text()}`);
  }
});

// 截图前打印页面错误
console.log('页面错误信息:', pageErrors);

4. 调整截图参数避免渲染问题 #

如果是页面尺寸过大导致的卡住，可以限制截图区域或关闭全页面截图：

await page.screenshot({
  path: 'screenshot.png',
  clip: { x: 0, y: 0, width: 1920, height: 1080 }, // 指定截取区域
  fullPage: false // 禁用全页面截图
});

5. 监控浏览器进程状态 #

定期检查Chrome进程是否存活，异常时及时处理：

const browser = await puppeteer.launch();

// 每5秒检查一次进程状态
setInterval(() => {
  if (!browser.process() || !browser.process().connected) {
    console.error('浏览器进程已断开连接');
    // 这里可添加重启浏览器的逻辑
  }
}, 5000);

内容的提问来源于stack exchange，提问作者machineghost