用 WeasyPrint 把 HTML 转成 PDF：从 pip install 到第一份报告

【免费下载链接】WeasyPrintThe awesome document factory项目地址: https://gitcode.com/gh_mirrors/we/WeasyPrint

服务端要产出可打印的报告、发票或对账单时，可以用 WeasyPrint 把 HTML 转 PDF。它不依赖浏览器内核：CSS 布局引擎是纯 Python 代码，文本渲染交给 Pango，无需安装 Chromium 或无头浏览器。

🧩 能力速览：WeasyPrint HTML 转 PDF

把 HTML 解析成盒模型树，并按 CSS 计算每个块的位置与尺寸。按页面尺寸和边距把内容切成多页，把页码、脚注、页眉排进指定位置。输出带嵌入字体、图片和链接的矢量 PDF，效果与浏览器预览一致，无需安装 Chromium。还支持 PDF/A 等归档变体，并能为屏幕阅读器附加无障碍标签。整条链路在单个 Python 进程内完成，不产生子进程调用，也不请求外部服务。

🚀 最短上手路径

复制下面三行，依次运行：

pip install weasyprint echo '<h1>你好</h1>' > demo.html weasyprint demo.html demo.pdf

第一行安装包及全部依赖，第二行生成一个最小 HTML 文件，第三行调用命令行入口。运行完你会在当前目录看到一个单页 PDF，打开它是排好版的标题，HTML 到 PDF 的完整链路已经跑通。Windows 下把 echo 一行换成手动新建 demo.html 文件即可，其余两行不变。

📋 按任务拆解用法

生成带页码页眉的报告 PDF

报告需要在页眉显示页码时，用 @page 规则把计数器放进页边距盒，每页都会自动排版：

from weasyprint import HTML html = '''<style>@page{@top-center{content:counter(page) " / " counter(pages)}}</style><p>正文</p>''' HTML(string=html).write_pdf('report.pdf')

同样规则也可写入样式表，配合命令行的 -s 参数使用；更多 PDF 分页控制属性可看 docs/going_further.rst。

批量转换目录下的 HTML 文件

批量任务在 Python 里循环文件、复用同一进程，避免反复启动解释器的开销：

from pathlib import Path from weasyprint import HTML out = Path('out'); out.mkdir(exist_ok=True) for f in Path('input').glob('*.html'): HTML(filename=str(f)).write_pdf(out / f'{f.stem}.pdf')

write_pdf 支持的全部参数可继续看 docs/api_reference.rst。

只导出长文档的部分页面

先 render() 拿到 Document 而不落盘，再用 copy() 切出页码区间，无需重新排版：

doc = HTML('long.html').render() doc.copy(doc.pages[2:5]).write_pdf('excerpt.pdf')

Document.copy 的完整用法示例可看 weasyprint/document.py。

⚠️ 调优与避坑

中文字体渲染为方块

症状：导出的 PDF 里中文全是方框。原因：系统缺少中文字体，Pango 找不到字形就回退成空框。修复：sudo apt install fonts-noto-cjk（Debian/Ubuntu）后重新导出。

相对路径的图片与字体静默丢失

症状：HTML 里图片空白，@font-face 回退到默认字体。原因：相对 URL 基于不存在的基准目录解析。修复：构造 HTML 时传入 base_url，命令行则加 -u 参数。

嵌入图片让 PDF 过大

症状：几页的文档体积达到几十兆。原因：源图按原始分辨率全量嵌入。修复：加 -D 150 限制嵌入分辨率，或用 --optimize-images 无损重压缩。

📚 继续深入

• 官方文档：适合想系统了解安装、页面模型和全部渲染参数的人。
• 测试用例：适合想看分页控制、脚注、渐变这些特性具体怎么写 CSS 的人。
• 核心源码：适合想研究 CSS 布局引擎实现或修 bug 的人。

【免费下载链接】WeasyPrintThe awesome document factory项目地址: https://gitcode.com/gh_mirrors/we/WeasyPrint