解决Gotenberg PHP库PDF主内容与页眉页脚重叠问题

核心解决方案：用CSS分页媒体规则预留页眉页脚空间 #

Gotenberg基于Chrome渲染引擎，支持CSS分页媒体规范，通过@page设置页面边距，把背景图中页眉、页脚的区域提前空出来，让主内容仅在中间安全区域显示，自动分页时也不会侵入页脚区域。

具体实现代码（适配背景图布局） #

假设你的背景图中页眉高度为80px、页脚高度为60px，按以下方式修改CSS：

/* 定义页面尺寸与边距，预留页眉页脚的空间 */
@page {
  size: A4; /* 匹配背景图的页面尺寸，可改为letter等 */
  margin-top: 80px;    /* 数值等于背景图页眉的实际高度 */
  margin-bottom: 60px; /* 数值等于背景图页脚的实际高度 */
  margin-left: 20px;   /* 按需调整左右边距 */
  margin-right: 20px;
}

body {
  margin: 0;
  padding: 0;
  /* 背景图设置：确保覆盖整个PDF页面（包括@page的边距区域） */
  background-image: url('default-background.jpg');
  background-size: 100% 100%;
  background-repeat: no-repeat;
}

.main-content {
  box-sizing: border-box;
  width: 100%;
  /* 可选：防止内容在元素中间被分页截断 */
  page-break-inside: avoid;
}

关键逻辑说明 #

1. @page的边距会强制主内容从页眉下方开始、到页脚上方结束，Chrome的自动分页机制会严格遵守这个范围，不会让内容跑到页脚区域。
2. 背景图设置background-size: 100% 100%后，会覆盖整个PDF页面（包括@page设置的边距区域），刚好和页眉页脚的位置对应。
3. 如果背景图需要每页重复显示，把background-repeat改成repeat-y即可。

额外注意事项 #

• 必须确保背景图的尺寸和@page设置的页面尺寸完全匹配（比如A4是210mm×297mm），避免背景图拉伸变形。
• 若有需要跨页显示的元素（如长表格），可给元素添加page-break-inside: auto来允许分页。

内容的提问来源于stack exchange，提问作者Avnee.Angel