Puppeteer报错：Protocol error (page.printToPdf) 页码范围超出总页数

问题根源 #

这个错误明确表示你指定的pageRanges超出了PDF实际生成的总页数，常见触发场景：

• headerStartPage的值大于PDF实际总页数，比如实际只有3页，但headerStartPage设为5，那第一个PDF的范围1-4、第二个的5-都会超出有效页码
• 页面未完全渲染就执行pdf()方法，导致Puppeteer计算的页数不准确，后续指定范围时出错

修复方案 #

1. 确保页面完全渲染 #

当前使用的waitUntil: 'networkidle2'可能不足以等待动态内容（如异步加载的列表、图片）渲染完成，可调整为：

await webPage.goto(printUrl, { 
  waitUntil: 'networkidle0', // 等待网络连接完全空闲
  timeout: 60000 // 延长超时时间，适配慢加载页面
});

还可以添加等待特定元素加载的逻辑，确保所有内容渲染完毕：

// 替换为页面最后一个核心内容元素的选择器
await webPage.waitForSelector('.final-content-element', { timeout: 60000 });

2. 先获取实际总页数再指定范围 #

在生成PDF前，先获取页面实际渲染后的总页数，校验headerStartPage的合法性：

await webPage.goto(printUrl, { waitUntil: 'networkidle0', timeout: 60000 });
await webPage.waitForSelector('body');

// 计算实际总页数
const pageCount = await webPage.evaluate(() => {
  return Math.ceil(document.body.scrollHeight / window.innerHeight);
});

// 校验headerStartPage是否在有效范围内
if (headerStartPage < 1 || headerStartPage > pageCount) {
  throw new Error(`headerStartPage(${headerStartPage})超出有效页码范围1-${pageCount}`);
}

// 生成第一个PDF
const pdf1Bytes= await webPage.pdf({
  path: filePartOne,
  format: 'Letter',
  printBackground: true,
  preferCSSPageSize: true,
  displayHeaderFooter: true,
  footerTemplate: footer,
  headerTemplate: headerOne,
  defaultFontSize: '40px',
  margin: {
    top: "30mm",
    bottom: "25mm",
    right: "10mm",
    left: "15mm",
  },           
  pageRanges: `1-${headerStartPage - 1}`,
});

// 生成第二个PDF
const pdf2Bytes = await webPage.pdf({
  path: filePartTwo,
  format: 'Letter',
  printBackground: true,
  preferCSSPageSize: true,
  displayHeaderFooter: true,
  footerTemplate: footer,
  headerTemplate: headerTwo,
  defaultFontSize: '40px',
  margin: {
    top: "30mm",
    bottom: "25mm",
    right: "10mm",
    left: "15mm",
  },
  pageRanges: `${headerStartPage}-`,
});

3. 处理边界情况 #

如果headerStartPage等于1，第一个PDF的范围1-0无效，需跳过生成；如果headerStartPage等于总页数，确保第二个PDF的范围逻辑正常：

// 仅当headerStartPage大于1时生成第一个PDF
if (headerStartPage > 1) {
  const pdf1Bytes= await webPage.pdf({
    // 原有配置...
    pageRanges: `1-${headerStartPage - 1}`,
  });
}

// 仅当headerStartPage不超过总页数时生成第二个PDF
if (headerStartPage <= pageCount) {
  const pdf2Bytes = await webPage.pdf({
    // 原有配置...
    pageRanges: `${headerStartPage}-`,
  });
}

4. 检查CSS分页规则 #

如果页面使用了page-break-after或page-break-before，需确保规则正确，避免因错误分页导致页数计算偏差：

/* 示例：正确的强制分页规则 */
.page-break {
  page-break-after: always;
}

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