使用Python的xhtml2pdf库转HTML到PDF时CSS失效问题求解

我之前在项目里用xhtml2pdf转PDF时，也被CSS不生效的问题折腾过好一阵，整理了几个最实用的解决方向，亲测能解决大部分情况：

1. 先确认你的CSS在xhtml2pdf的支持范围内 #

xhtml2pdf基于ReportLab，它只支持CSS2的子集，很多现代CSS特性是不兼容的，这是最常见的坑：

• 别用float属性，改用display: inline-block或者表格布局来实现横向排列
• 垂直方向的margin经常失效，优先用padding代替；盒模型尽量简化
• CSS3特性比如圆角、阴影、渐变、flex布局这些基本不支持，别浪费时间在上面
• 字体要明确指定，比如font-family: Arial, sans-serif，自定义字体需要额外注册（后面会说）

2. 确保CSS正确嵌入到HTML中 #

xhtml2pdf对外部CSS文件的支持很弱，大概率读取不到，所以优先用内联样式或者把CSS内容嵌入到<head>的<style>标签里：

• 如果你的CSS是单独文件，可以用Python代码读取内容，手动插入到HTML里，示例代码：

from xhtml2pdf import pisa

def html_to_pdf(html_path, css_path, output_path):
    # 读取原始HTML
    with open(html_path, "r", encoding="utf-8") as f:
        html_content = f.read()
    
    # 读取CSS内容
    with open(css_path, "r", encoding="utf-8") as f:
        css_content = f.read()
    
    # 把CSS插入到HTML的head标签末尾
    modified_html = html_content.replace("</head>", f"<style type='text/css'>{css_content}</style></head>")
    
    # 生成PDF
    with open(output_path, "wb") as f:
        pisa.CreatePDF(modified_html, dest=f)

3. 检查HTML是否符合严格的XHTML规范 #

xhtml2pdf对HTML的格式要求很严格，不符合规范的话样式也会失效：

• 所有标签必须闭合：比如<br>要写成<br/>，<img src="xxx">要改成<img src="xxx"/>
• 属性值必须用引号包裹：比如class=my-style要改成class="my-style"
• 避免用HTML5新标签：<section>、<article>这些换成<div>，不然可能被忽略

4. 用调试技巧定位问题 #

• 先简化测试：把HTML和CSS砍到最基本的结构（比如一个带样式的div），确认能生效后再逐步添加内容，排除干扰
• 开启日志：调用pisa.showLogging()，查看转换过程中的警告和错误，比如哪些CSS属性不被支持
• 打印转换前的HTML：检查CSS是否真的嵌入正确，有没有语法错误

5. 特殊样式的替代方案 #

• 分页：用<div style="page-break-after: always;"></div>可以强制分页，这个属性是支持的
• 多列布局：别用CSS多列，直接用<table>标签，xhtml2pdf对表格的样式支持很稳定
• 自定义字体：需要先通过ReportLab注册字体，再在CSS中引用，示例：

from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

# 注册自定义字体
pdfmetrics.registerFont(TTFont("MyCustomFont", "./fonts/my-font.ttf"))

然后CSS里写：font-family: "MyCustomFont";

内容的提问来源于stack exchange，提问作者Taimur Islam