使用FlyingSaucer生成PDF证书时背景出现白边问题

针对你用Spring Boot 3.1.0 + Thymeleaf + FlyingSaucer生成证书PDF时出现的背景图白边问题，以下是经过验证的解决步骤：

1. 强制清零页面与容器边距 #

FlyingSaucer默认会给PDF页面添加默认边距，同时HTML的html/body标签也自带默认内边距/外边距，必须显式重置：

@page {
    /* 若背景图是自定义尺寸，将size改为对应印刷单位，比如1920px≈1440pt，1440px≈1080pt，写成：size: 1440pt 1080pt; */
    size: A4; 
    margin: 0; /* 关键：取消页面默认边距 */
}

html, body {
    margin: 0;
    padding: 0;
    width: 100%;
    height: 100%;
    overflow: hidden; /* 避免内容溢出产生滚动条或额外空白 */
}

2. 配置背景图的铺满规则 #

确保背景图完全覆盖body容器，避免留白：

body {
    background-image: url('/path/to/your/background.jpg');
    background-repeat: no-repeat;
    background-position: 0 0; /* 强制从左上角开始渲染 */
    background-size: 100% 100%; /* 完全适配容器尺寸，也可用cover，但cover可能裁切，100%100%更精准 */
}

如果使用自定义页面尺寸，务必保证@page的size参数和背景图的印刷尺寸（pt单位）完全匹配，FlyingSaucer对px单位的渲染精度不如pt，建议提前转换：1px = 0.75pt。

3. 调整FlyingSaucer渲染参数 #

在Java生成代码中，确保启用打印媒体类型，并确认页面尺寸生效：

ITextRenderer renderer = new ITextRenderer();
// 加载渲染后的HTML内容
renderer.setDocumentFromString(thymeleafRenderedHtml);
// 指定媒体类型为print，确保样式适配PDF打印场景
renderer.getSharedContext().setMedia("print");
renderer.layout();
renderer.createPDF(outputStream);

4. 排查图片本身问题 #

用图片编辑工具打开你的1920x1440背景图，检查：

• 图片边缘是否本身带有白色像素（可能是导出时的画布留白）
• 若用PNG格式，是否存在透明通道（FlyingSaucer可能将透明区域渲染为白色），建议转为JPG格式测试

5. 清理Thymeleaf模板冗余内容 #

确保Thymeleaf渲染后的HTML中，body标签内没有多余的空格、换行或空标签，这些隐性内容可能导致容器尺寸偏移。

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