使用 PDFBox 3.0 保存 PDF 时，若将正在读取的源文件直接作为 save() 的目标路径，会导致文件结构损坏、解析异常及内容丢失——这是 3.0 版本明确禁止的行为，与 2.x 的宽松策略有本质区别。
使用 pdfbox 3.0 保存 pdf 时，若将正在读取的源文件直接作为 `save()` 的目标路径，会导致文件结构损坏、解析异常及内容丢失——这是 3.0 版本明确禁止的行为，与 2.x 的宽松策略有本质区别。
在 PDFBox 3.0 中，PDDocument.save(File) 方法内部采用流式重写（streaming rewrite）机制：它边读取原始 PDF 的对象流（如 object streams、xref table），边构建新文件结构。当目标文件与输入文件为同一物理路径时，写入操作会覆盖尚未读取的文件区域，造成字节错位、交叉污染和元数据断裂——这正是你日志中反复出现 Skipped unexpected dir object、does not end with 'endobj' 及 read() returns -1 等底层 I/O 异常的根本原因。
关键证据已在你的日志中清晰提示：
WARN org.apache.pdfbox.pdmodel.PDDocument.save
- You are overwriting the existing file 24411393_with_barcode_img.pdf,
this will produce a corrupted file if you're also reading from it该警告并非建议，而是强制约束：PDFBox 3.0 的设计哲学是“读写分离”，任何绕过此原则的操作均不可靠。
✅ 正确实践：始终使用临时/独立输出路径
将 pdDocument.save(destinationFile) 替换为 先写入临时文件，再原子替换：
// ✅ 推荐：使用临时文件 + 原子移动
File tempFile = File.createTempFile("pdfbox_temp_", ".pdf");
try {
pdDocument.save(tempFile); // 安全写入临时位置
Files.move(tempFile.toPath(), destinationFile.toPath(),
StandardCopyOption.REPLACE_EXISTING,
StandardCopyOption.ATOMIC_MOVE); // 原子替换（Linux/macOS）或常规覆盖（Windows）
} finally {
if (tempFile.exists()) {
tempFile.delete(); // 清理临时文件（若未成功移动）
}
}⚠️ 注意：StandardCopyOption.ATOMIC_MOVE 在 Windows 上可能退化为普通复制，但 REPLACE_EXISTING 已确保语义安全；若需强原子性，可结合 Files.deleteIfExists(destinationFile) + Files.move(...) 实现。
❌ 错误模式（必须避免）
以下写法在 PDFBox 3.0 中必然失败：
// ❌ 危险！绝对禁止 pdDocument.save(destinationFile); // destinationFile === 加载时的 sourceFile // ❌ 同样危险：即使用了 copy，但后续 save 仍指向原路径 Files.copy(sourceFile.toPath(), destinationFile.toPath(), REPLACE_EXISTING); pdDocument = Loader.loadPDF(destinationFile, ...); // 此时 destinationFile 已被读取 pdDocument.save(destinationFile); // → 覆盖正在读取的文件 → 损坏！
? 补充说明：为何 PDFBox 2.x “看似正常”？
PDFBox 2.x 采用内存全量加载 + 全量序列化策略：save() 时所有对象已驻留内存，写入新文件不依赖原文件剩余字节。因此即使覆盖原文件，也仅影响磁盘上未读部分，不易立即崩溃（但仍有潜在风险）。而 3.0 的流式处理更高效、内存占用更低，代价是严格要求输入/输出路径隔离——这是性能与安全的权衡结果。
✅ 最佳实践总结
| 项目 | 推荐做法 |
|---|---|
| 输入路径 | 使用 Loader.loadPDF(sourceFile) 加载源文件（只读） |
| 输出路径 | 必须为全新路径（临时文件或备份路径） |
| 保存调用 | pdDocument.save(tempFile)，之后用 Files.move() 替换原文件 |
| 资源清理 | pdDocument.close() 必须在 save() 之后调用，且确保 save() 成功完成 |
| 压缩控制 | 如需禁用压缩（如调试），使用 CompressParameters.NO_COMPRESSION 是安全的，不影响路径规则 |
遵循此规范，即可彻底规避 PDF 内容丢失、仅显示二维码等典型损坏现象，同时享受 PDFBox 3.0 在内存效率与 PDF/A 兼容性上的显著提升。
