HTML转PDF失败主因是渲染引擎CSS支持差异：flex布局常失效，@media print规则兼容性差，中文字体易缺失成方块，需双轨维护样式与字体路径。
HTML 转 PDF 不是“丢进去就出来”，核心问题在于：浏览器渲染的 HTML 和 PDF 渲染引擎（如 pdfkit、weasyprint、puppeteer）对 CSS 的支持差异极大，直接套用网页样式大概率导致排版错乱、字体丢失、分页失控。
为什么 display: flex 在 PDF 里经常失效
多数轻量级 HTML→PDF 工具（如 weasyprint 5.x、pdfkit）不支持完整 Flexbox，justify-content 或 flex-wrap 可能被完全忽略；puppeteer 虽基于 Chromium，但打印模式下部分 flex 行为与屏幕渲染不一致（比如 min-height 不触发伸缩）。
- 优先用
display: block+float或inline-block布局，尤其对多栏、卡片类结构 - 避免嵌套三层以上 flex 容器；若必须用，改用
@page+break-inside: avoid控制分页，比靠 flex 对齐更可靠 -
puppeteer中可加emulateMedia: 'screen'强制按屏幕样式渲染，但会牺牲打印优化（如去掉背景图），需权衡
@media print 规则在不同工具里效果天差地别
@media print 是前端最常写的适配逻辑，但它在 PDF 工具链中支持程度极不统一：puppeteer 完全尊重，weasyprint 仅支持部分属性（如 color、display），pdfkit 则完全无视。
- 不要把关键布局逻辑（如隐藏导航栏、调整字体大小）只写在
@media print里；用独立 class（如pdf-only）配合内联 style 或 JS 注入更可控 - 字体相关声明（
font-family、font-size）建议同时写在默认样式和@media print中，防止 fallback 失效 - weasyprint 支持
@page { size: A4; margin: 2cm; }，但不支持@page :first，需要分页标题时得用break-before: page
中文字体缺失导致 PDF 里全是方框
PDF 工具默认不加载系统字体，simhei.ttf、noto-sans-sc 等常见中文字体路径若未显式注册或嵌入，就会回退到无中文支持的默认字体（如 Helvetica），结果就是满屏□。
立即学习“前端免费学习笔记（深入）”；
-
weasyprint需通过--fonts-dir指定字体目录，或在 CSS 中用@font-face加载绝对路径（注意：不能用相对路径或网络 URL） -
puppeteer无需注册字体，但要确保生成 PDF 的服务器上已安装对应字体，且 Chrome 启动时能读取（Linux 常需fc-cache -fv刷新缓存） -
pdfkit不解析 CSS 字体，必须手动调用doc.font('path/to/simhei.ttf')，每个文本块都要显式指定，无法全局继承
真正难的不是转换动作本身，而是把“网页能跑”和“PDF 能印”当成两个独立样式环境来维护——CSS 类名、字体加载路径、分页断点，都得有双轨意识。漏掉任意一环，PDF 就可能在客户邮件里变成一张白纸加几个方块。
