PDFKit/WKHTMLTOPDF在AWS服务器上无法设置PDF分辨率问题求助

这种本地正常、AWS环境出问题的渲染差异我碰过好几次，核心原因基本都是wkhtmltopdf的环境依赖缺失或者版本/配置解析差异，给你几个针对性的解决方案：

1. 统一本地与AWS的wkhtmltopdf版本 #

不同版本的wkhtmltopdf对dpi、页面尺寸的解析逻辑可能不一样，先确认两边的版本是否一致：

• 本地执行：wkhtmltopdf --version
• AWS服务器上执行同样的命令对比
  如果版本不同，建议在AWS上安装和本地一致的版本（比如0.12.6，兼容性相对稳定）。

2. 补全AWS服务器的系统依赖 #

AWS的默认服务器环境（比如Amazon Linux、Ubuntu Server）通常会缺少wkhtmltopdf渲染必需的字体和图形依赖，导致内容被异常缩放。根据你的系统类型安装依赖：

针对RHEL/CentOS/Amazon Linux： #

sudo yum install -y libXext libXrender fontconfig dejavu-sans-fonts

针对Debian/Ubuntu： #

sudo apt-get update && sudo apt-get install -y libxext6 libxrender1 fontconfig fonts-dejavu-core

安装后重启应用服务再测试。

3. 调整配置的单位与参数 #

有时候cm单位在AWS环境的解析会有偏差，换成更通用的pt（点）单位，同时配合zoom参数强化dpi设置：

PDFKit.configure do |config|
  config.default_options = {
    encoding: 'UTF-8',
    disable_smart_shrinking: true,
    dpi: 384,
    zoom: 4, # 384dpi是默认96dpi的4倍，强制匹配缩放比例
    page_width: '3308pt', # 84.02cm ≈ 3308pt（1cm=37.795pt）
    page_height: '4677pt', # 118.8cm ≈ 4677pt
    margin_bottom: 0,
    margin_top: 0,
    margin_left: 0,
    margin_right: 0,
    orientation: 'Portrait', # 补充你之前截断的方向配置
    no_background: false, # 确保背景内容正常渲染（如果有）
    quiet: true
  }
  # 如果AWS上wkhtmltopdf不在默认路径，手动指定
  # config.wkhtmltopdf = '/usr/local/bin/wkhtmltopdf'
end

4. 用命令行直接测试，排除代码层问题 #

先绕开Ruby代码，直接在AWS服务器上用wkhtmltopdf命令行生成PDF，验证环境是否正常：

wkhtmltopdf --dpi 384 --page-width 3308pt --page-height 4677pt --disable-smart-shrinking --margin-top 0 --margin-bottom 0 --margin-left 0 --margin-right 0 input.html output.pdf

如果命令行生成的PDF正常，说明是PDFKit的配置没有正确生效；如果还是有问题，那就是环境依赖或版本的问题，回到前两步排查。

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