WeasyPrint是目前Python生态中CSS支持最完整、中文/字体/分页控制最友好的PDF生成方案，基于WebKit渲染逻辑重构，需显式声明中文字体路径、避免JS依赖、用break-系列属性和@page精确控制分页与样式。
用 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='''
<html>
<head>
<style>
@font-face {
font-family: "Noto Sans CJK SC";
src: url("/path/to/NotoSansCJKsc-Regular.otf");
}
body { font-family: "Noto Sans CJK SC"; font-size: 12pt; }
h1 { break-before: page; }
</style>
</head>
<body><h1>第一页</h1><p>正文内容...</p></body>
</html>
''').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、换字体路径——尤其是中文字体文件权限和编码问题，最容易卡一整天。
