使用 pdfbox 2.x 移除 pdf 中 qr 码图像后，adobe reader 提示“an error exists on this page”，且文件体积异常增大——根本原因在于资源对象跨页共享、xobject 与内容流操作不一致，以及未清理残留引用。本文详解问题成因并提供安全、可验证的修复实践。
在 PDF 结构中，图像资源（XObject）常通过 Resources 字典集中管理，且同一 PDImageXObject 可被多个页面共用——这是 PDF 规范为节省空间设计的核心机制。而原代码中调用 pdPage.getResources() 获取资源后直接在 COSDictionary 层面移除 XObject，实则修改了共享的 PDResources 对象。若该图像同时存在于其他页面，其资源将被意外销毁，但其他页面的内容流（Content Stream）仍保留对已删除 COSName 的 Do 操作指令，导致 Acrobat 解析时因引用失效而触发“页面错误”警告。
更关键的是，原逻辑存在严重不一致性：
- 在资源遍历阶段，代码会 移除所有匹配 _barcodeimg_ 的图像 XObject（循环中多次 removeItem）；
- 但在内容流解析阶段，却仅记录最后一个匹配项的 cosName（qrCodeCosName = propertyName.getName() 被反复覆盖），最终只删除一条 Do 指令。
这造成“资源已删、指令犹存”的状态，是警告的直接诱因。
此外，文件体积从 6.8 MB 增至 8.1 MB，源于 importPage() + 手动重建内容流的低效操作：importPage() 并非浅拷贝，它会复制全部资源（含未使用的字体、图像、Pattern 等），而新生成的 PDStream 未启用压缩，且旧资源未被彻底释放。
✅ 正确修复策略（PDFBox 2.0.27+）
1. 避免跨页资源污染：按需克隆资源
// ✅ 安全做法：为当前页创建独立资源副本 PDResources originalResources = page.getResources(); PDResources clonedResources = new PDResources(); clonedResources.getCOSObject().addAll(originalResources.getCOSObject()); // 浅拷贝字典 page.setResources(clonedResources); // 替换为独占资源
2. 同步清理资源与内容流（单图/多图均适用）
public static boolean removeQRCodeImages(PDDocument doc, PDPage page, String imgUniqueId) throws IOException {
PDResources resources = page.getResources();
List<COSName> toRemove = new ArrayList<>();
// Step 1: 收集所有待删除图像的 COSName（不立即删除！）
for (COSName name : resources.getXObjectNames()) {
if (!resources.isImageXObject(name)) continue;
PDXObject xobj = resources.getXObject(name);
if (!(xobj instanceof PDImageXObject)) continue;
PDImageXObject img = (PDImageXObject) xobj;
if (hasBarcodeMetadata(img)) {
toRemove.add(name);
}
}
// Step 2: 解析内容流，构建过滤后的新指令列表
PDFStreamParser parser = new PDFStreamParser(page);
parser.parse();
List<Object> tokens = parser.getTokens();
List<Object> filtered = new ArrayList<>();
for (int i = 0; i < tokens.size(); i++) {
Object token = tokens.get(i);
if (token instanceof Operator && "Do".equals(((Operator) token).getName())) {
// 检查前一个 token 是否为 COSName 且在待删列表中
if (i > 0 && tokens.get(i - 1) instanceof COSName) {
COSName refName = (COSName) tokens.get(i - 1);
if (toRemove.contains(refName)) {
// 跳过 Do 指令及其引用名（即删除整条绘图指令）
continue;
}
}
}
filtered.add(token);
}
// Step 3: 安全删除资源（此时内容流已无引用）
for (COSName name : toRemove) {
resources.removeXObject(name);
log.debug("Removed QR image resource: {}", name.getName());
}
// Step 4: 写入新内容流（启用压缩）
PDStream newContents = new PDStream(doc);
try (OutputStream os = newContents.createOutputStream(COSName.FLATE_DECODE)) {
ContentStreamWriter writer = new ContentStreamWriter(os);
writer.writeTokens(filtered);
}
page.setContents(newContents);
return !toRemove.isEmpty();
}
private static boolean hasBarcodeMetadata(PDImageXObject img) throws IOException {
COSStream metadata = img.getMetadata();
if (metadata == null) return false;
try (InputStream is = metadata.createInputStream()) {
XMPMetadata xmp = new DomXmpParser().parse(is);
DublinCoreSchema dc = xmp.getDublinCoreSchema();
return dc != null
&& StringUtils.isNotBlank(dc.getTitle())
&& dc.getTitle().contains("_barcodeimg_");
} catch (XmpParsingException e) {
return false; // 元数据解析失败视为非目标图像
}
}3. 关键注意事项
- 禁止直接操作 COSDictionary.removeItem()：应始终通过 PDResources.removeXObject(COSName)，确保内部状态同步；
- 必须先清理内容流，再删除资源：反向操作将导致悬空引用；
- 启用 Flate 压缩：newContents.createOutputStream(COSName.FLATE_DECODE) 可显著减小体积；
- 避免 importPage()：改用 newDocument.addPage(page.copy())（PDFBox 2.0.27+）或直接操作原文档，防止资源冗余复制；
- 验证 PDF 结构完整性：使用 pdfbox-tools 的 PDFDebugger 检查修改后页面的 Resources/XObject 字典与内容流是否匹配。
? 终极建议：对于生产环境，优先考虑 PDFont/PDImageXObject 的逻辑标记替代物理删除——例如将 QR 码图像透明度设为 0 或用空白矩形覆盖，既规避结构风险，又保持 PDF 合规性。物理删除仅适用于明确要求彻底剥离二进制数据的场景。
遵循上述方案，不仅能彻底消除 Adobe Reader 警告，还可使处理后文件体积回归合理范围（通常减少 10%~30%），同时保障跨页资源的安全性与 PDF 规范兼容性。
