Wicked PDF gem本地正常部署后字体异常问题求助

你遇到的这个问题我之前也碰过，大概率是服务器环境缺少默认字体或者CSS里没有明确指定可嵌入的字体导致的。毕竟本地开发环境通常有完整的字体库，但生产服务器（尤其是轻量的Linux镜像）往往只预装了极少的字体，wkhtmltopdf找不到指定字体时就会 fallback 到系统最基础的Cursor Font。

下面给你几个具体的排查和解决方向：

1. 在CSS里强制指定带嵌入的字体 #

这是最稳妥的方案，确保PDF渲染时能拿到正确的字体文件，不依赖系统字体。

• 把需要的字体文件（比如Arial、Roboto这类通用字体）放到Rails的app/assets/fonts目录下
• 在pdf.css.scss里用@font-face声明字体，并且给所有文本元素指定字体：

@font-face {
  font-family: 'Arial';
  src: url(wicked_pdf_asset_path('arial.ttf')) format('truetype');
  font-weight: normal;
  font-style: normal;
}

body, p, div, span {
  font-family: 'Arial', sans-serif !important;
  font-size: 14px;
}

注意：要用wicked_pdf_asset_path来引用字体文件，确保编译后路径正确，而且字体文件要加入预编译列表（在config/initializers/assets.rb里加Rails.application.config.assets.precompile += %w( arial.ttf )）

2. 检查服务器环境的字体安装情况 #

如果不想嵌入字体，可以给服务器安装常用的系统字体包：

• 对于Debian/Ubuntu系统，安装字体包：

sudo apt-get install fonts-dejavu-core fonts-liberation

• 对于CentOS/RHEL：

sudo yum install dejavu-sans-fonts liberation-sans-fonts

安装完后重启一下应用服务器，让wkhtmltopdf能识别到新安装的字体。

3. 确认wkhtmltopdf的资源加载是否正常 #

虽然你已经用了wicked_pdf_asset_base64，但还是要确认CSS是否真的被正确加载到PDF里：

• 可以把生成的PDF保存下来，用PDF阅读器查看「文档属性-字体」，看看实际使用的是什么字体，如果显示的是「Cursor」或者系统默认的未知字体，说明CSS没生效
• 尝试在CSS里加一些明显的样式（比如红色背景），看PDF里是否能显示，验证CSS是否被正确应用

4. 调整wkhtmltopdf的渲染参数 #

在生成PDF的代码里，可以添加一些字体相关的参数，强制wkhtmltopdf使用指定字体：

respond_to do |format|
  format.pdf do
    render pdf: "document",
           encoding: 'UTF-8',
           wkhtmltopdf: WickedPdf.new.pdf_from_string(
             render_to_string,
             disable_smart_shrinking: true,
             no_embed_fonts: false,
             default_font: 'Arial'
           )
  end
end

注意default_font参数要对应服务器上已安装的字体名称，或者你在CSS里声明的字体名

5. 排查预编译和资源路径问题 #

确保所有CSS、字体文件都被正确预编译：

• 部署时运行RAILS_ENV=production rake assets:precompile，检查public/assets目录下是否有生成的pdf.css和字体文件
• 避免在CSS里使用相对路径，全部用wicked_pdf_asset_path或者wicked_pdf_asset_base64来引用资源

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