在AWS Lambda中用Python将HTML转PDF触发OSError报错

问题根源 #

QPainter::begin(): Returned false 错误的核心原因是：wkhtmltopdf依赖图形渲染上下文，但AWS Lambda运行在无图形界面（headless）的环境中，缺少X11显示服务，导致无法初始化绘图组件。本地Docker测试正常是因为你的容器包含了必要的图形依赖或虚拟显示环境。

解决方案 #

1. 补充headless运行依赖 #

Lambda的Amazon Linux 2环境默认没有xvfb（虚拟X服务器）和相关图形依赖，需要将这些依赖打包到Lambda层或部署包中：

• 在Amazon Linux 2实例（或对应Docker镜像）中安装依赖：

  sudo yum install -y xvfb libX11 libXext libXrender fontconfig
  

• 将安装后的二进制文件（/usr/bin/xvfb-run、/usr/lib64/下的相关库）和兼容的wkhtmltopdf二进制（需针对Amazon Linux 2编译，避免架构/系统不兼容）打包成zip，作为Lambda层上传。

2. 修改代码调用方式 #

在代码中通过xvfb-run启动wkhtmltopdf，为其提供虚拟显示环境：

• 方法一：修改pdfkit配置，将执行命令改为带xvfb-run的形式：

  # 替换原config行
  config = pdfkit.configuration(wkhtmltopdf='xvfb-run /usr/local/bin/wkhtmltopdf')
  

• 方法二：用subprocess手动执行命令（更灵活）：

  import subprocess
  
  # 渲染HTML后执行以下命令
  cmd = [
      'xvfb-run',
      '/usr/local/bin/wkhtmltopdf',
      '--enable-local-file-access',
      '/tmp/w.html',
      '/tmp/out.pdf'
  ]
  result = subprocess.run(cmd, capture_output=True, text=True)
  if result.returncode != 0:
      raise Exception(f"wkhtmltopdf执行失败: {result.stderr}")
  

3. 验证wkhtmltopdf兼容性 #

确保使用的wkhtmltopdf是针对Amazon Linux 2编译的版本，避免因二进制不兼容导致的隐性错误。不要直接使用本地Docker环境中的二进制（可能基于Ubuntu/Debian，与Amazon Linux 2依赖不匹配）。

4. 检查权限与路径 #

• 确认wkhtmltopdf二进制文件有执行权限（打包时添加chmod +x操作）。
• Lambda中仅/tmp目录可读写，确保生成的HTML和PDF文件都放在/tmp下（你的代码中已满足此要求）。

额外提示 #

如果使用Lambda层，需确保层的兼容架构为x86_64（对应Python3.8的Lambda运行环境），避免arm架构的依赖包无法运行。

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