使用 PDFBox 3.0 保存修改后的 PDF 时，若直接以加载源文件的同一路径调用 save()，将引发文件结构破坏、内容丢失甚至无法打开——根本原因是 PDFBox 3.0 严格禁止“读写同源”，而旧版 2.x 对此容忍度较高。
使用 pdfbox 3.0 保存修改后的 pdf 时，若直接以加载源文件的同一路径调用 `save()`，将引发文件结构破坏、内容丢失甚至无法打开——根本原因是 pdfbox 3.0 严格禁止“读写同源”，而旧版 2.x 对此容忍度较高。
在 PDFBox 3.0 中，文档加载（Loader.loadPDF()）与保存（PDDocument.save()）采用流式内存映射与延迟解析机制，当输入文件同时被用作输出目标时，底层 RandomAccessRead 流会在保存过程中持续读取原始文件结构（如交叉引用表、对象流、xref stream），而写入操作又会实时覆写磁盘上的相同字节区域，造成读写竞争与数据错位。这正是日志中反复出现 Skipped unexpected dir object、does not end with 'endobj' 和 read() returns -1 等低层解析异常的根本原因——PDF 文件的物理结构已被破坏。
✅ 正确做法：强制使用临时输出路径
必须确保 save() 的目标文件路径与 Loader.loadPDF() 加载的源文件完全独立。推荐采用以下安全模式：
// ✅ 正确：使用临时文件或明确区分的输出路径
File sourceFile = new File("input.pdf");
File tempOutput = Files.createTempFile("pdfbox-modified-", ".pdf").toFile();
try (PDDocument doc = Loader.loadPDF(sourceFile, MemoryUsageSetting.setupTempFileOnly())) {
// ... 修改逻辑：添加二维码、调整内容等 ...
// 关键：保存到与 sourceFile 不同的文件路径
doc.save(tempOutput); // ← 绝对不可写为 doc.save(sourceFile)
}
// 如需替换原文件，应在 save 成功后原子性移动
Files.move(tempOutput.toPath(), sourceFile.toPath(),
StandardCopyOption.REPLACE_EXISTING);⚠️ 注意：即使使用 CompressParameters.NO_COMPRESSION 或 MemoryUsageSetting.setupMainMemoryOnly()，也无法绕过该限制——这是 PDFBox 3.0 架构级的强约束，而非配置问题。
❌ 常见错误模式（务必避免）
- 错误 1：doc.save(sourceFile) —— 日志中明确警告 You are overwriting the existing file... this will produce a corrupted file
- 错误 2：先 Files.copy(src, dst) 再 Loader.loadPDF(dst) + doc.save(dst) —— 若 dst 与后续 save() 目标相同，仍属读写同源
- 错误 3：多线程共用同一 PDDocument 实例并并发调用 save() —— 即使路径不同，也可能因资源竞争导致状态不一致
? 验证修复效果
成功修复后，应观察到：
- 日志中不再出现 WARN 级“overwriting the existing file”提示；
- 生成的 PDF 可被 Adobe Acrobat、Chrome PDF 查看器正常打开，全文内容完整可见；
- 文件大小变化符合预期（如添加图像后适度增大，而非异常膨胀或截断）；
- pdDocument.getNumberOfPages() 与原始文档一致，无页数丢失。
? 补充建议
- 升级兼容性检查：PDFBox 3.0 移除了 PDPageContentStream.append() 等旧 API，改用 AppendMode.APPEND 构造函数（您代码中已正确使用）；但需同步检查 JPEGFactory → LosslessFactory / JPEGFactory 的图像创建逻辑是否适配新版本。
- XMP 元数据注意：您代码中为图像设置 PDMetadata 的方式在 3.0 中仍有效，但建议确认 XmpSerializer.serialize(..., true) 的 true 参数（启用 UTF-16）是否与文档编码兼容，避免元数据写入异常。
- 性能优化：若批量处理，可复用 MemoryUsageSetting 实例，并在 PDDocument.close() 后显式清理临时文件（尤其使用 setupTempFileOnly() 时）。
遵循“读写分离”原则，是 PDFBox 3.0 安全操作 PDF 文档的基石。这一变更虽带来短期适配成本，却显著提升了库的健壮性与 PDF 标准合规性。
