本文详解如何在 Django 项目中利用 pdfkit 将多个 HTML 内容块分别渲染为独立 PDF 页面，核心是通过 CSS 的 page-break-after: always 实现精准分页。
本文详解如何在 django 项目中利用 pdfkit 将多个 html 内容块分别渲染为独立 pdf 页面，核心是通过 css 的 `page-break-after: always` 实现精准分页。
在使用 pdfkit（基于 wkhtmltopdf 的 Python 封装）将 HTML 转换为 PDF 时，若需将多个逻辑内容单元（如报告章节、练习题、示例模块）严格分隔为独立页面，仅拼接 HTML 字符串是不够的——默认情况下所有内容会连续排版，可能跨页或挤在同一页面。真正的解决方案在于控制 PDF 分页行为的 CSS 分页属性。
pdfkit 完全支持标准 CSS 分页规则（需 wkhtmltopdf ≥ 0.12.0），其中最常用且可靠的是：
<div style="page-break-after: always;"></div>
该样式会强制浏览器（及 wkhtmltopdf 渲染引擎）在此元素后插入分页符，确保后续内容始终从新一页开始。
以下是在 Django 项目中的完整实践示例（适配您的原始代码）：
import pdfkit
from django.template.loader import render_to_string
my_contents = [
{'title': 'Example 1', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 2', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 3', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 4', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 5', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
]
final_html = ''
for i, content in enumerate(my_contents):
data = {
'title': content['title'],
'contents': content['contents'],
}
# 渲染每个模块的 HTML 模板
final_html += render_to_string('pdfs/routines_handout.html', data)
# 在除最后一个模块外的所有模块末尾添加分页符
if i '
# 生成 PDF（注意：确保 wkhtmltopdf 已正确安装并可被 pdfkit 找到）
pdfkit.from_string(final_html, 'out.pdf')
✅ 关键注意事项：
-
不要在末尾添加多余分页符：如示例所示，仅在前 N−1 个模块后插入 ，否则 PDF 末尾会出现空白页；
- CSS 作用域安全：page-break-after 是内联样式，无需额外 CSS 文件，兼容性高；
- 替代方案（推荐进阶使用）：也可在模板中直接定义分页规则，例如在 routines_handout.html 底部添加：
{% if not forloop.last %}<div style="page-break-after: always;"></div>{% endif %}这样逻辑更清晰，避免 Python 层拼接 HTML 的脆弱性；
- wkhtmltopdf 配置建议：如遇分页失效，检查是否启用了 --enable-local-file-access（尤其当模板含本地静态资源时），或尝试添加 --page-size A4 --margin-top 20 --margin-bottom 20 等参数提升排版稳定性。
总结：page-break-after: always 是 pdfkit 多页生成中最轻量、最可靠的分页手段。结合 Django 模板系统，可灵活构建结构化、可维护的 PDF 报告流水线——无需复杂布局引擎，一行 CSS 即可掌控每一页的边界。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
