解决ZUGFeRD Mustang校验器字体引用错误 (PDF/A)

2025-03-05 22:37:15

ZUGFeRD Mustang Validator 字体引用错误解决之道

碰上 ZUGFeRD Mustang Validator 报字体引用错误了？别慌，这问题挺常见的，咱们来捋一捋。

问题

在使用 ZUGFeRD 标准生成电子发票（PDF/A 格式）时, 用 Mustang Validator (版本 2.16.2) 校验生成的 PDF 文件, 会出现以下错误：

<validation ...>
  <pdf>
    ...
    <TestAssertion ... message=A content stream refers to resource(s) F1 not defined in an explicitly associated Resources dictionary .../>
    ...
  </pdf>
  ...
</validation>

这个错误信息表明，PDF 的内容流引用了未在关联的资源字典中定义的资源 (特别是字体 F1)。把 PDF 文件中页眉的 "Blatt: 1 von 1" 部分去掉, 校验错误就消失了。这说明问题可能出在页眉对字体的引用上。

问题原因

错误的核心在于违反了 PDF/A-3 (ISO 19005-3:2012, 6.2.2) 和 PDF 规范 (ISO 32000-1:2008, 7.8.3)。简单说，就是 PDF/A-3 要求，如果内容流 (Content Stream) 中使用了外部对象 (比如图像、字体), 就必须显式地关联一个资源字典 (Resources Dictionary)。你遇到的问题，多半是页眉部分使用了字体，但是这个字体没有正确地在资源字典中声明。

Mustang Validator 严格遵守 PDF/A 标准, 会检查这些细节。

解决方案

下面提供几种解决方案, 核心都是确保字体资源被正确引用:

1. 检查字体嵌入

最基本的是确保所有使用的字体都已嵌入到 PDF 文件中。PDF/A 标准要求所有字体都必须嵌入, 不能依赖系统字体。

原理： 嵌入字体能保证文档在任何系统上显示一致，符合 PDF/A 的长期归档要求。
操作：
- 如果使用 PDFBox 生成 PDF，确保在创建字体对象时设置了正确的嵌入标志。
- 可以用 PDF 编辑工具（如 Adobe Acrobat）打开 PDF，检查字体是否已嵌入（文件 -> 属性 -> 字体）。
- 可以看下PDType1Font这里相关的字体设置选项。
代码示例 (PDFBox)：

// 假设已经有了一个 PDPageContentStream 对象 contentStream
PDFont font = PDType1Font.HELVETICA_BOLD; // 或其他已嵌入的字体
contentStream.setFont(font, 12);
contentStream.beginText();
contentStream.newLineAtOffset(100, 700);
contentStream.showText("Blatt: 1 von 1");
contentStream.endText();

// ... 其他代码 ...

// 确保所有资源都已正确设置

2. 显式添加资源字典 (Resources Dictionary)

如果确认字体已嵌入，但 Mustang Validator 仍然报错，那就需要手动检查并添加资源字典。

原理: 资源字典是一个包含了内容流所使用的各种资源（字体、图像等）的字典对象。它通常与页面 (PDPage) 或 XObject 关联。
操作:
1. 找到生成页眉内容流的代码。
2. 获取或创建与该内容流关联的资源字典。
3. 将使用的字体添加到资源字典中。
代码示例 (PDFBox):

// 假设 page 是 PDPage 对象, font 是已经嵌入的字体
PDResources resources = page.getResources();
if (resources == null) {
    resources = new PDResources();
    page.setResources(resources);
}

// 将字体添加到资源字典, 'F1' 是字体的名称, 可以自定义, 但要与内容流中的引用一致
resources.put(COSName.getPDFName("F1"), font);

// ... 在 contentStream 中使用字体 ...
// contentStream.setFont(font, 12);  // 注意: 如果已经在资源字典里设置了, 这里可以省略
// contentStream.showText("Blatt: 1 von 1");

3. 使用 XObject

对于复杂的布局或者重复使用的内容 (比如页眉页脚), 可以考虑使用 XObject。

原理: XObject (Form XObject) 是一种独立的、可重用的内容块。它有自己的资源字典, 可以包含文本、图像等。
操作:
1. 创建一个包含页眉内容的 XObject。
2. 在 XObject 的资源字典中添加字体。
3. 在主页面的内容流中引用该 XObject。
进阶： 如果你有更复杂的逻辑处理字体，XObject 可以保证更清晰的代码结构。
代码示例 (PDFBox):

// 创建 XObject
PDFormXObject headerXObject = new PDFormXObject(new PDStream(pdf));
headerXObject.setResources(new PDResources());
headerXObject.setBBox(new PDRectangle(0, 0, 500, 50)); // 设置 XObject 的大小

// 获取 XObject 的 content stream
PDPageContentStream xObjectContentStream = new PDPageContentStream(pdf, headerXObject);

// 添加字体到 XObject 的资源字典
headerXObject.getResources().put(COSName.getPDFName("F1"), font);

// 在 XObject 的 content stream 中绘制内容
xObjectContentStream.setFont(font, 12);
xObjectContentStream.beginText();
xObjectContentStream.newLineAtOffset(10, 20);
xObjectContentStream.showText("Blatt: 1 von 1");
xObjectContentStream.endText();
xObjectContentStream.close();

// 在页面的 content stream 中引用 XObject
PDPageContentStream pageContentStream = new PDPageContentStream(pdf, page, PDPageContentStream.AppendMode.APPEND, true, true);
pageContentStream.drawForm(headerXObject);
pageContentStream.close();

4. 检查 XML 附件

尽管错误信息指向字体,但 ZUGFeRD 规范中，XML 附件也可能影响校验结果.

原理： 检查确认你添加 ZUGFeRD XML 的部分有没有疏漏。
操作： 仔细检查你提供的 attachFile 方法的实现，确保:
- AFRelationship 设置正确 (应为 "Alternative")。
- Subtype 设置正确 (应为 "text/xml")。
- 文件名、等信息符合 ZUGFeRD 规范。
- 按照规范操作 COSName.EF, COSName.UF等.

安全建议

最小权限原则: 在处理 PDF 文件时, 尽量使用最小权限的代码。避免使用不必要的、可能引入安全漏洞的 API。
输入验证: 对所有外部输入 (包括 XML 数据) 进行严格的验证和清理, 防止注入攻击。
定期升级 PDFBox 至最新版本.
这些方法综合运用, 应该可以解决 Mustang Validator 的字体引用错误。解决这个问题的关键是细心, 耐心理解 PDF 结构和 PDF/A 规范。