Ubuntu 16.04下wkhtmltopdf生成PDF无CSS样式问题求助

我帮好几个开发者解决过这个问题——Windows上一切正常，到Ubuntu 16.04就变成黑白无样式的PDF，本质大多是wkhtmltopdf的版本、依赖或者配置问题，咱们一步步排查解决：

• 先换掉老旧的wkhtmltopdf版本
  Ubuntu 16.04默认仓库里的wkhtmltopdf版本太旧，而且缺少Qt渲染引擎的补丁，对CSS颜色、背景、字体的支持极差。先卸载旧版本：

  sudo apt-get remove --purge wkhtmltopdf
  

  然后安装带Qt补丁的稳定版（直接用静态deb包）：

  sudo wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.xenial_amd64.deb
  sudo dpkg -i wkhtmltox_0.12.6-1.xenial_amd64.deb
  

  如果安装时弹出依赖错误，执行下面的命令自动修复：

  sudo apt-get -f install
  

• 把CSS路径改成绝对路径
  Laravel里如果用相对路径引用CSS，wkhtmltopdf在Ubuntu的服务器环境下经常找不到资源。建议用Laravel的public_path()辅助函数生成绝对路径：
  把原来的

  <link rel="stylesheet" href="css/style.css">
  

  改成：

  <link rel="stylesheet" href="{{ public_path('css/style.css') }}">
  

  另外，记得在生成PDF时加上--enable-local-file-access参数，允许wkhtmltopdf读取本地静态文件。如果用的是barryvdh/laravel-wkhtmltopdf包，可以在config/wkhtmltopdf.php里配置：

  'options' => [
      'enable-local-file-access' => true,
      // 其他选项...
  ]
  

• 强制开启CSS背景和渲染选项
  Ubuntu下的wkhtmltopdf默认可能关闭了CSS背景色支持，还有些动态样式需要JS辅助渲染。生成PDF时务必加上这些参数：

  • --enable-css-background：专门开启背景色支持
  • --enable-javascript：启用JS渲染动态样式
  • --javascript-delay 1000：给JS留1秒加载时间（根据页面复杂度调整）
  • --no-stop-slow-scripts：防止因为JS慢而停止渲染

• 补上缺失的字体
  Ubuntu默认没有Windows上的一些常用字体（比如微软雅黑、宋体），也缺少部分中文字体，导致字体样式丢失。安装常用字体包：

  sudo apt-get install fonts-wqy-microhei fonts-wqy-zenhei ttf-mscorefonts-installer
  

  安装完成后更新字体缓存：

  sudo fc-cache -fv
  

  之后在CSS里指定字体时，尽量用系统已安装的字体名称，避免用仅Windows有的字体。

• 用命令行测试静态HTML
  如果以上步骤还没解决，先把要生成PDF的页面保存成静态HTML文件，用wkhtmltopdf命令行直接生成，排除Laravel代码的干扰：

  wkhtmltopdf --enable-css-background --enable-local-file-access test.html output.pdf
  

  如果命令行生成的PDF样式正常，那问题就出在Laravel的配置或代码调用上；如果还是有问题，就再检查wkhtmltopdf的依赖是否安装完整。

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