本文直击HTML转PDF中“导出两页、其一空白”的高频痛点，解析height: 100%在打印上下文中的隐式溢出机制，结合CSS Paged Media规范与Chromium无头渲染特性，提供可立即验证的修复方案与排版原则。
本文直击html转pdf中“导出两页、其一空白”的高频痛点，解析`height: 100%`在打印上下文中的隐式溢出机制，结合css paged media规范与chromium无头渲染特性，提供可立即验证的修复方案与排版原则。
在将HTML精准输出为单页PDF（如A4横向）时，开发者常陷入一个典型误区：过度依赖像素/点（pt）硬设尺寸 + 全局height: 100%级联控制。你提供的代码看似严谨——指定了@page { size: A4 landscape; margin: 0mm }，容器宽高精确计算为841pt × 594pt（A4横向尺寸），子项也声明height: 100%，但最终却生成了包含空白页的双页PDF。根本原因并非尺寸计算错误，而是CSS盒模型在分页上下文中的行为差异被忽视了。
? 根本原因：height: 100%触发隐式内容溢出
在浏览器默认渲染流中，height: 100%要求元素高度严格等于其包含块（containing block）的高度。但在PDF生成阶段（尤其是Chromium --print-to-pdf模式），页面布局遵循CSS Paged Media规范，此时：
-
.item的高度由父容器.container的grid布局决定，实际渲染高度≈594pt； - 而
.item div同时设置了padding: 2em（约32px，即≈24pt）且height: 100%； -
height: 100%仅约束内容区（content box），不包含padding → 实际占用高度 =100% + 2em × 2≈594pt + 48pt>594pt； - 当内容总高度超过单页可用空间时，Chromium会自动插入分页符，并因后续无内容而生成空白页。
✅ 正确做法：移除
.item div中的height: 100%，改用min-height: 0或flex布局保障弹性填充，同时显式控制内边距对高度的影响。
✅ 立即生效的修复方案
.item div {
padding: 2em;
text-align: left;
overflow-y: hidden;
/* 删除 height: 100%; —— 这是罪魁祸首 */
/* 推荐增强：添加 min-height: 0 防止 grid 子项最小高度干扰 */
min-height: 0;
}同时建议补充以下健壮性设置：
立即学习“前端免费学习笔记（深入）”；
/* 强制禁用分页断点（避免子项跨页） */
.item {
break-inside: avoid; /* 关键！防止 grid item 被拆分到两页 */
}
/* 确保 body 不产生额外空白 */
body {
break-before: auto;
break-after: auto;
}⚠️ 注意事项与进阶建议
-
不要迷信
calc()绝对尺寸：841pt - 2px这类混合单位计算在不同DPI或缩放环境下易失准，推荐统一使用mm或in（如width: 297mm; height: 210mm;）； -
字体与行高是隐形高度杀手：
font-size: 18px在100%缩放下实际行高可能达~28px，多段文本叠加极易突破单页。建议设置line-height: 1.2并用overflow: hidden兜底； -
Chromium打印参数需匹配：确保命令行参数一致，例如：
chrome --headless=new \ --print-to-pdf-no-header \ --no-pdf-header-footer \ --print-to-pdf=output.pdf \ input.html -
终极验证方式：在Chrome浏览器中直接打开HTML →
Cmd+P→ 选择“另存为PDF”，勾选“更多设置”中“背景图形”，观察预览是否单页——这与--print-to-pdf行为高度一致。
掌握这一原理后，你不仅能解决空白页问题，更能系统规避表格跨页断裂、页眉页脚错位、中文字体截断等同类排版故障。记住：PDF不是放大版网页，而是物理纸张的数字映射；所有“看起来刚好”的CSS，在分页引擎眼中都可能是越界的隐患。
