故障排查：PDF/A 与 PDF/UA 验证失败

适用范围

这些条目涵盖引擎在确保文档保持在 PDF/A 或 PDF/UA 配置文件范围内时触发的失败。以下条款编号与引擎源代码和异常消息中引用的编号一致。本页仅用自己的表述说明这些条款。引擎只报告它检测到的配置文件失败，并不因此证明文档已经符合规范。权威的符合性结论应来自运行自有规则集的外部验证程序。

症状。 抛出 NextPDF\Security\Exception\IncompatiblePdfAModeException，消息指出 PDF/A 模式下禁止执行加密操作。
可能原因。 该流程同时启用了某个 PDF/A 模式并请求加密。引擎引用 ISO 19005-{1,2,3,4} §6.1.3：PDF/A 文件的 trailer 中不得出现 Encrypt 键。无论调用顺序如何，引擎都会将其作为绝对拒绝处理。
证据/诊断。 getContext() 会返回 pdfa_mode 与 encryption_operation。失败路径测试 tests/SecurityScenarios/PdfAEncryptionRefusalTest.php 会断言：无论 PDF/A 是在加密调用之前还是之后启用，都会触发此拒绝。
解法。
1. 决定文档需要哪种性质：归档符合性，还是加密。
2. 若为归档文档，请移除加密调用。
3. 若为加密文档，请移除 PDF/A 的启用调用。
4. 重新运行该流程。
相关内容。 加密与权限。

症状。 图像导入期间抛出 Pdf14FeatureRejectedException，消息点名 /JPXDecode 或 /JBIG2Decode，并引用条款编号 ISO 19005-1:2005 §6.1.13。
可能原因。 某个 PDF/A-1 构建导入了使用 PDF 1.4 之后才引入的筛选器的图像。PDF/A-1 以 PDF 1.4 功能集为目标，因此 PdfA1FeatureGuard 会拒绝 JPEG 2000（/JPXDecode）与 JBIG2（/JBIG2Decode）。
证据/诊断。 src/Writer/PdfA1FeatureGuard.php 保存这份禁用筛选器清单，并在抛出异常时附上所引用的条款编号。该防护只在 PDF/A-1 配置文件下拒绝；PDF/A-2、PDF/A-3 与 PDF 2.0 配置文件均允许这些筛选器。
解法。
1. 在不使用 JPEG 2000 或 JBIG2 的前提下重新编码源图像，例如另存为基线 JPEG，或改用 Flate 压缩图像。
2. 或者改以 PDF/A-2 或 PDF/A-3 为目标，这两者均允许那些筛选器。
3. 重新运行构建。
相关内容。 符合性参考文档。

症状。 某个 PDF/A 构建在字体验证步骤失败；外部验证程序报告存在未嵌入的字体。
可能原因。 有字符使用了程序未嵌入的字体来绘制。PDF/A 管理器合约规定所有字体都必须嵌入；任何未嵌入的 standard-14 字体都不允许使用。
证据/诊断。 src/Contracts/PdfAManagerInterface.php 声明了 validateFont(string $fontName, bool $isEmbedded, array $cmapForward)，并注明规则「所有字体都必须嵌入；任何未嵌入的 standard 14 字体一律不允许。」具体的强制执行逻辑随 nextpdf/pro 一并发布。
解法。
1. 找出报告为未嵌入的字体。
2. 为该字体配置一份可嵌入的字体文件，而不是依赖内置的 standard-14 字体。
3. 若要了解 Base 14 替代的相互作用，请阅读「字体与标记」条目。
4. 重新运行构建并重新验证。
相关内容。 字体与标记。

症状。 某个 PDF/A 构建在 JavaScript 验证步骤失败，或外部验证程序报告存在 JavaScript 动作。
可能原因。 文档或某个表单字段包含 JavaScript 动作。PDF/A 管理器合约引用 ISO 19005-4:2020 §6.7.1，该条禁止 JavaScript 动作。
证据/诊断。 PdfAManagerInterface::validateNoJavaScript() 与 validateNoJavaScriptActions() 均在其文档块中引用 §6.7.1。
解法。
1. 从文档或表单字段移除该 JavaScript 动作。
2. 若该动作对功能必不可少，则这份文档无法制作成 PDF/A；请为该用途另行生成一份非 PDF/A 版本。
3. 重新运行构建并重新验证。
相关内容。 符合性参考文档。

症状。 启用标记后构建的文档未被识别为 PDF/UA-2，或缺少 PDF/UA-2 声明。
可能原因。 结构树为空。对于不包含任何已加标记结构的文档，引擎不会声明 PDF/UA-2，因为空结构树无法满足该配置文件。
证据/诊断。 失败路径测试 tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php 会断言：空的已加标记文档不会声明 PDF/UA-2。这是引擎明确定义的行为，并非缺陷。
解法。
1. 确认内容通过标记路径输出，使结构树被填入内容，而不是保持为空。
2. 验证标记内容序列确实映射到结构元素。
3. 重新运行建置，并重新检查 PDF/UA-2 状态。
相关内容。 字体与标记。

症状。 因语言项缺失，或语言标签无效，导致 PDF/UA-2 检查失败。
可能原因。 文档或某个结构元素缺少有效语言。PDF/UA-2 要求声明自然语言；缺失或格式错误的 Lang 值无法通过严格检查。
证据/诊断。 失败路径测试 tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php 会验证这一严格语言要求。语言标签会通过 src/Accessibility/Bcp47Validator.php 验证；无效标签会引发 src/Accessibility/InvalidBcp47TagException.php。
解法。
1. 将文档级语言设为有效的 BCP-47 标签，例如 en-US 或 zh-Hant-TW。
2. 若某段内容使用不同语言，请在对应结构元素上设置语言。
3. 重新运行建置并重新验证。
相关内容。 字体与标记。

此处所述的 PDF/A 与 PDF/UA 拒绝都由引擎内部产生。它们与外部验证程序的结论彼此独立，也不会取代外部结论；请运行 veraPDF 等验证程序来获取权威结果。
具体的 PDF/A 必要对象写入器（XMP 元数据流、包含 ICC 配置文件的输出意图）会在运行阶段从 nextpdf/pro resolve（解析）取得。若只安装 core 包，这些对象不会输出；仅含 core 的构建并不是完整的 PDF/A 生成器。
加密拒绝是绝对的，且与顺序无关；即使在加密调用之后才启用 PDF/A，仍会引发此拒绝。