本文深入解析了如何用 Python 的 WeasyPrint 工具实现 HTML 到 PDF 的高保真转换，直击前端方案（如 jsPDF + html2canvas）在字体嵌入、Flex/Grid 布局、伪元素、分页控制等方面普遍失真的痛点；强调 WeasyPrint 凭借基于 WebKit 重构的纯 CSS 渲染引擎，在中文支持、@page 规则、break-系列分页属性和计数器等关键能力上远超同类方案，同时详述了中文字体路径声明、绝对单位选用、@media print 的误用规避、表格防断页、页眉页脚原生定义等实战要点——这不仅是一份工具指南，更是破解 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学习网公众号！