使用 PDFBox 3.0 保存修改后的 PDF 时，若直接以加载源文件路径作为 save() 输出路径，将导致文件结构损坏、内容丢失或解析异常——这是由底层流式读写冲突引发的确定性问题，而非图像插入逻辑错误。
使用 pdfbox 3.0 保存修改后的 pdf 时，若直接以加载源文件路径作为 `save()` 输出路径，将导致文件结构损坏、内容丢失或解析异常——这是由底层流式读写冲突引发的确定性问题，而非图像插入逻辑错误。
在 PDFBox 3.0 中，PDDocument.save(File) 方法在执行过程中会动态读取文档内部对象（如对象流、交叉引用表）并重写整个文件结构。当输入源与输出目标为同一物理文件时，PDFBox 在读取尚未写入完成的新内容时，可能遭遇截断、覆盖或字节错位，从而破坏 PDF 的二进制格式完整性。这一点在官方 PDFBox 3.0 迁移指南 中被明确列为禁止行为：
Don’t use the source as output
The input file must not be used as output for saving operations. It will corrupt the file and throw an exception as parts of the file are read the first time when saving it.
从您提供的日志中可清晰验证该问题：
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
随后出现的 Skipped unexpected dir object、Bad dictionary declaration、does not end with 'endobj' 及 IOException: Expected a long type at offset 0 等错误，均为文件结构已损坏的典型表现——PDF 解析器在尝试读取被中途覆写的对象流时，遭遇非法字节序列而失败。
✅ 正确做法：始终使用临时文件或独立输出路径
应严格分离「读取源」与「写入目标」。推荐采用以下安全模式：
// ✅ 正确：使用临时文件或新路径保存
File tempFile = Files.createTempFile("pdfbox-modified-", ".pdf").toFile();
pdDocument.save(tempFile); // ← 输出到全新文件
pdDocument.close();
// 再原子化替换（如需覆盖原文件）
Files.move(tempFile.toPath(), destinationFile.toPath(),
StandardCopyOption.REPLACE_EXISTING);或更简洁地，在业务逻辑中确保 destinationFile 与加载源文件物理路径不同：
// 加载时用 sourceFile PDDocument pdDocument = Loader.loadPDF(sourceFile, MemoryUsageSetting.setupTempFileOnly()); // 保存时必须用另一个文件（不可是 sourceFile！） pdDocument.save(newDestinationFile); // ← 关键：newDestinationFile ≠ sourceFile
⚠️ 其他注意事项
- 不要依赖 CompressParameters.NO_COMPRESSION 规避问题：禁用压缩仅影响内容流编码，无法解决底层 I/O 覆盖冲突。
- 避免 Files.copy(... REPLACE_EXISTING) 后立即加载同一文件：您的代码中先复制再加载 destinationFile，若该文件就是原始源，则后续 save(destinationFile) 仍构成覆盖风险。
- PDFBox 2.x 的“看似正常”具有误导性：2.x 版本因内部缓存策略较宽松，可能掩盖了竞态问题，但实际已产生隐性冗余（如您观察到的文件体积增大），并非真正安全；3.x 强化了校验与一致性，暴露了根本缺陷。
- 旋转处理逻辑无需修改：您对 Matrix.getRotateInstance 和 getRotatedMediaBox 的实现符合 PDF 坐标系规范，问题根源不在图像定位，而在文件 I/O 策略。
✅ 总结
| 问题本质 | PDFBox 3.0 不允许“边读边写同一文件”，属设计强制约束 |
|---|---|
| 根本原因 | save() 内部流操作与文件系统覆写发生不可控竞态 |
| 修复方式 | 强制使用不同文件路径进行读/写分离，通过临时文件 + 原子移动保障安全性 |
| 验证方法 | 检查日志是否仍有 overwriting the existing file 警告；打开生成 PDF 是否能被 Adobe Acrobat / PDFBox 自身正确解析 |
遵循此原则后，QR 码添加功能将稳定运行，文件体积变化也将回归合理范围（如您在移除操作中观察到的压缩效果），同时兼顾 PDF 标准兼容性与长期可维护性。
