将美观的HTML/CSS模板转换为PDF报告的最优方案咨询

方案1：使用WeasyPrint（推荐，专注HTML/CSS转PDF） #

WeasyPrint对CSS Paged Media规范支持完善，能精准保留样式并控制分页，适配动态报告生成场景。

• 安装：

  pip install weasyprint
  

• 核心实现步骤：

  1. 在HTML模板中通过CSS指定分页规则：

     /* 强制在目标元素前分页 */
     .page-break {
         page-break-before: always;
         margin-top: 0; /* 避免分页后出现多余空白边距 */
     }
     
     /* 自定义PDF页面参数 */
     @page {
         size: A4;
         margin: 2cm;
     }
     

     只需在需要分页的位置添加class="page-break"即可生效。

  2. 动态生成HTML后调用WeasyPrint转换：

     from weasyprint import HTML
     
     # dynamic_html为你从数据库生成的完整HTML字符串
     dynamic_html = """
     <html>
         <head>
             <style>/* 你的完整CSS样式代码 */</style>
         </head>
         <body>
             <!-- 第一页报告内容 -->
             <div class="page-break"></div>
             <!-- 第二页报告内容 -->
         </body>
     </html>
     """
     
     # 生成PDF文件
     HTML(string=dynamic_html).write_pdf("report.pdf")
     

• 优势：无需依赖浏览器，纯Python生态，原生支持打印样式（分页、页眉页脚），样式还原度高。

方案2：使用Pyppeteer（依赖无头Chrome，适配复杂现代CSS） #

如果模板用到flex、grid等复杂现代CSS，Pyppeteer调用无头Chrome渲染能完美还原样式——Chrome的渲染引擎对CSS支持最全面。

• 安装：

  pip install pyppeteer
  

• 核心实现步骤：

  1. 同样在HTML中加入分页CSS（与WeasyPrint规则一致）。
  2. Python代码调用无头Chrome生成PDF：

     import asyncio
     from pyppeteer import launch
     
     async def generate_pdf():
         browser = await launch(headless=True)
         page = await browser.newPage()
         # 传入动态生成的HTML字符串
         await page.setContent(dynamic_html)
         # 配置PDF参数并生成文件
         await page.pdf({
             'path': 'report.pdf',
             'format': 'A4',
             'margin': {'top': '2cm', 'right': '2cm', 'bottom': '2cm', 'left': '2cm'},
             'printBackground': True  # 必须开启，否则背景样式丢失
         })
         await browser.close()
     
     asyncio.run(generate_pdf())
     

• 优势：完全复刻Chrome浏览器的渲染效果，解决复杂CSS兼容性问题，同时支持JavaScript动态生成的内容。

关键注意事项 #

• 样式嵌入：尽量将CSS内联到HTML的<style>标签中，避免使用外部CSS文件，防止路径问题或加载失败。
• 字体处理：若使用非系统默认字体，需在CSS中通过@font-face嵌入字体文件（确保文件路径正确），避免PDF中字体缺失。
• 调试技巧：先在Chrome浏览器中预览动态生成的HTML，确认样式正常后再转PDF，减少排查成本。

内容的提问来源于stack exchange，提问作者Christian Papathanasiou