在 HTML 转 PDF（如通过 Node.js 生成）时，多页打印常出现页眉覆盖内容、表格跨页错位等问题；核心解法是合理使用 @media print、page-break-* 属性及语义化布局替代 position: fixed，确保每页顶部预留安全间距且表头自动重复。
在 html 转 pdf（如通过 node.js 生成）时，多页打印常出现页眉覆盖内容、表格跨页错位等问题；核心解法是合理使用 `@media print`、`page-break-*` 属性及语义化布局替代 `position: fixed`，确保每页顶部预留安全间距且表头自动重复。
为所有打印页面顶部添加一致留白，并解决页眉/表头重叠问题，关键在于放弃 position: fixed 布局用于打印场景——因其在分页时无法随内容流重置位置，极易导致跨页覆盖。正确的做法是结合 CSS 分页控制与结构化语义，实现可靠、可预测的多页输出。
✅ 推荐方案：使用 @media print + thead 自动重复 + 顶部内边距
@media print {
/* 确保表格头部在每页顶部自动显示 */
thead {
display: table-header-group;
}
/* 为整个文档内容区域预留顶部安全间距（即“虚拟页眉高度”）*/
body {
padding-top: 60px; /* 根据实际页眉高度调整，如 60px */
}
/* 可选：为第一页额外增加顶部空白（若需区别于后续页）*/
@page :first {
margin-top: 80px;
}
@page {
margin-top: 60px; /* 后续所有页面统一上边距 */
}
/* 避免表格行被截断，强制整行留在同一页 */
tr {
page-break-inside: avoid;
}
/* 对明确需要分页的位置（如章节标题），使用 page-break-before */
.page-break-before {
page-break-before: always;
}
}
⚠️ 注意事项与常见误区
-
不要用
position: fixed实现打印页眉：fixed元素在 PDF 渲染中通常脱离分页上下文，导致所有页眉堆叠在第一页顶部，后续页无页眉或错位。 -
grid/flex布局在@media print中兼容性有限：尤其在 Puppeteer、wkhtmltopdf 等主流 Node.js PDF 工具中，display: grid对分页支持极差；请优先使用语义化<header></header>+padding/margin或<thead> 原生机制。<li> <strong><code>page-break-inside: avoid比page-break-before更可靠：对表格行、卡片容器等块级元素设置avoid，可有效防止内容被强行截断，比依赖人工添加.page-break类更健壮。 -
测试务必使用目标 PDF 工具渲染：不同引擎（Puppeteer vs. WeasyPrint vs. Prince）对 CSS Paged Media 支持程度不同；建议始终以
margin和padding为基础，辅以thead和page-break-inside。
? 补充技巧：自定义页眉（需高级工具支持）
若需动态页眉（如页码、标题），且使用 Puppeteer，推荐在 print() 选项中启用原生页眉：
await page.pdf({
format: 'A4',
printBackground: true,
displayHeaderFooter: true,
headerTemplate: '<div style="font-size:10px; margin-left:20mm;">My Report</div>',
footerTemplate: '<div style="font-size:9px; text-align:right; margin-right:20mm;">Page <span class="pageNumber"></span>
</div>',
});
此时 CSS 中无需再手动定位页眉，彻底规避重叠风险。
综上，用 @page { margin-top } 定义全局页顶留白 + thead { display: table-header-group } 保证表头复用 + tr { page-break-inside: avoid } 防止内容断裂，是最简洁、兼容性最强、符合打印语义的解决方案。
