HTML转PDF效果取决于HTML/CSS质量与渲染引擎能力；需主动适配print媒体查询、强制分页、内联字体及针对性布局约束，而非依赖工具自动修复。
HTML 转 PDF 本身不会自动“改善”格式转换——它只是把 HTML 渲染结果快照成 PDF，而最终效果完全取决于 HTML 结构、CSS 控制力和渲染引擎能力。想让 PDF 排版靠谱，得从 HTML/CSS 层面主动适配，而不是依赖工具“智能修复”。
为什么 print 媒体查询经常失效
很多开发者以为加了 @media print 就万事大吉，但实际中它常被忽略或覆盖。核心问题在于：多数 HTML→PDF 工具（如 wkhtmltopdf、Puppeteer）默认不触发浏览器的完整打印样式链，也不会执行 window.print() 的样式重置逻辑。
- 务必在 HTML 中显式引入
@media print样式，并用!important提升关键规则优先级（比如body { margin: 0 !important; }） - 避免依赖
display: none隐藏元素——某些引擎对动态样式解析不完整，改用visibility: hidden或直接移除 DOM 节点更可靠 -
Puppeteer需显式传参：page.pdf({ printBackground: true })，否则 CSS 背景色/图将丢失
wkhtmltopdf 的 page-break 控制不生效怎么办
wkhtmltopdf 对分页支持有限，page-break-before、break-inside: avoid 等属性容易被忽略，尤其在表格或浮动布局中。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 强制分页请用
<div style="page-break-before: always;"></div>，且该div必须是块级、无浮动、无负 margin - 表格跨页断裂？给
table加style="page-break-inside: avoid;"不一定管用；更稳妥的是用thead { display: table-header-group; }确保表头重复，再配合tr内联样式控制单行高度 - 升级到
wkhtmltopdf 0.12.6+，旧版本对 Flex/Grid 完全不识别，会直接回退为块流，导致布局错乱
Puppeteer 生成 PDF 时字体缺失或中文乱码
这是最常被低估的问题：PDF 渲染器（Chromium）默认只加载系统基础字体，不继承你开发机上安装的思源黑体、Noto Sans SC 等。即使 HTML 中写了 font-family: "Noto Sans SC"，PDF 里也可能回退成方块或 Times New Roman。
立即学习“前端免费学习笔记（深入）”；
- 必须在 HTML 中内联加载字体：用
@font-face+src: url(data:font/woff2;base64,...)嵌入 base64 字体（推荐 woff2，体积小兼容好） - 避免使用
font-display: swap，PDF 渲染不等字体加载完成就截屏，会导致文字渲染为空白 - Linux 服务器上运行 Puppeteer 时，需预装字体包（如 Ubuntu 下
apt install fonts-noto-cjk），否则即使 base64 生效，字号/行高仍可能异常
真正卡住人的从来不是“怎么转”，而是“怎么让换行、页眉页脚、中文字号、表格对齐这些细节在 PDF 里稳定复现”。每种工具对 CSS 的支持粒度不同，没有通用方案，只能按目标引擎针对性约束 HTML 输出——比如给 wkhtmltopdf 写语义简单、float+table 为主的 HTML；给 Puppeteer 则可放开 Grid/Flex，但必须亲手喂字体、控分页、禁动画。
