HTML内容无法在wkhtmltopdf生成的PDF中渲染问题求助

问题现象 #

此前正常运行的HTML转PDF功能，现在出现内容缺失：仅能看到<hr/>生成的水平线，用户签名、名称、响应日期等动态内容完全不显示。

已排除的可能性 #

• 后端/Rails逻辑问题：确认数据正常输出，相同HTML在浏览器中可完整渲染所有内容
• Bootstrap兼容性问题：浏览器中HTML渲染正常，说明前端逻辑本身无问题

相关代码片段 #

无法渲染的核心ERB代码：

<div class="row top-padded">
  <div class="col-md-10">
    <p class="block bold"><%= (status == "abstain") ? "Abstained By" : "#{status.capitalize} By:" %></p>
    <hr />
    <% requesters.merge(User.answered).where(approved_status: status).each do |user_obj| %>
      <% user = user_obj&.user&.decorate %>
      <%= image_tag user_obj.signature, style: "width: 200px; height: auto;" unless user_obj.signature.blank? %>
      <p>
        <%= user&.first_last || "Removed User" %>
        on
        <%= user_obj.decorate.response_date %>
        <%= user&.time_zone if user %>
      </p>
    <% end %>
  </div>
</div>

完整HTML模板（ERB）：

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <meta charset="UTF-8">
    <%= wicked_pdf_stylesheet_link_tag "optional/pdf_fonts" %>
    <%= wicked_pdf_stylesheet_link_tag "application" %>
  </head>
  <body>
    <div class="col-lg-12">
      <h1><%= question %></h1>
      <div class="approval_metadata top-padded">
        <p>
          <%#=  this is for rendering pdf%>
          <%= content_tag(:span, highlight("Title: #{user&.name}", 'title', highlighter: '<strong>\1</strong>'), class: "block") %>
          <%= content_tag(:span, highlight("Filename: #{user&.filename}", 'filename', highlighter: '<strong>\1</strong>'), class: "block") %>
          <%= content_tag(:span, highlight("File created: #{user&.created_at&.strftime('%d-%^b-%Y %I:%M:%S %p')}", 'file created', highlighter: '<strong>\1</strong>'), class: "block") %>
          <%= content_tag(:span, highlight("File Last Modified: #{user&.updated_at&.strftime('%d-%^b-%Y %I:%M:%S %p')}", 'file last modified', highlighter: '<strong>\1</strong>'), class: "block") %>
          <%= content_tag(:span, highlight("Location: Resource Library / #{user.pluck(:name)&.join(" / ")}", 'location', highlighter: '<strong>\1</strong>'), class: "block") %>
          <%= content_tag(:span, highlight("Approval Requested: #{approval&.created_at&.strftime('%d-%^b-%Y %I:%M:%S %p')}", 'approval requested', highlighter: '<strong>\1</strong>'), class: "block") %>
          <%= content_tag(:br) %>
        </p>
      </div>
      <% User.statuses.each do |status, index| %>
        <div class="row top-padded">
          <div class="col-md-10">
            <p class="block bold"><%= (status == "abstain") ? "Abstained By" : "#{status.capitalize} By:" %></p>
            <hr />
            <% requesters.merge(User.answered).where(approved_status: status).each do |user_obj| %>
              <% user = user_obj&.user&.decorate %>
              <%= image_tag user_obj.signature, style: "width: 200px; height: auto;" unless user_obj.signature.blank? %>
              <p>
                <%= user&.first_last || "Removed User" %>
                on
                <%= user_obj.decorate.response_date %>
                <%= user&.time_zone if user %>
              </p>
            <% end %>
          </div>
        </div>
      <% end %>
    </div>
  </body>
</html>

当前怀疑方向 #

1. wkhtmltopdf工具的渲染兼容性问题
2. Bootstrap 4升级到Bootstrap 5后的PDF适配问题

解决建议 #

针对wkhtmltopdf的排查与修复 #

• 升级工具版本：老旧版本对CSS3、HTML5特性支持有限，直接升级到最新稳定版测试。
• 启用调试输出：添加--debug-javascript和--verbose参数运行wkhtmltopdf，查看是否有JS解析或渲染报错；用--dump-dom导出渲染后的DOM结构，确认动态内容是否被正确解析。
• 强制内容可见性：给缺失内容的容器添加行内样式visibility: visible !important; display: block !important;，避免工具误判元素为不可见。
• 修正图片路径：确保user_obj.signature是绝对URL（如https://your-domain.com/path/to/signature.png），wkhtmltopdf对相对路径图片的解析稳定性差。

针对Bootstrap 5的兼容调整 #

• 使用PDF专用样式：创建独立的PDF样式表，覆盖Bootstrap 5中可能冲突的布局样式，示例：

  /* PDF样式重置 */
  .row, .col-md-10, .col-lg-12 {
    display: block !important;
    width: 100% !important;
    float: none !important;
    margin: 0 !important;
    padding: 0 !important;
  }
  .top-padded {
    margin-top: 1em !important;
  }
  .block {
    display: block !important;
    margin: 0.5em 0 !important;
  }
  

  暂时屏蔽Bootstrap全局样式，仅加载该专用样式，验证是否为Bootstrap导致的问题。
• 替换flex布局：Bootstrap 5大量使用flex布局，wkhtmltopdf对其支持不完善，手动将容器改为块级布局，移除d-flex等相关类。
• 指定兼容字体：Bootstrap 5默认字体可能在PDF中无法加载，在PDF样式中指定系统通用字体：

  body {
    font-family: Arial, Helvetica, sans-serif !important;
  }
  

其他排查点 #

• 验证ERB渲染结果：在控制器中输出渲染后的纯HTML，确认所有动态内容（用户名、日期、图片URL）都已正确生成，无空值或未解析的ERB标签。
• 处理分页截断：如果内容刚好处于分页位置，wkhtmltopdf可能截断内容，添加CSS强制避免分页：

  .top-padded {
    page-break-inside: avoid !important;
  }
  

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