HTML页眉页脚转PDF技巧分享

本文深入解析了在HTML转PDF过程中精准控制页眉页脚的关键技巧与常见陷阱：必须手动关闭Chrome打印设置中的系统页眉页脚才能让CSS样式生效；@page规则虽可设置页边距（包括:first伪类定制首页），但不支持嵌套样式；position:fixed在PDF中仅首屏渲染，需改用margin预留空间配合普通元素模拟；页码显示严格依赖class="pageNumber"和"totalPages"这两个硬编码标识，任何变体均失效；而真正可靠的方案往往需借助Puppeteer等服务端工具，以获得对页眉页脚、双面布局及动态页码的完整控制——掌握这些细节，才能告别PDF导出时页眉错位、页码消失、首页样式失控的尴尬局面。

Chrome DevTools 打印预览中页眉页脚开关在哪

Chrome 默认开启系统页眉页脚（含 URL、页码、日期），这会覆盖你用 CSS 写的 @page 页边距或 position: fixed 页眉页脚。必须手动关闭——它不在网页代码里，而在打印设置界面。

• 按 Ctrl+P（Windows）或 Cmd+P（macOS）唤出打印面板
• 点击右下角「更多设置」展开区域
• 取消勾选「页眉和页脚」复选框（注意：不是「背景图形」，也不是「页面边距」）
• 此时 @page { margin: 2cm; } 和自定义页眉页脚才真正生效

CSS @page + :first 伪类控制首页页眉不同

PDF 分页由浏览器渲染引擎自动触发，@page 是唯一能影响分页后整体布局的 CSS 规则。但 @page :first 只对第一页生效，且不能写选择器嵌套内容，只能设页边距与空白。

@page {
  margin: 1.5cm;
}
@page :first {
  margin-top: 3cm; /* 首页留高一点，方便放标题 */
}
/* ❌ 错误：以下无效 */
@page :first {
  header { display: none; } /* 不支持 */
}

想让首页无页眉、其余页有，得靠 JS 动态加 class 控制 DOM 元素显隐，再结合 @page 调整页边距匹配视觉留白。

position: fixed 页眉页脚在 PDF 中失效原因

Chrome 的 PDF 导出不支持 position: fixed 在跨页时重复渲染（即不会每页都显示一个固定定位元素）。它只会在第一页渲染一次，后续页丢失。

• 替代方案：用 @page 的 margin 预留空间，再用普通
  + margin-top 模拟页眉
• 更可靠做法：服务端生成 PDF（如 Puppeteer、WeasyPrint），它们支持 @page :left/:right 和 running() 函数
• Puppeteer 示例关键配置：

  await page.pdf({
    displayHeaderFooter: true,
    headerTemplate: '<div style="font-size:10px;margin-left:1cm;">Report v2.1</div>',
    footerTemplate: '<div style="font-size:9px;text-align:right;margin-right:1cm;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
    printBackground: true
  });

页码显示用 class="pageNumber" 而不是 data-* 属性

Chrome 原生 PDF 导出只识别两个特殊 class 名：pageNumber 和 totalPages。它们是硬编码解析的，写成 data-page-number 或 pg-num 完全无效。

• → 渲染为当前页数字（如 “3”）
• → 渲染为总页数（如 “12”）
• 这两个 class 必须出现在 headerTemplate 或 footerTemplate 字符串中，不能靠 JS 插入
• 若用纯前端导出（如 jsPDF），需自行计算分页并逐页写入页码，复杂度陡增

实际转 PDF 时最易忽略的是：页眉页脚是否启用，完全由客户端打印设置决定，和服务端 HTML 结构无关；而页码占位符名是死的，拼错一个字母就变空白。

今天关于《HTML页眉页脚转PDF技巧分享》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！