使用 Apache PDFBox 的 addPage() 直接添加来自其他文档的页面会导致内容无法渲染，产生全空白页；必须改用 importPage() 方法完成跨文档页面的安全复制与嵌入。
使用 apache pdfbox 的 `addpage()` 直接添加来自其他文档的页面会导致内容无法渲染，产生全空白页；必须改用 `importpage()` 方法完成跨文档页面的安全复制与嵌入。
在使用 Apache PDFBox 进行 PDF 文档合并时，一个常见却容易被忽视的陷阱是：直接调用 PDDocument.addPage(PDPage) 添加来自其他 PDDocument 实例的页面，将导致最终 PDF 中出现完全空白的页面——尽管页数统计正确、文档结构完整，但所有内容均不可见。
根本原因在于：PDPage 对象与其所属的 PDDocument（即“拥有者文档”）强绑定。该页面的资源（如字体、图像、流内容等）存储在原文档的底层 COSDocument（即 scratch file）中。若直接将 page 传给目标文档的 addPage()，PDFBox 并不会自动迁移或重映射这些依赖资源；目标文档无法解析其内容流，从而渲染为空白。
✅ 正确做法是使用 PDDocument.importPage(PDPage) 方法：
- importPage() 会深度复制页面及其全部依赖资源（包括 Resources 字典、Contents 流、字体、图像 XObject 等），并将其注册到当前文档的资源管理器中；
- 返回的是一个属于当前文档的新 PDPage 实例，可安全用于 addPage() 或直接插入；
- 官方 Javadoc 明确指出：“If you are adding a page to this document from another document and want to copy the contents to this document's scratch file then use this method”。
以下是修复后的核心代码示例（基于原始逻辑优化）：
// 创建目标文档
PDDocument document = new PDDocument();
// 加载固定页模板（如 CGV）
File cgvFile = new File(context.repertoire_advendio + "conf/CGV.pdf");
try (PDDocument docCgv = Loader.loadPDF(cgvFile)) {
PDPage templatePage = docCgv.getPage(0);
// 遍历待合并的 PDF 文件
File inputDir = new File(context.repertoire_output_docone);
for (String filename : inputDir.list()) {
if (!filename.startsWith("fact_") && !filename.startsWith("agence_fact_")) {
continue;
}
File pdfFile = new File(inputDir, filename);
try (PDDocument srcDoc = Loader.loadPDF(pdfFile)) {
// 逐页导入并插入固定页
for (int i = 0; i < srcDoc.getNumberOfPages(); i++) {
// ✅ 关键：使用 importPage 复制页面到当前文档上下文
PDPage importedPage = document.importPage(srcDoc.getPage(i));
document.addPage(importedPage);
// 插入固定页（同样需导入！）
PDPage importedTemplate = document.importPage(templatePage);
document.addPage(importedTemplate);
}
}
}
}
// 保存并关闭
String outputPath = context.repertoire_output_docone
+ "output/docone_" + context.id_legal_entity
+ "_" + context.input_invoice_date.replace("-", "") + ".pdf";
document.save(outputPath);
document.close();? 关键注意事项：
- importPage() 必须在目标文档（document）上调用，而非源文档；
- 每个需跨文档复用的页面（包括 templatePage）都必须单独 importPage() —— 即使是同一模板页，在每次插入前也应重新导入（PDFBox 不缓存跨文档引用）；
- 始终使用 try-with-resources 确保源 PDDocument 及时关闭，防止文件句柄泄漏和内存占用；
- importPage() 是深拷贝操作，对大文件或大量页面可能影响性能，但这是保证正确性的必要开销；
- 切勿复用已关闭文档中的 PDPage 对象——Loader.loadPDF(...).getPage(0) 后若源文档已关闭，该 PDPage 将处于无效状态。
总结：addPage() 仅适用于向本文档添加本就属于该文档的页面（如 new PDPage() 创建的空白页）；而所有来自外部 PDF 的页面，一律须经 importPage() 转换后方可安全集成。掌握这一区别，是构建健壮 PDF 合并工具的基础前提。
