Ubuntu与wkhtmltopdf报错求助：无法连接X显示、非零代码1退出

我之前在Ubuntu服务器部署服务时正好碰到过一模一样的问题，这本质是因为wkhtmltopdf依赖X11显示环境，但无桌面的Ubuntu系统（比如服务器版）默认没有启动X Server，导致Qt底层找不到可用的显示设备。下面是几个亲测有效的解决方案：

方案一：安装Xvfb虚拟显示服务器（最推荐） #

这是最通用且轻量的解决方式，Xvfb可以在无物理显示器的情况下创建虚拟X11显示环境：

• 首先更新包列表并安装Xvfb：

  sudo apt update && sudo apt install xvfb
  

• 直接用Xvfb包裹wkhtmltopdf命令运行：

  xvfb-run -a wkhtmltopdf input.html output.pdf
  

  其中-a参数会自动寻找可用的虚拟显示端口，避免冲突。
• 如果想每次运行都不用手动加xvfb-run，可以设置bash永久别名：

  echo 'alias wkhtmltopdf="xvfb-run -a wkhtmltopdf"' >> ~/.bashrc
  source ~/.bashrc
  

  之后直接敲wkhtmltopdf命令就会自动使用虚拟显示环境了。

方案二：手动配置显示环境变量 #

如果不想安装额外软件，可以手动设置DISPLAY环境变量并启动临时X Server：

• 先设置DISPLAY端口：

  export DISPLAY=:0
  

• 后台启动Xvfb（如果没安装的话还是得先装）：

  Xvfb :0 -screen 0 1024x768x16 &
  

• 然后正常运行wkhtmltopdf即可。

方案三：修复XDG_RUNTIME_DIR环境变量 #

针对报错里提到的QStandardPaths: XDG_RUNTIME_DIR未设置问题，可以手动指定这个变量：

• 设置并创建对应的目录：

  export XDG_RUNTIME_DIR=/tmp/runtime-$(whoami)
  mkdir -p $XDG_RUNTIME_DIR && chmod 700 $XDG_RUNTIME_DIR
  

• 之后再运行wkhtmltopdf，这个方法适合桌面版Ubuntu偶尔出现环境变量丢失的情况，但服务器版还是推荐方案一。

额外提示 #

如果是使用较新版本的wkhtmltopdf，也可以尝试添加--no-sandbox参数（针对Chrome内核的版本），不过这个参数不一定能解决X显示的问题，还是优先用虚拟显示的方案。

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