WeasyPrint 实战指南：一条命令把 HTML 变成排版精准的 PDF-开发者社区

WeasyPrint 实战指南：一条命令把 HTML 变成排版精准的 PDF

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

如果你需要把 HTML 网页、模板化的报告或存档页面输出成 PDF，WeasyPrint 是一个值得优先考虑的方案。它是一个纯 Python 的 HTML 转 PDF 转换库，不依赖浏览器内核，而是通过 Pango 完成文本渲染，因此输出结果在不同机器上保持一致。这篇指南面向刚接触它的开发和运营同学，从安装、命令行动手，讲到中文字体、自定义字体和批量处理中的几个高频坑。

安装 WeasyPrint 之前要注意什么

WeasyPrint 本身用 pip 装，但它依赖系统级的 Pango 文本渲染库，这一步经常被忽略，导致装完跑不起来。

Linux（Ubuntu/Debian）：可以直接走发行版包管理器：
```
sudo apt install weasyprint
```
Windows / macOS：在 Python 环境里执行pip install weasyprint即可（macOS 也可以用 Homebrew：brew install weasyprint）。
建议装在虚拟环境里，避免和系统 Python 的依赖打架：
```
python3 -m venv venv source venv/bin/activate pip install weasyprint
```

装完后跑一下weasyprint --info，它会打印系统、Pango 和 WeasyPrint 各自的版本，能直接确认依赖链是否完整。以后排查渲染问题，这也是第一个该看的命令。

一条命令完成 HTML 转 PDF

命令行是最快的上手方式，语法就是"输入在前，输出在后"：

weasyprint input.html output.pdf

输入既可以是本地文件，也可以是 URL，适合直接做网页存档。如果想在转换时叠加一份自己的样式表，可以加-s参数指向 CSS 文件。

日常使用中还有几个参数值得记住：-m指定媒体类型（默认 print）、-e强制指定输入编码（老文件里遇到乱码时很有用）、-D限制嵌入图片的分辨率以控制 PDF 体积。完整参数清单可以用--help查看，官方文档里的 manpage.rst 也有逐项说明。

用 Python API 获得更细的控制

当转换逻辑要嵌进业务代码时，用 Python API 更合适。核心入口是HTML类，两个最常用的方法：

from weasyprint import HTML # 从 URL 或本地文件生成 HTML('https://example.com').write_pdf('web_page.pdf') # 从 HTML 字符串生成 HTML(string='<h1>我的文档</h1><p>正文内容</p>').write_pdf('report.pdf')

write_pdf适合一步到位直接出文件；如果需要先拿到文档对象再处理，就调render()，它会返回一个Document，上面有pages列表和write_pdf()等方法。API 细节可以看 api_reference.rst。

中文和自定义字体怎么配

中文字体不生效是最常见的问题，原因基本就两类：系统里没装对应字体，或者没在 CSS 里正确声明字体族。解决思路：

先确认系统已安装支持中文的字体，CSS 的font-family里写明该字体族名；
如果要用私有字体文件，用@font-face规则显式声明，并通过FontConfiguration对象让 WeasyPrint 感知它：

from weasyprint import CSS, HTML from weasyprint.text.fonts import FontConfiguration font_config = FontConfiguration() css = CSS(string=''' @font-face { font-family: MyFont; src: url(fonts/myfont.ttf); } ''', font_config=font_config)

注意FontConfiguration需要传给所有作用于同一文档的CSS对象，字体声明才会生效。字体相关的渲染逻辑集中在 weasyprint/text/fonts.py，想理解加载机制可以读一下。

提取页面子集

render()返回的Document支持按页切片。比如只导出第 2 到第 3 页（Python 切片从 0 开始计数）：

document = HTML('input.html').render() document.copy(document.pages[1:3]).write_pdf('subset.pdf')

这个能力在"同一份长报告按章节拆给不同部门"的场景里很好用。

批量转换的性能建议

如果你的任务是月末批量导出几十上百份报告，别为每个文件起一次新进程。更稳的做法是：

让 Python 进程长期运行，循环调用write_pdf；
复用同一个FontConfiguration实例，避免每份文档都重新解析一遍字体；
大批量时留意图片体积，必要时用-D（命令行）限制嵌入分辨率。

下一步建议

想深入 CSS 支持范围，读一遍 docs/ 下的 first_steps 和 going_further；
想理解布局是怎么算的，看 weasyprint/layout/ 里的模块；
上手时先跑通weasyprint --info，再跑一条最小转换命令，字体和分页问题按本文顺序排查，基本能覆盖 90% 的初始化场景。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

WeasyPrint 实战指南：一条命令把 HTML 变成排版精准的 PDF