如何使用Wicked_PDF在Rails中填充现有PDF模板并生成新PDF？

云原生阿岚

2026-5-26

绝对可以用Wicked_PDF搞定，但具体怎么实现得看你的PDF模板类型——是用HTML/CSS写的动态模板，还是已经有了带占位符的静态PDF？下面给你拆解不同场景的方案，再推荐几个更适配的工具：

用Wicked_PDF实现的两种场景

Wicked_PDF的核心逻辑是把HTML/CSS渲染成PDF，所以它最适配HTML类模板，但也能配合其他工具处理静态PDF：

场景1：HTML/CSS作为模板（Wicked_PDF的主场）
这是Wicked_PDF最擅长的场景，你只需要把模板写成Rails视图，填充动态变量就行。步骤很简单：

先在Gemfile里添加依赖并安装：
```
gem 'wicked_pdf'
gem 'wkhtmltopdf-binary' # 依赖的渲染引擎，不用自己装wkhtmltopdf
```
然后跑bundle install和rails generate wicked_pdf生成配置文件。

在控制器里写生成逻辑：

def generate_filled_pdf
  @order = Order.find(params[:id]) # 你要填充的动态数据
  respond_to do |format|
    format.pdf do
      render pdf: "order_#{@order.id}", # 生成的PDF文件名
             template: 'orders/order_template', # 你的HTML模板路径
             layout: 'pdf_layout' # 可选的PDF专用布局（比如去掉导航栏）
    end
  end
end

在视图app/views/orders/order_template.html.erb里写填充内容：

<div class="pdf-container">
  <h1>订单详情 #<%= @order.id %></h1>
  <p>客户姓名: <%= @order.customer_name %></p>
  <p>订单金额: $<%= @order.amount %></p>
</div>

这种方式灵活度拉满，适合需要动态生成复杂内容的场景。

场景2：已有静态PDF模板（带占位符/表单字段）
Wicked_PDF本身不直接支持编辑静态PDF，但可以配合其他gem实现：比如先用pdf-forms填充静态PDF的表单字段，再用Wicked_PDF做后续的格式调整。不过这种方式有点绕，更推荐直接用下面的专用工具。

更适配的工具推荐

如果你的需求是处理静态PDF模板，这几个工具比Wicked_PDF更顺手：

FillablePDF：专门用来填充带表单字段的PDF模板，几乎零学习成本
先加依赖：

gem 'fillable-pdf'

然后直接填充字段：

template_path = Rails.root.join('app', 'assets', 'pdfs', 'user_form_template.pdf')
output_path = Rails.root.join('public', 'filled_user_form.pdf')

fillable_pdf = FillablePDF.new(template_path)
# 对应PDF里的表单字段名，直接赋值
fillable_pdf.set_fields(
  'full_name' => 'Travis Smith',
  'email' => 'travis@example.com',
  'phone_number' => '555-1234'
)
fillable_pdf.save(output_path)

完美适配带可填写字段的静态PDF，连位置都不用自己调。

Prawn：适合需要精确控制内容位置的静态PDF模板
Prawn是Rails生态里老牌的PDF生成库，支持加载已有PDF模板并在上面叠加内容：

Prawn::Document.new(template: Rails.root.join('app', 'assets', 'pdfs', 'blank_invoice.pdf')) do |pdf|
  # 指定坐标添加文本（坐标是PDF的左下角为原点）
  pdf.text "Invoice #1234", at: [200, 700], size: 16
  pdf.text "Date: #{Date.today}", at: [200, 680]
  # 还能添加图片
  pdf.image Rails.root.join('app', 'assets', 'images', 'company_logo.png'), at: [50, 720], width: 100
end.render_file Rails.root.join('public', 'generated_invoice.pdf')

唯一的缺点是需要你知道内容的精确坐标，适合对排版要求极高的场景。

Grover：现代版的Wicked_PDF，支持复杂CSS/JS
如果你的HTML模板用到了现代CSS（比如Grid、Flex）或者JS动态内容，Grover基于Chrome渲染引擎，比Wicked_PDF的兼容性更好。用法和Wicked_PDF几乎一致，替换gem就行：
```
gem 'grover'
```
控制器里的渲染逻辑和Wicked_PDF差不多，只是把render pdf:换成render grover:即可。

总结一下

要是用HTML/CSS做模板：优先选Wicked_PDF或Grover，前者成熟，后者兼容现代前端特性
要是处理带表单字段的静态PDF：直接用FillablePDF，省心省力
要是需要精确控制内容位置的静态PDF：选Prawn

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