wkhtmltopdf在开发与生产环境生成文档不一致问题排查

1. 资产管线（Asset Pipeline）环境差异 #

本地开发模式下Rails实时编译资产，CSS路径解析完全正常；但远程开发/生产环境可能开启了资产预编译、压缩或CDN配置，导致：

• 远程开发环境可能未正确预编译PDF专用CSS，或asset_host配置导致背景样式路径无法被wkhtmltopdf抓取
• 生产环境的CSS压缩工具（如Sprockets）可能误删文本相关样式规则，或路径匹配错误导致样式未加载

2. wkhtmltopdf版本不一致 #

Wicked PDF依赖wkhtmltopdf渲染PDF，不同环境安装的版本差异会导致CSS支持度不同：

• 旧版本可能不支持background等CSS属性（对应远程开发无背景）
• 部分版本对文本颜色、字体的渲染存在兼容性问题（对应生产环境无文本）

3. CSS路径解析问题 #

即使使用静态无指纹文件，不同环境的域名、资产路径配置不同，可能导致wkhtmltopdf无法正确加载CSS：

• 相对路径在服务器环境下被解析为错误地址，导致部分样式失效
• 独立服务器的CSS文件可能存在跨域或权限问题，wkhtmltopdf默认可能拒绝加载外部资源

• 输出渲染前的HTML：在生成PDF的Controller中临时替换代码为render html: render_to_string(layout: 'pdf', template: 'your_template')，在对应环境打开该页面，检查CSS是否加载成功、样式是否生效，排除HTML/CSS本身的问题
• 启用调试日志：在config/initializers/wicked_pdf.rb中添加配置：

  WickedPdf.config = {
    debug: true,
    log_level: :debug
  }
  

  查看服务器日志中wkhtmltopdf的执行命令和错误信息，定位资源加载失败的问题
• 直接使用wkhtmltopdf命令测试：将测试HTML保存为文件，在目标环境服务器上执行：

  wkhtmltopdf input.html output.pdf
  

  对比结果，排查是Rails配置问题还是wkhtmltopdf本身的兼容性问题
• 统一wkhtmltopdf版本：在所有环境安装相同版本的wkhtmltopdf（推荐稳定版0.12.6+），避免版本差异导致的渲染不一致
• 简化CSS测试：先使用极简CSS（如仅设置body { background: #ccc; color: #000; }）验证三个环境的渲染结果，逐步添加原有样式，定位到导致问题的具体规则
• 强制使用绝对路径：在布局文件中直接使用完整HTTP路径引用CSS，比如：

  <%= wicked_pdf_stylesheet_link_tag 'http://your-domain.com/assets/zapp_pdf.css' %>
  

  确保wkhtmltopdf能直接抓取到CSS资源

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