使用 PDFkit 和 Wkhtmltopdf 生成 PDF 时，长表格常被整体挤到下一页而非自然分页；根本原因常是父容器 overflow 属性（如 hidden 或 auto）干扰了 wkhtmltopdf 的分页计算，将其设为 visible 即可修复。
使用 pdfkit 和 wkhtmltopdf 生成 pdf 时，长表格常被整体挤到下一页而非自然分页；根本原因常是父容器 `overflow` 属性（如 `hidden` 或 `auto`）干扰了 wkhtmltopdf 的分页计算，将其设为 `visible` 即可修复。
在 Django 项目中通过 PDFkit 调用 wkhtmltopdf 渲染 HTML 为 PDF 时，表格内容（尤其是行数较多时）频繁出现“整表跳页”现象——即本该在当前页底部继续显示的表格，却完全消失并出现在下一页顶部。尽管开发者常尝试 page-break-inside: avoid、table-header-group 等 CSS 分页控制规则，效果往往不佳。这并非 CSS 本身失效，而是 wkhtmltopdf 在布局计算中对某些 CSS 属性异常敏感。
关键症结：父级容器的 overflow 属性
wkhtmltopdf 对 overflow: hidden、overflow: auto 或 overflow: scroll 的容器具有严格限制：一旦表格位于此类容器内，其内部内容将被视为不可分割的“原子块”，导致分页引擎放弃在表格内部断行，转而强制整表移至新页。这是 wkhtmltopdf 的已知渲染行为（非 bug，属布局约束）。
✅ 正确解法非常简洁：
将包裹表格的
<!-- ✅ 推荐写法 --> <div style="overflow: visible;"> <table class="data-table"> <thead>...</thead> <tbody> <tr><td>Row 1</td></tr> <tr><td>Row 2</td></tr> <!-- ... many rows ... --> </tbody> </table> </div>
⚠️ 注意事项：
- 不要仅依赖 page-break-inside: avoid —— 它在 overflow: hidden 容器中会被忽略；
- 避免对表格父容器设置 height、max-height 或 position: absolute，这些同样会触发 wkhtmltopdf 的“不可分页”判定；
- 若需滚动效果（如预览时），请仅在 HTML 预览阶段启用 overflow: auto，生成 PDF 前动态移除或覆盖为 visible；
- 表格自身仍建议保留稳健的分页辅助样式：
table { page-break-inside: auto; }
tr { page-break-inside: avoid; page-break-after: auto; }
thead { display: table-header-group; }
tfoot { display: table-footer-group; }
最后，在 Django 视图中确保 HTML 模板已应用上述修正，并通过 pdfkit.from_string() 或 pdfkit.from_url() 输出时，wkhtmltopdf 将能正确识别表格内部断点，实现平滑跨页渲染。无需引入外部 JS 补丁（如 wkhtmltopdf_tableSplitHack.js），轻量且兼容性更佳。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
