Java Freemarker PDF模板中Base64图片背景裁切问题求助

以下是针对Freemarker生成PDF时Base64图片显示异常的可行排查和解决方向：

• 检查Base64编码的完整性与格式
  先确认渲染后的HTML源码中，img的src属性是完整的data:image/png;base64,xxxxxx格式：

  • 对比原始图片的Base64编码和模板输出后的编码，排查是否存在字符串截断或额外字符
  • 避免转义错误：如果Freemarker开启了默认HTML转义，Base64中的+、/、=可能被转义为+、/、=导致编码失效，可使用<#noescape>标签包裹变量：

    <img src="data:image/png;base64,<#noescape>${imgDataAsBase64}</#noescape>" />
    

• 调整PDF渲染引擎的处理逻辑
  多数异常由PDF生成引擎（如Flying Saucer、iText）的图片渲染限制导致：

  • 给img标签添加width、height属性或用CSS固定尺寸，避免引擎自动缩放失真
  • 转换图片格式/颜色模式：若图片是CMYK颜色模式，PDF引擎支持性较差，转成RGB模式后再编码；不需要透明效果的话，将PNG转成JPEG再生成Base64
  • 升级引擎版本：旧版本的iText或Flying Saucer对Base64图片兼容性不足，升级到最新稳定版可解决部分底层问题

• 绕过Base64直接嵌入图片
  如果Base64方式始终有问题，换用本地文件或流的方式嵌入：

  • 将用户上传的图片保存为临时文件，在PDF生成时通过引擎API直接添加图片流（比如iText的Image.getInstance()方法），跳过HTML渲染环节
  • 若使用Freemarker模板，可将图片路径作为变量传入，模板中引用本地路径（需确保PDF引擎能访问到该文件）

• 禁用Freemarker的长字符串换行
  部分场景下Freemarker会对超长的Base64字符串自动换行，破坏编码结构，可在模板配置中关闭字符串格式化，或确保变量输出时未被添加换行符。

内容的提问来源于stack exchange，提问作者B.Mat