AWS EC2 Linux无头服务器上wkhtmltopdf生成PDF失败求助

命令行能正常跑但Python代码不行，这种情况我之前也碰到过，大概率是路径、权限或者调用方式的细节没处理好，咱们一步步排查：

1. 先确认Python的调用方式（重点看路径和参数） #

你只贴了CSS路径的代码，没放实际调用wkhtmltopdf的部分，我给你补全两种常见的调用方式，重点注意绝对路径的使用：

如果用subprocess直接调用 #

import subprocess
import os
import pathlib

# 替换成你实际的路径
css_dir = "/home/ec2-user/your-project/css"
html_path = "/home/ec2-user/your-project/report.html"
output_pdf = "/home/ec2-user/your-project/output.pdf"

# 转成绝对路径，避免子进程工作目录不一致导致找不到文件
report_css = pathlib.Path(os.path.join(css_dir, 'report.css')).resolve()
w3_css = pathlib.Path(os.path.join(css_dir, 'w3.css')).resolve()

# 组装命令，注意要启用本地文件访问（否则读不到本地PNG和CSS）
cmd = [
    "wkhtmltopdf",
    "--enable-local-file-access",
    "--user-style-sheet", str(report_css),
    "--user-style-sheet", str(w3_css),
    html_path,
    output_pdf
]

try:
    # 捕获输出方便排查错误
    result = subprocess.run(cmd, check=True, capture_output=True, text=True)
    print("PDF转换成功！")
except subprocess.CalledProcessError as e:
    print(f"转换失败，错误详情：\n{e.stderr}")

如果用pdfkit第三方库调用 #

要是你用的是pdfkit，得注意配置项的格式，尤其是布尔选项和多CSS文件的写法：

import pdfkit
import os
import pathlib

css_dir = "/home/ec2-user/your-project/css"
html_path = "/home/ec2-user/your-project/report.html"
output_pdf = "/home/ec2-user/your-project/output.pdf"

report_css = pathlib.Path(os.path.join(css_dir, 'report.css')).resolve()
w3_css = pathlib.Path(os.path.join(css_dir, 'w3.css')).resolve()

options = {
    'page-size': 'A4',
    'enable-local-file-access': None,  # 布尔选项要设为None，pdfkit会转成正确的命令行参数
    'user-style-sheet': [str(report_css), str(w3_css)]  # 多个CSS文件放列表里
}

try:
    pdfkit.from_file(html_path, output_pdf, options=options)
    print("PDF转换成功！")
except Exception as e:
    print(f"转换失败：{str(e)}")

2. 检查HTML里的图片路径 #

你用matplotlib生成的PNG是本地文件，HTML里的<img>标签必须用绝对路径，比如<img src="/home/ec2-user/your-project/plots/figure1.png">，不能用相对路径（比如./plots/figure1.png），否则wkhtmltopdf在子进程里找不到图片。

3. 权限问题别忽略 #

AWS EC2上运行Python脚本的用户（比如ec2-user）必须有读取CSS、PNG和HTML文件的权限。如果文件是root用户创建的，记得给文件加读权限：

chmod +r /path/to/your/css/*.css
chmod +r /path/to/your/plots/*.png

4. 一定要看错误日志 #

不管用哪种方式调用，一定要捕获并打印错误输出！命令行能跑但Python不行，90%的情况是某个参数没传对或者路径写错了，错误日志会直接告诉你问题所在（比如“找不到report.css”“无法加载本地图片”）。

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