如何在Heroku上使Flask应用中的WKHTMLTOPDF正常运行？

我之前在Heroku部署Flask应用生成PDF的时候也碰到过几乎一模一样的坑——本地跑完全正常，一上Heroku就报500，折腾了好一阵才搞定，给你几个关键的调试和修复步骤：

1. 先看Heroku的详细错误日志 #

别只盯着页面上的“Internal Server Error”提示，赶紧去看Heroku的详细日志，这是定位问题的关键。你可以用命令行：

heroku logs --tail

我当时就是在日志里看到“wkhtmltopdf: error while loading shared libraries: libXrender.so.1: cannot open shared object file”，才发现是系统依赖没装。

2. 添加WKHTMLTOPDF专属的Heroku构建包 #

Heroku的Python运行环境默认没有wkhtmltopdf需要的底层系统依赖（比如libXrender、libXext这些图形相关库），必须添加专门的构建包来补上：

• 打开你的Heroku应用设置页面，找到Buildpacks板块
• 点击“Add buildpack”，添加官方维护的wkhtmltopdf构建包（你可以在Heroku的构建包市场里搜索到它）
• 一定要注意顺序：把Python构建包放在第一个，wkhtmltopdf构建包排在后面，不然依赖安装会出问题

或者用命令行添加（记得调整构建包的顺序）：

heroku buildpacks:add --index 2 <wkhtmltopdf构建包地址>

（注：如果找不到地址，直接在Heroku构建包市场搜“wkhtmltopdf”就能拿到官方的那个）

3. 修正pdfkit的配置代码 #

你当前用subprocess找wkhtmltopdf路径的方式在Heroku环境下不稳定，而且那个wkhtmltopdf-pack包其实可以不用（构建包已经帮我们把wkhtmltopdf装到系统路径里了）。修改你的配置函数：

def _get_pdfkit_config():
    if platform.system() == 'Windows':
        # 注意Windows路径的反斜杠要转义，不然会被当成转义字符
        return pdfkit.configuration(wkhtmltopdf=os.environ.get('WKHTMLTOPDF_BINARY', 'C:\\Program Files\\wkhtmltopdf\\bin\\wkhtmltopdf.exe'))
    else:
        # Heroku上构建包会把wkhtmltopdf放到/usr/local/bin目录下
        wkhtmltopdf_path = os.environ.get('WKHTMLTOPDF_BINARY', '/usr/local/bin/wkhtmltopdf')
        return pdfkit.configuration(wkhtmltopdf=wkhtmltopdf_path)

另外提醒下：你原来的Windows路径写的是C:\Program Files，这里的反斜杠没转义，本地其实也有隐患，赶紧改成双反斜杠。

4. 调整requirements.txt #

把git+git://github.com/johnfraney/wkhtmltopdf-pack.git这一行删掉，因为我们用Heroku构建包来安装wkhtmltopdf，不需要这个Python包了。你的requirements.txt只需要保留：

pdfkit==0.6.1
# 加上你用的Flask版本，比如Flask==2.0.1
# 其他你的应用依赖包...

5. 排查模板渲染和变量问题 #

有时候500错误根本不是wkhtmltopdf的锅，而是模板渲染失败——比如aaa或者ag_number这些变量在生产环境下没有正确赋值，导致渲染report2.html时报错。你可以先加个测试路由验证：

@app.route('/test-render')
def test_render():
    credit_hours = aaa['Credit Hours']
    rendered = render_template("report2.html", credit_hours=credit_hours)
    return rendered

如果这个路由能正常返回HTML，那问题就出在pdfkit/wkhtmltopdf部分；如果不行，先把变量初始化的问题解决掉。

最后，重新部署 #

改完所有配置后，重新push代码到Heroku：

git add .
git commit -m "Fix wkhtmltopdf on Heroku deployment"
git push heroku main

按照这些步骤来，应该就能解决你的500错误了——我当时就是靠添加构建包和修正路径搞定的。

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