Mac环境下PDFkit搭配wkhtmltopdf运行卡顿问题求助

我之前也碰到过Mac上pdfkit和wkhtmltopdf配合时出现卡顿、加载停滞的情况，结合你提到的「终端手动执行命令正常、Ubuntu下可正常生成」的细节，给你几个针对性的排查和解决方向：

• 指定wkhtmltopdf的绝对路径
  Mac上通过Homebrew安装的wkhtmltopdf路径可能和Ubuntu不同（尤其是M系列芯片的Mac，路径是/opt/homebrew/bin/wkhtmltopdf，Intel芯片是/usr/local/bin/wkhtmltopdf），而pdfkit有时会因为PATH配置差异找不到正确的二进制文件，导致静默卡顿。你可以在代码里明确指定路径：

  PDFKit.configure do |config|
    config.wkhtmltopdf = '/opt/homebrew/bin/wkhtmltopdf' # 根据你的芯片类型调整路径
  end
  

• 开启调试日志定位问题
  把pdfkit和wkhtmltopdf的日志打开，就能看到具体执行时的命令和输出，帮你找到卡顿的根源。在代码里添加：

  require 'pdfkit'
  
  kit = PDFKit.new('<h1>测试内容</h1>', page_size: 'A4')
  kit.stderr = STDERR # 输出wkhtmltopdf的错误信息
  kit.verbose = true # 启用详细日志模式
  pdf = kit.to_pdf
  

  运行后观察终端输出，可能会发现是参数错误、外部资源加载超时或者渲染引擎的问题。

• 检查Mac的安全权限限制
  尤其是M系列芯片的Mac，系统的隐私权限可能会限制wkhtmltopdf的网络访问或文件写入。你可以试试：

  • 把运行代码的IDE（比如VS Code、RubyMine）添加到「系统设置 > 隐私与安全性 > 完全磁盘访问」列表中；
  • 直接在终端里运行你的Ruby脚本，而不是通过IDE启动，避免IDE的权限隔离影响。

• 对齐wkhtmltopdf版本或更新到稳定版
  Mac上brew安装的wkhtmltopdf版本可能和Ubuntu上的不一致，部分旧版本在Mac上存在渲染引擎的bug，导致卡顿。试试更新到最新稳定版：

  brew update
  brew reinstall wkhtmltopdf
  

  如果Ubuntu上用的是特定版本，也可以在Mac上安装对应版本来测试。

• 用极简代码排除干扰
  写一个最基础的测试脚本，排除业务代码或复杂HTML的干扰，确认pdfkit和wkhtmltopdf的基础功能是否正常：

  require 'pdfkit'
  
  PDFKit.configure do |config|
    config.wkhtmltopdf = '/opt/homebrew/bin/wkhtmltopdf' # 替换为你的实际路径
  end
  
  kit = PDFKit.new('<h1>极简测试PDF</h1>')
  kit.to_file('/tmp/test_mac.pdf')
  

  如果这个脚本能成功生成PDF，那问题大概率出在你原来的HTML内容里（比如包含加载缓慢的外部资源、复杂CSS/JS导致渲染阻塞），可以逐步添加内容排查。

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