Wicked PDF样式未生效排查及资产预编译验证咨询

问题背景 #

使用Wicked PDF生成PDF时，已指定pdf.html.erb作为布局（移除该文件会触发缺少布局的错误，确认布局已正确加载），但样式完全不生效。尝试过本地路径和外部可访问的绝对URL引入样式表，结果均一致。

已完成的配置如下：

Gem依赖 #

gem 'wkhtmltopdf-binary', '~> 0.12.6.6'
gem 'wicked_pdf', '~> 2.7'
gem 'mobility', '~> 1.2', '>= 1.2.9'

Wicked PDF初始化器配置 #

WickedPdf.config = {
  exe_path: '/Users/main/.rbenv/shims/wkhtmltopdf'
}

资产预编译配置（assets.rb） #

Rails.application.config.assets.precompile += %w( initialise.css foundation.css zapp.css )

PDF布局文件pdf.html.erb #

<!DOCTYPE html>
<html>
<head>
<title></title>
    <meta charset='utf-8' />
    <%= wicked_pdf_stylesheet_link_tag "initialise" %>
    <%= wicked_pdf_stylesheet_link_tag "foundation" %>
    <%= wicked_pdf_stylesheet_link_tag "zapp" %>
    <%# stylesheet_link_tag wicked_pdf_asset_base64("initialise") %>
    <%# stylesheet_link_tag wicked_pdf_asset_base64("foundation") %>
    <%# stylesheet_link_tag wicked_pdf_asset_base64("zapp") %>
</head>
<body>
    <%= yield %>
</body>
</html>

控制器响应配置 #

respond_to do |format|
  format.html
  format.pdf do
    render pdf: 
      "#{@individual.name_last}_#{@individual.name_first}_t_up",
       layout: 'pdf', 
       encoding: 'utf8'
 end
end

PDF生成链接 #

<%= link_to fa_icon("file-pdf-o", class: 'fa-lg'), t_up_individual_path(@individual, format: :pdf), target: '_pdf' %>

生成的访问路径：href="/individuals/94/t_up.pdf?locale=en"

样式表定义的问题或遗漏点 #

1. 优先使用base64嵌入样式
   wicked_pdf_stylesheet_link_tag生成的相对路径容易被wkhtmltopdf解析失败，尤其是开发环境未预编译资产时。建议启用布局中注释掉的base64嵌入方式，直接将CSS内容编码后嵌入HTML，彻底规避路径问题：

   <%= stylesheet_link_tag wicked_pdf_asset_base64("initialise") %>
   <%= stylesheet_link_tag wicked_pdf_asset_base64("foundation") %>
   <%= stylesheet_link_tag wicked_pdf_asset_base64("zapp") %>
   

2. 开发环境需手动预编译资产
   开发环境默认不会自动预编译资产，若在开发环境测试PDF样式，必须先执行预编译命令：

   rails assets:precompile
   

   否则wicked_pdf_stylesheet_link_tag无法找到编译后的资产文件。

3. 检查wkhtmltopdf的资产访问权限
   确认初始化器中的exe_path指向正确的wkhtmltopdf可执行文件，同时确保该进程有读取Rails资产目录的权限。生产环境中若资产部署到CDN，需确保wkhtmltopdf能访问到CDN资源。

4. 排查CSS兼容性
   wkhtmltopdf基于旧版WebKit内核，部分现代CSS特性（如flexbox、grid高级布局）可能不支持。建议先使用极简CSS（如设置背景色、字体大小）测试是否生效，逐步排查兼容性问题。

5. 添加打印媒体类型配置
   在控制器render配置中指定:media => 'print'，适配wkhtmltopdf的打印渲染模式：

   format.pdf do
     render pdf: "#{@individual.name_last}_#{@individual.name_first}_t_up",
            layout: 'pdf', 
            encoding: 'utf8',
            media: 'print'
   end
   

   同时可在CSS中添加@media print规则，专门针对PDF调整样式。

资产预编译验证方法 #

1. 查看输出目录
   预编译完成后，检查public/assets目录下是否生成了带哈希后缀的目标CSS文件（如initialise-xxxxxx.css），同时确认manifest-<环境>.json文件中存在这些资产的映射记录。

2. 命令行日志验证
   执行预编译命令时，观察输出日志是否有报错：

   rails assets:precompile RAILS_ENV=production
   

   无报错且日志显示已编译指定CSS文件，则预编译成功。

3. 浏览器直接访问
   在浏览器中直接访问资产路径（如开发环境的http://localhost:3000/assets/initialise.css），确认能正常加载CSS内容，说明资产已正确预编译并可访问。

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