使用 pdfbox 3.0 保存修改后的 pdf 时，若直接以加载源文件路径作为 save() 的输出路径，将导致文件结构损坏、内容丢失或解析异常——根本原因是 pdfbox 3.0 在保存过程中会边读边写，覆写操作破坏了正在被解析的底层字节流。
使用 pdfbox 3.0 保存修改后的 pdf 时，若直接以加载源文件路径作为 save() 的输出路径，将导致文件结构损坏、内容丢失或解析异常——根本原因是 pdfbox 3.0 在保存过程中会边读边写，覆写操作破坏了正在被解析的底层字节流。
在 PDFBox 3.0 中，禁止将输入文件路径直接用作保存目标路径（即“in-place save”），这是与 2.x 版本最显著且必须遵守的行为变更。从官方 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.
这一限制源于 PDFBox 3.0 对内存与 I/O 模型的重构：PDDocument.save() 在序列化过程中会动态访问文档对象图，并可能重读原始文件中的交叉引用表（xref）、对象流（object streams）等结构。当输出目标与输入源为同一文件时，写入操作会覆盖尚未读取的原始数据块，造成 PDF 文件语法错乱（如日志中反复出现的 Skipped unexpected dir object、does not end with 'endobj'、Expected a long type at offset 0, instead got '' 等错误），最终生成无法被标准 PDF 阅读器正确解析的损坏文件。
✅ 正确做法：使用临时文件或独立输出路径
将 pdDocument.save(destinationFile) 替换为先保存至唯一临时文件，再原子性地替换原文件：
// ✅ 推荐：使用临时文件 + 原子替换
Path tempPath = Files.createTempFile("pdfbox_modified_", ".pdf");
pdDocument.save(tempPath.toFile(), CompressParameters.NO_COMPRESSION);
pdDocument.close();
// 原子性替换（确保线程/进程安全）
Files.move(tempPath, destinationFile.toPath(),
StandardCopyOption.REPLACE_EXISTING,
StandardCopyOption.ATOMIC_MOVE);? 提示：StandardCopyOption.ATOMIC_MOVE 在同文件系统下可保证替换操作不可中断；若跨文件系统不支持，可降级为 REPLACE_EXISTING，但需确保无并发写入风险。
⚠️ 其他关键注意事项
不要复用 Loader.loadPDF() 加载的文件路径作为 save() 目标
即使你已通过 Files.copy() 预先复制了源文件（如代码中 Files.copy(sourceFile.toPath(), destinationFile.toPath(), ...)），只要后续 Loader.loadPDF(destinationFile, ...) 加载的是该副本，而 save() 又写回 destinationFile，仍构成“读-写同一文件”，触发损坏逻辑。避免在 PDPageContentStream 中误用旋转矩阵
当前代码中对 90°/270° 页面的 transform() 调用存在坐标系混淆风险（如 pdPage.getCropBox().getWidth() + pdPage.getCropBox().getLowerLeftX() 计算不严谨）。建议统一使用 Matrix.getTranslateInstance() + Matrix.getRotateInstance() 组合，并基于页面归一化坐标（0,0 为左下角）计算偏移，而非依赖 CropBox 边界加法。XMP 元数据注入非必需且易引入兼容性问题
示例中为每张图片创建独立 XMP 并注入 PDMetadata，但 PDF 规范并不要求图像级元数据，且 image.setMetadata(metadata) 在 PDFBox 3.0 中可能引发嵌套对象引用异常。如无强业务需求，建议移除该段代码以简化流程、提升稳定性。
? 总结
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
| PDF 打开后仅显示二维码、正文消失、Acrobat 报“损坏” | PDFBox 3.0 禁止读写同一文件，覆写破坏 PDF 结构 | 强制分离输入/输出路径：始终 save() 到新文件，再替换 |
| 日志出现 Skipped unexpected dir object / read() returns -1 | 文件字节流被截断或错位，解析器无法定位对象 | 使用临时文件 + ATOMIC_MOVE 保障完整性 |
| 文件体积异常（如移除图片后反而增大） | PDFBox 2.x 与 3.0 的压缩策略、对象清理机制不同 | 属正常行为差异，无需修复；关注功能正确性而非体积 |
遵循“输入 ≠ 输出”这一黄金法则，即可彻底规避 PDFBox 3.0 的文件损坏问题，确保 QR 码增删等 PDF 编辑操作稳定可靠。
