Puppeteer v24.4.0生成PDF时页眉图片加载报错如何解决？

你在使用Puppeteer v24.4.0生成带页眉图片的PDF时，遇到了ProtocolError: Protocol error (Page.printToPDF): Printing failed错误，以下是针对性的解决思路和修正方案：

原问题代码 #

const imgBase64 = readFileSync(imgPath).toString("base64");
const headerTemplate = `
<div style="width:100%; height: 50px;">
  <img src="data:image/png;base64,${imgBase64}" alt="logo">
</div>`;
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.setContent(htmlContent, { waitUntil: "networkidle0" });
await page.pdf({
   path: outputPath,
   format: "A4",
   displayHeaderFooter: true,
   margin: { top: "390px", bottom: "150px", left: "20px", right: "20px" },
   headerTemplate: headerTemplate,
   footerTemplate: footerTemplate,
   printBackground: true,
});

await browser.close();

解决步骤 #

• 调整页眉图片样式与容器适配
  原页眉模板中的图片未设置尺寸限制，可能超出页眉容器导致渲染异常。给图片添加max-width和max-height，确保它在50px高的容器内正常显示：

  <div style="width:100%; height: 50px; padding: 5px 0;">
    <img src="data:image/png;base64,${imgBase64}" alt="logo" style="max-width:100%; max-height:40px;">
  </div>
  

• 修正边距配置
  A4纸张的有效打印高度约为1123px，原top: "390px"的边距过大，会导致内容区域与页眉/页脚的布局冲突。建议调整为合理值，比如：

  margin: { top: "80px", bottom: "60px", left: "20px", right: "20px" }
  

• 确保footerTemplate有效
  代码中引用了footerTemplate但未给出定义，空模板或格式错误会触发打印失败。至少要定义一个空的有效HTML模板：

  const footerTemplate = `<div></div>`;
  

• 切换到新无头模式
  Puppeteer v24+默认使用headless: 'new'模式，原代码的headless: true（对应旧无头模式）可能存在兼容性问题，修改为：

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

• 验证图片Base64编码
  确认readFileSync读取的图片路径正确，Base64编码未损坏。可以通过打印imgBase64的前20个字符，或替换为已知有效的Base64图片测试。

修正后的完整代码示例 #

const fs = require('fs');
const puppeteer = require('puppeteer');

async function generatePDF(htmlContent, imgPath, outputPath) {
  // 读取并编码图片为Base64
  const imgBase64 = fs.readFileSync(imgPath).toString("base64");
  
  // 适配的页眉模板
  const headerTemplate = `
    <div style="width:100%; height: 50px; padding: 5px 0;">
      <img src="data:image/png;base64,${imgBase64}" alt="logo" style="max-width:100%; max-height:40px;">
    </div>`;
  
  // 有效页脚模板
  const footerTemplate = `<div style="width:100%; text-align:center; font-size:10px; padding:5px 0;">第<span class="pageNumber"></span>页，共<span class="totalPages"></span>页</div>`;

  // 使用新无头模式启动浏览器
  const browser = await puppeteer.launch({ headless: 'new' });
  const page = await browser.newPage();
  
  // 加载HTML内容
  await page.setContent(htmlContent, { waitUntil: "networkidle0" });
  
  // 生成PDF
  await page.pdf({
    path: outputPath,
    format: "A4",
    displayHeaderFooter: true,
    margin: { top: "80px", bottom: "60px", left: "20px", right: "20px" },
    headerTemplate: headerTemplate,
    footerTemplate: footerTemplate,
    printBackground: true,
  });

  await browser.close();
}

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