在 Web 开发与自动化办公场景中，将 HTML 内容转换为 PDF 是一种常见的文档处理需求。PDF 格式在不同平台和设备上能保持稳定的排版效果，适合用于生成报表、归档页面或制作离线文档。Python 生态中提供了多种实现方案，本文以 Spire.Doc for Python 为例，记录其在实际使用中的基本用法与需要注意的问题。
为什么需要 HTML 转 PDF
HTML 作为网页的标准标记语言，擅长描述内容的结构与样式，但其最终呈现效果依赖于浏览器和设备的渲染差异。当需要将网页内容作为正式文档分发或存档时，PDF 的固定布局特性更具优势。通过 Python 脚本实现转换，可以将这一过程自动化，避免手动操作的繁琐与不一致。
安装 Spire.Doc for Python
开始之前，需要通过 pip 安装该库：
bash
pip install Spire.Doc安装完成后，可以在 Python 脚本中导入相关模块。该库的核心类包括 Document（文档对象）、FileFormat（文件格式枚举）以及 XHTMLValidationType（HTML 验证选项）。
从 HTML 文件转换为 PDF
如果手头已有现成的 HTML 文件，转换过程相当直接。核心思路是：先加载 HTML 文件到一个 Document 对象中，再将其另存为 PDF 格式。
python
from spire.doc import *
from spire.doc.common import *
doc = Document()
doc.LoadFromFile("input.html", FileFormat.Html, XHTMLValidationType.none)
doc.SaveToFile("output.pdf", FileFormat.PDF)
doc.Close()这里需要注意 LoadFromFile 方法的第三个参数 XHTMLValidationType.none，它表示不进行严格的 XHTML 验证。由于实际项目中的 HTML 代码往往不够规范，使用 none 可以避免因验证失败而导致的加载错误。
这种方法适合处理静态 HTML 文件，例如已保存的网页、自动生成的报告模板等。
从 HTML 字符串转换为 PDF
更灵活的场景是处理动态生成的 HTML 字符串，比如从数据库查询结果拼接出的内容。这种情况下，无法先保存为文件再加载，而是需要直接将字符串渲染到文档中。
Spire.Doc 提供了 Paragraph.AppendHTML() 方法，可以将 HTML 片段插入到段落中并解析其样式。下面是一个包含标题、段落和表格的示例：
python
from spire.doc import *
from spire.doc.common import *
doc = Document()
section = doc.AddSection()
paragraph = section.AddParagraph()
html_string = """
<h1>旅游统计报表</h1>
<p>以下是<strong>2025年度</strong>的统计数据。</p>
<table>
<tr><th>国家</th><th>收入（亿美元）</th></tr>
<tr><td>法国</td><td>79.5</td></tr>
<tr><td>美国</td><td>76.9</td></tr>
</table>
"""
paragraph.AppendHTML(html_string)
doc.SaveToFile("output.pdf", FileFormat.PDF)
doc.Close()这段代码展示了几个要点：AddSection() 创建文档节，AddParagraph() 添加段落，而 AppendHTML() 负责解析 HTML 字符串。示例中的 HTML 包含一个简单的表格结构，AppendHTML() 能够识别 <table>、<tr>、<th>、<td> 等标签并将其渲染为 PDF 中的表格。
这种方式适合接口返回 HTML 片段后直接生成 PDF 的场景，省去了中间文件的操作。例如后端服务接收到前端提交的表单数据后，拼接成 HTML 片段再转换为 PDF 返回给用户下载。
实际使用中的注意事项
在实际测试中，有几个问题值得留意。
大文件的性能问题。尝试转换一个包含约 10 万行表格的 HTML 文件（超过 130MB），生成 PDF 的耗时较长。可以将大文件拆分为多个较小的 HTML 文件分别转换后再合并。对于表格数据量大的场景，这一限制需要纳入考量。
样式与渲染的差异。HTML 的流式布局与 PDF 的固定布局存在本质差异。复杂的 Flexbox 或 Grid 布局、CSS3 动画等特性在转换后可能出现偏差。较新的版本已修复了部分 HTML 转 PDF 时内容丢失的问题，但使用前建议先做小规模测试。
表格处理的细节 。虽然 AppendHTML() 能解析表格标签，但对于合并单元格、嵌套表格等复杂结构，渲染结果可能与浏览器中的显示存在差异。示例中的简单表格通常没有问题，但复杂表格建议实际验证。
免费版的限制。Spire.Doc 的免费版本会在生成的 PDF 中添加 warning 水印，且有页数或功能上的限制。如果用于正式项目，需要评估这一限制是否可接受。
进阶配置
除了基础的转换，Spire.Doc 允许在转换前调整页面设置。通过 Section.PageSetup 可以设置页边距、纸张大小等参数：
python
section.PageSetup.Margins.Top = 50.0
section.PageSetup.Margins.Bottom = 50.0
section.PageSetup.Margins.Left = 40.0
section.PageSetup.Margins.Right = 40.0这些配置在生成正式文档时较为实用，比如为报表预留装订边距或调整页面方向以适应宽表格。
小结
本文围绕 Python 中 HTML 转 PDF 的实现，以 Spire.Doc for Python 为例，介绍了从 HTML 文件和 HTML 字符串两种输入形式完成转换的基本流程。该库通过文档对象模型解析 HTML 内容，对标题、段落、表格等常见元素有基本的支持。实际使用中，复杂样式、大文件以及免费版的限制都可能影响转换效果，建议根据具体项目需求评估是否适用。如果只是简单的 HTML 页面归档，少量代码即可完成转换；若涉及大量数据或高保真样式要求，可能需要结合拆分策略或考虑其他方案。