Django项目中解决xhtml2pdf生成大PDF空白问题

1. 精简HTML内容，降低解析负担 #

• 移除HTML中冗余的空标签、重复样式定义、非必要嵌套结构，尤其是表格内的多余div/span标签，减少xhtml2pdf的解析压力。
• 替换或删除xhtml2pdf不兼容的CSS属性（如position: fixed、复杂渐变、部分flex布局），这类属性可能导致渲染中断，最终生成空白PDF。
• 对表格使用极简结构，避免过度样式嵌套，优先使用原生表格样式而非多层容器模拟。

2. 调整xhtml2pdf渲染参数 #

修改生成PDF的代码，启用流式渲染、增加错误排查机制，避免一次性加载全部内容到内存：

from xhtml2pdf import pisa
from io import BytesIO
from django.http import HttpResponse

def generate_large_pdf(request):
    # 假设已通过模板渲染获取到HTML内容
    html_content = render_large_table_html()
    result = BytesIO()
    
    # 配置渲染参数，优化大文档处理
    pisa_status = pisa.CreatePDF(
        html_content,
        dest=result,
        encoding='UTF-8',
        show_error_as_pdf=True,  # 渲染出错时生成带错误信息的PDF，方便排查
        default_css=None,  # 使用自定义精简CSS，减少解析耗时
    )
    
    if not pisa_status.err:
        response = HttpResponse(content_type='application/pdf')
        response['Content-Disposition'] = 'attachment; filename="large_report.pdf"'
        response.write(result.getvalue())
        return response
    else:
        return HttpResponse(f"PDF生成错误: {pisa_status.err}", status=500)

3. 分块生成后合并PDF #

如果内容体积过大，可拆分HTML为多个小片段，分别生成PDF后再合并：

from PyPDF2 import PdfMerger
from xhtml2pdf import pisa
from io import BytesIO
from django.http import HttpResponse

def generate_merged_pdf(request):
    # 将大HTML拆分为多个小片段
    html_fragments = split_large_html_into_chunks()
    merger = PdfMerger()
    
    for fragment in html_fragments:
        fragment_pdf = BytesIO()
        pisa.CreatePDF(fragment, dest=fragment_pdf, encoding='UTF-8')
        fragment_pdf.seek(0)
        merger.append(fragment_pdf)
    
    response = HttpResponse(content_type='application/pdf')
    response['Content-Disposition'] = 'attachment; filename="merged_report.pdf"'
    merger.write(response)
    merger.close()
    return response

4. 调整服务器环境限制 #

• 检查并提升服务器进程的内存限制（如uWSGI的memory-limit、Gunicorn的相关配置），避免进程因内存不足被强制终止，导致生成空白PDF。
• 延长请求超时时间，大PDF生成耗时较长，需修改Nginx的proxy_read_timeout、uWSGI的harakiri等超时配置，防止请求中途被切断。

5. 替换为更高效的PDF生成库 #

xhtml2pdf对大文档的处理效率有限，可考虑替换为：

• WeasyPrint：对现代CSS支持更好，内存管理更优，适合大文档生成，示例代码：

from weasyprint import HTML, CSS
from django.http import HttpResponse

def generate_pdf_with_weasyprint(request):
    html_content = render_large_table_html()
    # 自定义精简CSS
    css = CSS(string='''
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ddd; padding: 8px; }
    ''')
    pdf_bytes = HTML(string=html_content).write_pdf(stylesheets=[css])
    response = HttpResponse(pdf_bytes, content_type='application/pdf')
    response['Content-Disposition'] = 'attachment; filename="large_report.pdf"'
    return response

• 直接使用ReportLab：如果表格结构固定，跳过HTML解析步骤，直接用ReportLab的API生成PDF，彻底避免HTML解析的性能瓶颈。

内容的提问来源于stack exchange，提问作者Tarunya Reddy