ruby:3.0.4-alpine版Docker化Rails应用配置wkhtmltopdf方案咨询

方案1：保留现有Alpine镜像，手动安装兼容版wkhtmltopdf #

该方案不需要更换基础镜像，不需要引入额外技术栈，改动量最小，可完全适配现有基于wicked_pdf编写的业务代码。
你遇到的平台不兼容报错本质是停更的wkhtmltopdf_binary gem从未适配Alpine 3.15+版本，直接从Gemfile中删除该依赖即可，不需要靠第三方gem提供二进制，通过Dockerfile直接安装系统级兼容版本即可正常运行：

1. 修改现有Dockerfile的apk安装段，临时引入Alpine 3.14（最后一个内置wkhtmltopdf稳定包的版本）的社区软件源，安装完成后立刻移除该源配置，避免后续安装其他依赖时出现版本串扰：

RUN echo "https://dl-cdn.alpinelinux.org/alpine/v3.14/community" >> /etc/apk/repositories \
  && apk --update add --no-cache build-base bash git vim curl postgresql-dev openssl-dev nodejs npm yarn tzdata less \
imagemagick postgresql-client gcompat wkhtmltopdf libssl1.1 font-noto-cjk \
  && sed -i '$d' /etc/apk/repositories \
  && wkhtmltopdf --version

说明：追加的libssl1.1用于解决3.14版本wkhtmltopdf在高版本Alpine上的OpenSSL依赖不兼容问题，font-noto-cjk用于解决中文导出时的乱码、方块字问题，最后一行wkhtmltopdf --version会在构建阶段直接校验二进制可用性，避免镜像构建完成后运行才发现报错。

2. 清理Gemfile中过时的wkhtmltopdf_binary相关依赖，仅保留wicked_pdf即可，在wicked_pdf初始化配置中指定二进制路径为系统安装路径：

# config/initializers/wicked_pdf.rb
WickedPdf.config = {
  exe_path: '/usr/bin/wkhtmltopdf'
}

按以上修改重新构建镜像即可正常使用PDF导出功能，所有原有wicked_pdf相关业务代码不需要做任何调整。
不要尝试从源码编译qtwebkit + wkhtmltopdf，整套编译流程需要20G以上磁盘空间，编译时长超过1小时，编译过程依赖问题极多，性价比极低。

方案2：替换为Ruby生态原生PDF方案，完全弃用wkhtmltopdf #

如果担心旧版wkhtmltopdf依赖的qtwebkit存在未修复的安全漏洞，可以直接替换为纯Ruby实现的PDF生成组件，不需要安装任何系统级二进制依赖，完全兼容Ruby 3.0+、Rails 7，也不需要引入NodeJS技术栈：

• Prawn：生态最成熟的纯Ruby PDF生成库，支持自定义字体、图片、表格、矢量图形、页眉页脚、水印等所有常用PDF功能，性能远高于wkhtmltopdf的HTML渲染模式，适合版式固定的票据、报表、合同类PDF生成。缺点是不支持直接转译HTML，需要使用其提供的DSL编写布局，初次适配需要一定工作量。
• HexaPDF：近年更新非常活跃的纯Ruby PDF处理库，除了基础PDF生成功能外，还支持简单HTML到PDF的转译、PDF合并/拆分/加密/签名/内容提取，性能优于Prawn，MIT协议商用友好，适合需要轻度HTML转PDF、同时需要PDF加工能力的场景。
• Thinreports：面向业务报表场景的纯Ruby PDF生成工具，配套可视化模板编辑器，不需要手写大量布局代码，适合固定格式的统计报表、单据类PDF生成，学习成本极低。

避坑提示 #

• 目前所有声称支持Alpine 3.15+版本的wkhtmltopdf第三方gem均存在二进制捆绑不全、依赖缺失的问题，生产环境不建议使用。
• 安装完wkhtmltopdf后不要执行apk upgrade全量升级系统包，避免依赖版本被覆盖导致二进制失效。
• 如果需要导出带复杂JS交互的HTML页面，纯Ruby方案无法满足需求的情况下，优先选择方案1即可，目前生产环境大量Rails Alpine镜像均采用该方式部署wkhtmltopdf，稳定性有充分验证。

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