故障排查知识库

这套知识库涵盖什么

这套知识库会把观察到的失败现象映射到其成因与解法。每一条目都以引擎自身的异常类、失败路径测试与源码防护为依据，而不是臆测。如果引擎中没有任何代码路径会产生某个失败，这套知识库就不会凭空编造相应条目。

这套知识库包含四个主题页面：

• 签名验证 —— 签名无效、证书链不完整、撤销状态未知和时间戳失败。
• PDF/A 与 PDF/UA 验证 —— 缺少输出意图、内容未标记、缺少语言和嵌入字体失败。
• 字体与标记 —— 找不到字体、子集化、CJK 覆盖范围和结构树问题。
• 加密与权限 —— 解密失败和权限标志的边界条件。

如何阅读一则条目

每一则条目都包含五个部分：

1. 症状 —— 你观察到的现象：一个异常类、一段消息片段，或下游验证器的判定结果。
2. 可能成因 —— 引擎报告的、出现在你的输入或配置中的条件。
3. 证据/诊断 —— 如何确认成因。这里会指出确切的异常类、getContext() 字段，或能展示该行为的测试，让你可以查证，而不是猜测。
4. 解法 —— 按有序流程列出排除成因的步骤。
5. 相关 —— 后续应阅读的模块参考页或同类条目。

按异常类型识别失败

NextPDF 使用 PHP 类来识别错误，而不是字符串错误代码。异常类中不存在 NPDF-#### 这类常量。请捕获叶节点异常，以便做出有针对性的响应，并读取 ContextAwareExceptionInterface::getContext() 来获取结构化诊断字段。基类型是 NextPDF\Exception\NextPdfException；安全性失败还会额外使用 NextPDF\Security\Exception\SecurityException。

如需完整的层次结构与捕获顺序规则，请阅读异常参考页。

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

范围与边界

这套知识库描述的是引擎内部的失败检测与报告。它并不描述像 veraPDF 或 callas 这类外部验证器的一致性判定结果；这些工具使用各自的规则集。当引擎为了让文档保持在某个配置文件范围内而拒绝某项操作时 —— 例如在 PDF/A 下拒绝加密 —— 相关条目会引用适用条款，以及执行该限制的异常。

另请参阅

• 异常参考页 —— 完整层次结构、捕获顺序和 getContext() 契约
• 一致性参考页 —— PDF/A、PDF/UA、PDF/X 配置文件检查器

词汇表：上下文感知异常