本文深入解析了如何用 WeasyPrint 这一 Python 生态中最可靠的 HTML 转 PDF 方案，精准还原复杂 HTML 页面的样式——尤其针对中文排版、字体嵌入、Flex/Grid 布局、分页控制等高频痛点，指出纯前端方案（如 jsPDF + html2canvas）在字体渲染、伪元素、响应式打印等方面的根本性缺陷，并手把手指导显式声明中文字体路径、规避 JS 依赖、善用 `@page` 和 `break-` 系列属性、正确处理单位与媒体查询等实战要点，帮你告别方块字、错位页眉和跨页断裂，真正实现设计稿到 PDF 的像素级一致性。

用 weasyprint 保留 HTML 样式转 PDF 最稳

纯前端 JS 方案（如 jsPDF + html2canvas）几乎无法真正保样式：字体嵌入失败、flex/grid 布局错乱、伪元素丢失、@media print 生效不可控。真正能复现浏览器渲染效果的，是基于真实 CSS 引擎的后端方案。weasyprint 是目前 Python 生态中对 CSS 支持最完整、对中文/字体/分页控制最友好的选择。

• weasyprint 基于 WebKit 渲染逻辑重构，支持 @page、break-before/after/inside、counter-reset/increment 等关键分页属性
• 必须显式指定中文字体路径，否则默认用 DejaVu Sans，中文会显示为方块
• 不支持 JavaScript 执行，所有动态内容需在生成 HTML 前完成渲染
• 不识别 rem 单位（除非根元素 font-size 是绝对值），建议统一用 px 或 pt

pip install weasyprint
# 示例：加载含内联样式的 HTML 并输出 PDF
from weasyprint import HTML
HTML(string='''




第一页
正文内容...

''').write_pdf('output.pdf')

@media print 不生效？检查这三点

很多开发者写了 @media print 却发现 PDF 里没反应，根本原因不是语法错，而是渲染引擎未触发打印上下文。

• weasyprint 默认即处于 print 媒体模式，无需额外声明 @media print —— 直接写样式即可；但若混用 @media screen，必须确保 print 规则权重更高或位置靠后
• 浏览器 DevTools 的 “Print preview” 模式用的是 Blink 引擎，而 weasyprint 是独立实现，部分 CSS 属性（如 zoom、-webkit-print-color-adjust）完全不支持
• 避免用 display: none 隐藏打印内容；应改用 @page { size: A4; margin: 0; } + body { margin: 1cm; } 控制实际可打印区域

字体嵌入失败导致中文变方块？路径和声明必须匹配

weasyprint 不读取系统字体，所有字体必须通过 @font-face 显式声明且路径可访问。常见错误是路径写相对 URL（如 ./fonts/NotoSans.otf），但 Python 进程工作目录 ≠ HTML 文件所在目录。

• 推荐用绝对路径：file:///full/path/to/NotoSansCJKsc-Regular.otf（注意三个斜杠）
• 字体格式优先选 .otf 或 .ttf；.woff/.woff2 不支持
• 声明时 font-family 名称要和 HTML 中 font-family 属性值**完全一致**（区分大小写、空格）
• 可加 !important 强制覆盖默认字体：body { font-family: "Noto Sans CJK SC" !important; }

表格跨页断裂、页眉页脚错位？用 break- 系列属性硬控

CSS 分页控制是保样式的最后一道防线。浏览器自动分页很随意，weasyprint 提供了更底层的干预能力。

• table { break-inside: avoid; } 防止表格被拆到两页
• tr:last-child { break-after: always; } 强制在某行后翻页
• 页眉页脚不用 JS 插入，改用 @page + ::before/::after 伪元素：@page { @top-center { content: "报表标题"; } }
• position: fixed 在 PDF 中无效，所有“固定定位”内容必须通过 @page 规则定义

真正难的不是生成 PDF，而是让每一页的留白、断行、字体尺寸、页码计数都和设计稿严丝合缝。这些细节没有银弹，得一行行试 break-、调 @page margin、换字体路径——尤其是中文字体文件权限和编码问题，最容易卡一整天。

到这里，我们也就讲完了《HTML转PDF保持格式技巧大全》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！