使用pdfkit转换HTML为PDF时无报错生成空文件的问题求助

核心问题定位 #

出现「页数和预期一致但无任何文本内容」的表现，不是路径配置错误，本质是渲染引擎完成了布局计算（所以能识别到正确分页数量）但文本层绘制失败，常见诱因包括wkhtmltopdf版本兼容bug、本地资源加载失败、编码不匹配、CSS特性兼容差。

分步修复方案 #

1. 修复底层渲染环境问题 #

注意：不要使用Ubuntu 16.04默认apt源提供的0.12.2.4版本wkhtmltopdf，该版本存在未修复的文本渲染缺陷，显式指定执行路径也无法解决问题

• 先执行命令卸载现有故障版本：sudo apt remove -y wkhtmltopdf
• 安装官方编译的0.12.6稳定静态版本（适配Ubuntu16.04），不要使用系统源内置的旧版本
• 安装完成后执行which wkhtmltopdf查询可执行文件的实际路径，后续代码配置中填写该路径即可

2. 最小化验证排除文件问题 #

新建最简单的测试HTML文件，仅写入基础文本内容，用现有转码逻辑生成PDF：

• 如果测试文件依然输出空白，说明wkhtmltopdf安装未成功，重新检查安装步骤
• 如果测试文件能正常显示文字，说明环境运行正常，问题出在目标HTML文件的适配性上

3. 调整转码参数适配目标HTML #

修改转码代码，补充必要参数解决资源加载、编码、JS阻断类问题，参考代码：

import pdfkit

# 替换成上一步which wkhtmltopdf查询到的实际路径
wkhtml_path = "/usr/local/bin/wkhtmltopdf"
config = pdfkit.configuration(wkhtmltopdf=wkhtml_path)
trans_options = {
    'enable-local-file-access': None,  # 允许读取本地CSS、图片、字体等资源
    'disable-javascript': None, # 页面JS运行报错会阻断文本绘制，可先禁用测试
    'encoding': "UTF-8", # 强制指定UTF-8编码，避免编码识别失败导致文本空白
    'disable-smart-shrinking': None, # 关闭智能缩放，避免缩放参数异常导致文本透明
}
pdfkit.from_file(
    'income_contract_01.html', 
    'res_fixed.pdf', 
    configuration=config, 
    options=trans_options
)

同时检查目标HTML文件：

• 将所有CSS、图片、字体的相对路径全部替换为系统绝对路径，避免程序运行工作目录不对导致资源加载失败
• 如果页面使用了flex、grid等较新的CSS布局，0.12版本的wkhtmltopdf对这类特性兼容度极差，要么改成传统块级+浮动布局，要么直接更换渲染引擎

4. 兜底实现方案 #

如果以上调整后依然存在渲染问题，不用继续调试wkhtmltopdf，直接换基于Chrome内核的渲染工具，渲染效果和浏览器打开的页面完全一致，不会出现布局正确但内容空白的问题，参考实现：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    # 替换成你的HTML文件的系统绝对路径，前面加file://前缀
    page.goto('file:///你的HTML文件全路径/income_contract_01.html')
    page.pdf(path='final_res.pdf')
    browser.close()

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