Puppeteer HTML转PDF时thead被分页截断后下页出现重叠问题

问题根因 #

该问题是Puppeteer 1.19.0对应版本内置Chromium的已知打印渲染bug：多行表头刚好被分页线截断时，浏览器会同时渲染上一页未显示完的半截表头、以及下一页的完整表头，最终出现重叠效果。 #

可行解决方案 #

方案1：新增打印专用CSS（改造成本最低） #

你之前只配置了tr的分页避免规则，需要补充thead、th的防截断规则，同时微调布局避免表头刚好卡在分页线位置：

@media print {
  thead {
    display: table-header-group !important;
    page-break-inside: avoid !important;
    break-inside: avoid !important;
  }
  th {
    page-break-inside: avoid !important;
    break-inside: avoid !important;
  }
  table {
    overflow: visible !important;
    break-before: avoid !important;
    /* 极小的上边距微调，避开刚好卡到分页线的极端场景 */
    margin-top: 2px !important;
  }
  tr {
    page-break-inside: avoid !important;
  }
}

方案2：手动控制分页 #

如果CSS规则在旧版Chromium上不生效，可以在渲染HTML时提前计算多行表头的总高度，判断当前渲染位置到页尾的剩余高度不足以放下完整表头时，主动在表格前插入分页符：

<!-- 放在表格前面，强制将整个表头推到下一页 -->
<div style="page-break-after: always;"></div>

方案3：升级Puppeteer版本（彻底解决） #

该bug在Puppeteer 2.0及以上版本已经被修复，升级后无需额外配置复杂规则，你原本写的基础CSS就能正常生效。升级后仅需适配少量API变更，page.pdf()核心参数基本兼容旧版本。 #

调试小技巧 #

可以临时将Puppeteer的headless模式关闭，手动打开浏览器打印预览校验效果，无需每次生成PDF查看，大幅提升调试效率。

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