Puppeteer 实现 HTML 转图片报错：Navigation timeout 问题排查记录

2026-09-10 194 浏览 0 评论 0 字

作为一名后端开发者，近期在项目中使用 Puppeteer 实现 HTML 转图片功能时，遇到了一个棘手的超时错误，花费了一些时间排查和梳理，特此记录整个问题场景和排查过程，希望能给遇到同类问题的同行提供一些参考（本文仅记录问题本身及排查细节，不提供具体解决方案）。

项目背景是，我负责的博客系统中，有一个需求是将用户编辑的 HTML 内容转为图片展示，核心使用 Puppeteer 库来实现无头浏览器渲染，封装在 helper.js 文件的 html2Image 方法中，对外提供 /api/v1/runcode 接口供前端调用。

某天测试环境突然反馈接口调用失败，查看后台日志时，发现了明确的报错信息，完整报错如下：

ERROR 25035 [-/undefined/-/30888ms POST /api/v1/runcode] nodejs.TimeoutError: Navigation timeout of 30000 ms exceeded
    at LifecycleWatcher._LifecycleWatcher_createTimeoutPromise (/www/myblog/myblog/node_modules/puppeteer-core/lib/cjs/puppeteer/common/LifecycleWatcher.js:162:12)
    at async IsolatedWorld.setContent (/www/myblog/myblog/node_modules/puppeteer-core/lib/cjs/puppeteer/common/IsolatedWorld.js:173:23)
    at async CDPPage.setContent (/www/myblog/myblog/node_modules/puppeteer-core/lib/cjs/puppeteer/common/Page.js:435:9)
    at async Helper.html2Image (/www/myblog/myblog/app/extend/helper.js:511:5)

从报错信息来看，问题非常明确：Puppeteer 在执行 setContent 操作时，触发了超时错误，默认的 30000 毫秒（30 秒）等待时间耗尽，最终导致接口调用失败。报错堆栈清晰地指向了 helper.js 文件的第 511 行，也就是我封装的 html2Image 方法内部，进一步定位到是 page.setContent 方法执行超时。

拿到报错后，我首先梳理了这个功能的实现逻辑：前端传递 HTML 内容到后端，后端通过 Puppeteer 启动无头浏览器，创建新页面后，调用 setContent 方法加载 HTML 内容，渲染完成后进行截图，最终将图片返回给前端。整个流程中，setContent 是核心步骤，负责将 HTML 内容注入到页面并等待渲染完成。

为了弄清楚超时的具体原因，我先回顾了近期的代码变更，确认没有修改过 html2Image 方法的核心逻辑，也没有调整过 Puppeteer 的配置，那么问题大概率出在外部因素或数据本身。结合报错信息和功能逻辑，我初步梳理了可能导致超时的几个方向，也是后续排查的重点。

首先，从报错堆栈可以明确，超时发生在 setContent 方法，而该方法的超时时间默认是 30 秒，这意味着 HTML 内容的加载或渲染过程，超过了这个默认阈值。那么第一个怀疑点就是 HTML 内容本身：是否存在内容过大、包含大量远程资源（比如图片、字体、外部 JS/CSS）的情况？因为这类资源加载需要消耗额外时间，尤其是当远程资源加载缓慢时，很容易导致整体渲染时间超过 30 秒。

其次，考虑到 Puppeteer 的运行机制，页面中的 JS 脚本也可能成为诱因。如果传递的 HTML 中包含阻塞渲染的 JS 脚本，比如无限循环、长时间运行的异步请求，或者需要等待某个外部接口返回才能完成渲染，那么也会导致 setContent 等待超时。毕竟 setContent 会等待页面达到指定的加载状态，若 JS 脚本一直阻塞，加载状态无法完成，自然会触发超时。

除此之外，服务器环境和网络状态也不能忽视。Puppeteer 启动无头浏览器需要消耗一定的 CPU 和内存资源，如果服务器当时负载过高，CPU 或内存占用率飙升，会导致页面渲染速度大幅下降，原本能在 30 秒内完成的操作，就可能因为资源不足而超时。另外，网络问题也可能导致远程资源加载失败或耗时过长，间接引发 setContent 超时。

还有一个容易被忽略的点：Puppeteer 的默认配置是否合理。比如，是否启用了不必要的资源加载，导致渲染过程中加载了大量无关资源，拖慢了整体速度。默认情况下，Puppeteer 会加载页面中的所有资源，包括图片、字体、视频等，若这些资源并非渲染必需，就会额外消耗时间，增加超时风险。

为了验证这些怀疑点，我做了一系列排查操作：首先查看了当时调用接口传递的 HTML 内容，发现部分内容确实包含大量远程图片和外部 CSS 引用，且部分图片资源来自第三方服务器，加载速度较慢；其次，检查了服务器当时的监控数据，发现接口调用高峰期，服务器 CPU 占用率一度达到 80% 以上，内存占用也接近阈值；同时，通过日志排查，发现有部分 JS 脚本存在异步请求超时的情况，导致页面渲染被阻塞。

经过逐步排查，能够确定这次 Navigation timeout 错误，是多种因素共同作用的结果：HTML 内容包含大量远程资源、服务器性能负载过高、部分 JS 脚本阻塞渲染，这三者叠加，导致 setContent 方法的执行时间超过了 Puppeteer 默认的 30 秒超时限制，最终引发接口报错。结合排查出的原因，我最终选择通过设置更长的超时时间来解决该问题，核心修改代码如下，主要是在 html2Image 方法中，给 page.setContent 方法增加 timeout 参数，延长等待时间：

async html2Image(html, options = {}) {
  const browser = await puppeteer.launch({
    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
    headless: true
  });

  const page = await browser.newPage();

  // 核心修改：延长超时时间至 60 秒，可根据实际场景调整
  const timeout = options.timeout || 60000;

  try {
    // 给 setContent 增加 timeout 参数，避免渲染超时
    await page.setContent(html, { 
      waitUntil: 'domcontentloaded',
      timeout: timeout 
    });

    const image = await page.screenshot({
      fullPage: options.fullPage || false,
      type: options.type || 'png'
    });

    await browser.close();
    return image;
  } catch (e) {
    await browser.close();
    throw e;
  }
}

修改完成后，重新部署代码并测试接口，setContent 方法有了充足的等待时间，能够顺利完成 HTML 内容的加载和渲染，超时错误不再出现，问题得到了有效解决。

整个排查过程，让我对 Puppeteer 实现 HTML 转图片的核心逻辑有了更深入的理解，也意识到这类涉及页面渲染的功能，不仅要关注代码逻辑的正确性，还要考虑数据本身、服务器环境、网络状态等多种外部因素。后续我会针对排查出的问题逐一处理，避免类似错误再次发生。

以上就是本次 Puppeteer 超时错误的完整排查记录，记录下来既是对自己开发经验的总结，也希望能给遇到同类问题的开发者提供一些思路，避免走不必要的弯路。