使用Python的pdfkit转换含Shopify CSS的HTML为PDF时出现空白页问题

以下是针对你遇到的空白PDF问题的具体解决步骤：

1. 处理外部CSS加载问题 #

Shopify的外部CSS可能因加载延迟或网络问题导致pdfkit提前渲染页面，最终生成空白PDF。

• 添加JavaScript延迟选项，给外部资源足够加载时间：
  在options字典中增加'javascript-delay': '5000'（单位毫秒，可根据实际情况调整）
• 替换外部CSS为本地引用：
  下载Shopify的CSS文件到Django静态目录，修改HTML模板中的CSS链接为本地静态文件路径，避免网络依赖

2. 修复重复的配置项 #

你的代码中重复设置了page-size参数（先Letter后A4），可能引发配置冲突，建议保留一个：

options = {
    'enable-local-file-access': '',
    'orientation': 'landscape',
    'page-size': 'A4',  # 仅保留一个页面尺寸配置
    'margin-top': '0',
    'margin-right': '0',
    'margin-bottom': '0',
    'margin-left': '0',
    'dpi': 96,
    'javascript-delay': '5000'  # 新增延迟配置
}

3. 验证渲染后的HTML内容 #

确认Django模板渲染是否正确，生成PDF前可先输出渲染后的HTML内容：

# 写入临时文件验证
with open('temp_rendered.html', 'w', encoding='utf-8') as f:
    f.write(rendered_content)

打开生成的temp_rendered.html文件，检查是否能正常显示所有内容，排除模板渲染错误。

4. 启用调试模式排查问题 #

添加verbose和debug选项，查看转换过程中的详细日志，定位资源加载或解析错误：

options = {
    # 其他配置...
    'verbose': '',
    'debug': ''
}

查看控制台输出的日志信息，确认是否存在CSS加载失败、JavaScript错误等问题。

5. 升级wkhtmltopdf版本 #

pdfkit依赖wkhtmltopdf执行转换，旧版本对现代CSS支持有限，建议升级到最新稳定版的wkhtmltopdf，提升对复杂样式的兼容性。

内容的提问来源于stack exchange，提问作者karan Dhaliwal