本文详解如何在 go 中借助 go-wkhtmltopdf 实现「每页独立起始」的 pdf 生成——通过 css 分页指令隔离内容、分离头尾模板，并动态注入变量，彻底避免表格跨页断裂与页眉误入前一页等问题。
本文详解如何在 go 中借助 go-wkhtmltopdf 实现「每页独立起始」的 pdf 生成——通过 css 分页指令隔离内容、分离头尾模板，并动态注入变量，彻底避免表格跨页断裂与页眉误入前一页等问题。
在使用 go-wkhtmltopdf 构建动态报表系统时，一个常见痛点是：当 HTML 内容（如长表格）自然流式渲染时，wkhtmltopdf 默认按内容高度自动分页，导致页眉被“挤”到上一页末尾、表格行被强行截断，破坏阅读逻辑和专业排版。解决核心在于将分页控制权从 wkhtmltopdf 的自动布局交还给开发者——即显式声明每页内容边界，并将页眉/页脚完全解耦为独立模板。
✅ 正确实践：三步实现精准分页
-
HTML 内容层：用 page-break-before: always 显式分页
为每个逻辑页面（如含 20 行数据的表格块）包裹一个带 .page 类的，并在 CSS 中强制其始终在新页开始：<style> .page { page-break-before: always; /* 关键：确保新页开始 */ break-before: page; /* 推荐同时添加现代标准语法 */ font-size: 16px; margin: 0; } /* 避免内部元素意外分页 */ .page table, .page tr, .page td { page-break-inside: avoid; } </style> <body> <div class="page"> <h2>第 1 页报告</h2> <table>...</table> </div> <div class="page"> <h2>第 2 页报告</h2> <table>...</table> </div> </body>PDF 生成层：禁用内容内嵌头尾，改用 Header* / Footer* 属性注入
❌ 错误做法：在 HTML 中硬编码或 page := wkhtml.NewPageReader(strings.NewReader(html)) // ✅ 使用内置页眉：支持 [page], [frompage], [topage] 等占位符 page.HeaderCenter.Set("报表 - 第 [page] 页") page.HeaderLine.Set(true) // 显示分隔线 // ✅ 使用自定义 HTML 页脚（推荐用于复杂布局） page.FooterHTML.Set("./footer.html") // ✅ 动态传参：供 footer.html 中 JavaScript 解析 page.Replace.Set("report_id", "RPT-2024-001") page.Replace.Set("generated_at", time.Now().Format("2006-01-02 15:04"))页脚模板（footer.html）：安全解析并渲染动态内容
wkhtmltopdf 会将 Replace 参数以 URL 查询字符串形式注入页脚 HTML。以下是一个健壮的 footer.html 示例，兼容所有常用变量：<!DOCTYPE html> <html> <head> <script> function subst() { const params = new URLSearchParams(window.location.search); const vars = Object.fromEntries(params.entries()); const classes = ['page', 'frompage', 'topage', 'date', 'time', 'report_id', 'generated_at']; classes.forEach(cls => { document.querySelectorAll('.' + cls).forEach(el => { el.textContent = vars[cls] || ''; }); }); } </script> </head> <body style="margin: 0; padding: 0;" onload="subst()"> <table width="100%" style="border-top: 1px solid #ccc; font-size: 12px;"> <tr> <td align="left" class="report_id"></td> <td align="center">生成时间：<span class="generated_at"></span></td> <td align="right">第 <span class="page"></span> 页 / 共 <span class="topage"></span> 页</td> </tr> </table> </body> </html>⚠️ 关键注意事项
- CSS 分页属性兼容性：page-break-before 是广泛支持的旧标准，但建议同时添加 break-before: page（CSS Fragmentation Module Level 3），提升未来兼容性。
- 页边距必须显式设置：若未调用 pdfg.MarginTop.Set() 或 pdfg.MarginBottom.Set()，页眉/页脚可能被裁切。建议预留 ≥10mm 安全边距。
- 页脚 HTML 路径需为绝对路径或工作目录相对路径：FooterHTML.Set() 不支持嵌入式 HTML 字符串，必须指向磁盘文件。
- 动态内容防 XSS：footer.html 中的 JavaScript 仅做文本替换，不执行用户输入，但若需渲染富文本，请严格过滤 vars 值。
- 性能优化：对大量分页（如百页报表），避免在单个 HTML 中拼接全部 .page 块；可改为循环创建多个 PageReader 并 AddPage()，内存更可控。
通过以上结构化方案，你不仅能彻底解决“页眉窜页”“表格断行”等排版顽疾，还能灵活扩展页眉徽标、多级页码、章节标题等企业级报表需求。最终生成的 PDF 将严格遵循设计预期：每页以完整页眉启始，以规范页脚收束，内容区块边界清晰、专业可靠。
