疑難排解知識庫

這套知識庫涵蓋什麼

這套知識庫會把觀察到的失敗對應到成因與解法。每一則條目都以引擎自身的例外類別、失敗路徑測試與原始碼防護為依據，而不是臆測。如果引擎沒有任何程式碼路徑會產生某個失敗，這套知識庫就不會憑空建立該失敗條目。

這套知識庫包含四個主題頁：

簽章驗證 —— 簽章無效、憑證鏈不完整、撤銷狀態未知，以及時間戳記失敗。
PDF/A 與 PDF/UA 驗證 —— 缺少輸出意圖、內容未標記、缺少語言，以及內嵌字型失敗。
字型與標記 —— 找不到字型、子集化、CJK 涵蓋範圍，以及結構樹問題。
加密與權限 —— 解密失敗，以及權限旗標的邊界。

如何閱讀一則條目

每一則條目都分成五個部分：

症狀 —— 你觀察到的現象：可能是一個例外類別、一段訊息片段，或下游驗證器的判定結果。
可能成因 —— 引擎回報，且出現在你的輸入或組態中的條件。
證據/診斷 —— 如何確認成因。這裡會指出確切的例外類別、getContext() 欄位，或能展示該行為的測試，讓你可以查證，而不是猜測。
解法 —— 排除成因的步驟，會以有序程序呈現。
相關 —— 接下來應閱讀的模組參考頁或同類條目。

依例外類型辨識失敗

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 設定檔檢查器

詞彙表：情境感知例外