Puppeteer无法生成PDF文件问题排查求助

问题描述 #

使用Puppeteer访问自有网站生成PDF时，screenshot方法可正常工作，但pdf方法无响应，等待数分钟仍无结果。设置headless: false时页面能正常加载，相关代码如下：

async generatePdfByWisitingWebsite(user: UserEntity, data: InputGetPdfDto) {
    const browser = await puppeteer.launch({ headless: true, protocolTimeout: 500000 });
    const page = await browser.newPage();
    await page.goto('http://localhost:3000/login', { waitUntil: 'networkidle2' });
    await page.type('#email', '...');
    await page.type('#password', '...');
    await page.click('#loginButton');

    await page.waitForNavigation({ waitUntil: 'networkidle2' });
    await page.goto('http://localhost:3000/app/account', { waitUntil: 'networkidle2' });

    await new Promise(function (resolve) {
      setTimeout(resolve, 2000);
    });

    const content = await page.evaluate(() => document.body.innerHTML);
    console.log(content);

    await page.screenshot({ path: 'output/build1.png' });


    await page.pdf({
      path: 'output/test.pdf',
      format: 'A4',
      printBackground: true,
      margin: {
        top: '10mm',
        right: '10mm',
        bottom: '10mm',
        left: '10mm',
      },
      timeout: 0,
    });

    await browser.close();
  }

排查与解决思路 #

• 切换无头模式版本：Puppeteer v19+默认的headless: true是新版Headless Chrome，可能存在兼容性问题。尝试改为headless: "chrome"（旧版无头模式），或明确用headless: false对比验证。
• 替换固定延迟为精准等待：固定2秒延迟无法保证页面完全渲染完成，尤其是无头模式下资源加载速度可能不同。在调用pdf前添加await page.waitForSelector('页面关键元素的选择器')，确保核心内容渲染完毕。
• 排查页面脚本阻塞：部分页面脚本在无头模式下可能进入死循环或无限等待，导致PDF生成卡住。可尝试在page.goto时禁用JavaScript：{ waitUntil: 'domcontentloaded', javaScriptEnabled: false }，若能生成PDF，再逐步定位问题脚本。
• 调整PDF生成参数：
  • 移除timeout: 0，设置合理超时（如timeout: 60000）并捕获错误，确认是否为超时问题。
  • 暂时去掉printBackground: true，部分背景渲染逻辑可能在无头模式下引发阻塞。
  • 尝试用width/height替代format: 'A4'，测试是否因页面尺寸导致渲染异常。
• 查看Chrome日志：启动浏览器时添加dumpio: true参数，捕获Chrome的输出日志，查找报错或阻塞线索：

  const browser = await puppeteer.launch({ headless: true, protocolTimeout: 500000, dumpio: true });
  

• 检查打印样式：页面的@media print样式可能在无头模式下导致布局异常，进而阻塞PDF生成。可在调用pdf前注入脚本临时禁用打印样式：

  await page.addStyleTag({ content: '@media print { * { display: block !important; } }' });
  

• 升级Puppeteer版本：旧版本可能存在无头模式PDF生成的已知bug，尝试升级到最新稳定版。

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