使用Gotenberg工具转换HTML为PDF时出现意外空白问题求助

我之前在用Gotenberg做HTML转PDF的时候也碰到过这种“HTML显示正常，PDF里莫名冒空白”的情况，结合踩过的坑给你几个实用的排查和解决方向：

• 优先检查打印媒体查询下的CSS样式
  Gotenberg基于Chrome的渲染引擎，会自动应用@media print的样式，这和屏幕端的@media screen经常有差异。你可以先在CSS里重置div的边距、内边距，同时强制统一盒模型：

  @media print {
    * {
      margin: 0 !important;
      padding: 0 !important;
      box-sizing: border-box !important;
    }
  }
  

  很多时候都是浏览器默认打印样式偷偷给元素加了额外间距，才导致PDF里出现空白。

• 处理浮动布局带来的渲染异常
  如果你的div里用了浮动元素，Chrome的打印引擎对浮动的计算有时候会和屏幕端不一致，很容易产生空白区域。建议给包含浮动的容器添加清除浮动的样式：

  .float-wrapper::after {
    content: "";
    display: table;
    clear: both;
  }
  

  更稳妥的方式是直接改用flex或grid布局，彻底避开浮动带来的渲染问题。

• 控制页面分页逻辑
  如果空白刚好出现在页面交界处，大概率是分页截断导致的。可以给容易产生空白的div添加分页控制属性，强制元素不被分页拆分：

  @media print {
    .avoid-break {
      page-break-inside: avoid;
      page-break-before: avoid;
      page-break-after: avoid;
    }
  }
  

• 修正inline-block元素的垂直对齐
  要是div里包含inline-block元素，默认的vertical-align: baseline可能会在元素底部产生空白。只需把垂直对齐方式改成顶部：

  .inline-block-item {
    vertical-align: top;
  }
  

• 禁用Gotenberg的默认样式（可选）
  如果以上方法都没用，可能是Gotenberg自带的默认打印样式干扰了你的布局。你可以在调用API时添加defaultStyles: false（或者命令行参数--no-default-styles），完全用自定义CSS来控制PDF渲染。

另外有个小技巧：先把你的HTML在Chrome浏览器的打印预览里看看，如果预览里也有空白，那问题肯定出在CSS的打印样式上；如果Chrome预览正常但Gotenberg转出来有问题，可以尝试调整Gotenberg的渲染参数，比如设置更高的DPI或者指定页面尺寸。

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