使用PDFBox 3.0 Alpha保存PDF后文件损坏问题排查求助

问题背景 #

使用PDFBox 3.0 Alpha移除PDF中的二维码后，文件从6.8MB压缩至6.7MB（符合预期），但重新加载该二维码并添加回文档后保存，PDF内容损坏，仅显示新增的二维码。此前使用PDFBox 2.0.24/2.0.27版本时无此损坏问题，但移除二维码后文件大小会增至8.1MB，问题出在文件保存阶段，怀疑与PDFBox 3.0的内部逻辑变更有关。

核心排查方向 #

1. 页面内容流的覆盖问题 #

PDFBox 3.0对PDPageContentStream的默认行为做了变更：2.x版本中创建内容流默认是追加原页面内容，而3.0中默认是覆盖。如果添加二维码的代码没有显式指定追加模式，就会直接覆盖原页面的所有内容，导致仅显示新添加的二维码。

检查代码是否使用了错误写法：

PDPageContentStream contentStream = new PDPageContentStream(document, page);

正确写法需指定追加模式：

PDPageContentStream contentStream = new PDPageContentStream(document, page, PDPageContentStream.AppendMode.APPEND, true, true);

最后两个true参数分别表示允许追加到现有内容流、重置上下文，确保原页面内容不会被覆盖。

2. 文档资源的回收与复用逻辑变更 #

PDFBox 3.0优化了资源（字体、图像、内容流）的自动清理机制，可能在移除二维码的过程中，误将原文档依赖的其他资源标记为“无用”并回收。当重新添加二维码并保存时，原内容因缺失依赖资源无法渲染。

• 查看错误日志中是否存在COSObject has been deallocated、Missing resource这类报错
• 移除二维码后，避免立即执行添加操作，可先将文档保存为临时文件，再重新打开临时文件添加二维码，强制资源重新加载

3. 页面修改后的状态同步问题 #

3.0中对PDDocument和PDPage的状态管理更严格，如果移除二维码后没有正确刷新页面的状态，后续添加操作可能导致文档结构损坏。

• 移除二维码时，调用page.getResources().getXObjects().clear()需谨慎，避免误删其他图像资源
• 添加二维码后，调用document.getDocumentCatalog().getPages().refresh()同步页面状态

临时解决方案 #

• 若需快速恢复业务功能，暂时回退到PDFBox 2.0.27版本，该版本内容流处理逻辑更稳定，虽会导致文件增大，但无内容损坏问题
• 在3.0环境下，拆分操作流程：移除二维码→保存临时PDF→打开临时PDF→添加二维码→保存最终文件，避免在同一个文档实例中连续执行修改操作

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