繪製與 I/O 錯誤

適用範圍

下列條目涵蓋在以下過程中所拋出的繪製與輸入/輸出（I/O）例外狀況：HTML 管線排版內容、分頁媒體解析器指派頁面幾何、文字定形器處理複雜文字、排版階段斷行、寫入器序列化文件、讀取器解析既有 PDF，以及中介資料階段讀取 Extensible Metadata Platform（XMP）封包。

下方出現兩種基底階層，而其差異決定了你在 catch 之後能讀取哪些診斷資料：

• NextPdfException 實作 ContextAwareExceptionInterface::getContext(): array。基底實作回傳空陣列；子類別只有在覆寫 getContext() 時才攜帶結構化的鍵。未覆寫它的子類別仍會透過 public readonly 屬性揭露其資料。
• 此處有數個類別直接繼承 PHP 的 RuntimeException。它們不具脈絡感知能力，也沒有 getContext() 方法；請改讀它們的 getMessage() 與任何公開屬性。

每個條目都會具名說明確切的類別、觸發條件，以及它所攜帶的脈絡鍵或公開屬性，以及復原路徑。

HTML 版面配置與分頁媒體

UnsplittableContentException

• 何時被拋出。 當被標記為 break-inside: avoid 的內容（一個斷行限制為 Avoid 的表格儲存格）其量測高度超出單一頁面的可用高度時，HTML 版面配置引擎會拋出它。引擎無法同時滿足避免斷行的限制與頁面邊界，因此寧可失敗也不悄悄溢出。
• 攜帶的資料。 繼承 NextPdfException，但未覆寫 getContext()，因此 getContext() 回傳空陣列。診斷資料在 public readonly 屬性上：gridRow（int）、gridCol（int）、contentHeight（float，點）與 pageHeight（float，點）。訊息會具名說明儲存格座標與兩個高度。
• 解法。 移除出問題儲存格上的 break-inside: avoid 限制、縮減該儲存格的內容使其能容於一頁，或增大頁面尺寸或縮減其邊界，使可用高度能容納內容。

BudgetExceededException

• 何時被拋出。 當架構決策記錄 ADR-020 所定義的四個資源預算層級之一遭突破，而呼叫端選擇了硬性失敗、而非軟性退回時，保留模式版面配置基元會拋出它。預設路徑不會拋出：ContainerLayout::acceptChild() 回傳 false，呼叫端退回到區塊版面配置，並發出一則警告。此例外狀況保留給組態時的驗證，以及斷言確切突破元組的測試使用。這些層級分別是 per-child（一個被擷取的子串流超出其上限）、per-container（Tier 1 節點計數預算）、per-document（版面配置遍歷或巢狀深度預算），以及 global（SDK 全域的 256 MB 峰值常駐集大小上限）。
• 攜帶的資料。 覆寫 getContext()，回傳一個由 application performance monitoring（APM）工具消費的穩定八鍵形狀：budgetTier、exceededValue、budgetLimit、containerType、phase、breachOrigin、captureSize 與 processedItemCount。前四個鍵是原始 v1.0.0 的子集，且一律會填充；後四個在建構式未提供它們時預設為 null 或 0。getCausalWarningCode() 會把（層級、容器型別）元組對應到軟性退回路徑本會發出的 WarningCode。
• 解法。 對於組態突破，請把所請求的值降回已載明的範圍（例如保留節點預算透過 Config::withRetainedNodeBudget() 接受 5,000 到 100,000）。對於內容突破，請縮減容器巢狀或節點數量，或仰賴預設的軟性退回到區塊版面配置，而非選擇硬性失敗的介面。

UnsupportedNamedPageException

• 何時被拋出。 當文件宣告一個具名的 @page <ident> { … } 規則（透過 page: <ident> 屬性綁定到內容）時，分頁媒體階段會失敗即關閉地拋出它。來自 CSS Paged Media Level 3 §3.4 與 Level 4 §3.2 的具名頁面——包括 :first、:left、:right 與 :blank 偽類別，以及具名的 size: 與 rotate: 覆寫——會被解析，但沒有任何生產版面配置路徑會消費它們。引擎寧可拒絕，也不發出捨棄該規則本會產生的、悄悄出錯的預設分頁。
• 攜帶的資料。 覆寫 getContext()，回傳 page_names（依原始順序、觸發失敗的相異 ident 清單）、has_size_override（bool）、has_rotate_override（bool）與 has_pseudo_classes（bool）。相同的值也會揭露在 pageNames、hasSizeOverride、hasRotateOverride 與 hasPseudoClasses 公開屬性上。
• 解法。 移除具名的 @page <ident> 規則與任何 page: <ident> 綁定，並透過受支援的未具名 @page { … } 規則及其偽類別形式來表達所欲的幾何。或者，釘選到一個會帶來完整具名頁面版面配置支援的未來版本。

排版與文字定形

IcuRequirementException

• 何時被拋出。 當文字分段需要 International Components for Unicode（ICU）斷行迭代器，但 require-ICU 政策已生效（NEXTPDF_REQUIRE_ICU=1）、同時 ext-intl 擴充功能與 IntlBreakIterator 卻不可用時，文字分段會拋出它。
• 攜帶的資料。 直接繼承 RuntimeException，因此它不具脈絡感知能力，也沒有 getContext()。它是同一程式碼路徑先前所拋出通用例外狀況的嚴格細化版本，因此既有的 catch (\RuntimeException) 處理器仍可正常運作。
• 解法。 安裝並啟用 ext-intl，使 ICU 斷行迭代器可用；或在 require-ICU 政策並非強制的情況下，取消設定 NEXTPDF_REQUIRE_ICU 以退回到非 ICU 的分段器。

ScriptShaperException

• 何時被拋出。 這是文字定形服務提供者介面（SPI）的基底例外狀況。它今日不會被直接拋出；改為拋出具體的子型別。請攔截此型別，以在同一處理任何定形失敗。
• 攜帶的資料。 直接繼承 RuntimeException；不具脈絡感知能力，無 getContext()。
• 解法。 依具體子型別分支處理。當前版本所隨附唯一的子型別請見下方的 NotYetImplementedException。

NotYetImplementedException

• 何時被拋出。 對於具體定形被延後實作的文字（蒙古文與藏文），每個佔位用的文字定形器都會從其 shape() 主體拋出它。定形 SPI 接縫已架構就緒，但實際的定形仍待一份經母語人士驗證的測試夾具。寧可拋出例外狀況、也不採取靜默 no-op，是為了在執行階段揭露意外的生產接線，而非把未定形的文字發送進一份宣稱具備標記式無障礙能力的 PDF。
• 攜帶的資料。 繼承 ScriptShaperException（因此也繼承 RuntimeException），所以它不具脈絡感知能力，也沒有 getContext()。診斷資料在其 public readonly 屬性上：bcp47LanguageTag（該文字段的 BCP-47 標籤，例如 mn-Mong 或 bo-Tibt）與 missingCapability（該實作所缺少的具體能力）。訊息會同時包含兩者。
• 解法。 不要在生產中把未實作文字的文字段交由定形器處理。請在上游偵測語言標籤，並退回到不同的繪製路徑，或釘選到一個會帶來受影響文字定形支援的未來版本。

寫入器輸出設定檔與加密

Pdf14FeatureRejectedException

• 何時被拋出。 當文件含有在 PDF 1.4 輸出設定檔（ISO 19005-1:2005 / PDF/A-1，禁止較後期 PDF 版本所引入的構造）下被禁止的功能時，寫入器會拋出它。
• 攜帶的資料。 繼承 NextPdfException，但未覆寫 getContext()，因此 getContext() 回傳空陣列。診斷資料在其 public readonly 屬性上：feature（被拒絕的功能名稱）、reason（為何被禁止）與 isoClause（ISO 子句參照）。訊息會把三者合併。
• 解法。 移除被拒絕的功能，或以一個 PDF 1.4 相容的等效項取代之，或改以一個允許該功能的較高輸出設定檔為目標。

Pdf20FeatureRejectedException

• 何時被拋出。 當文件含有在嚴格 PDF 2.0 輸出設定檔下被禁止的功能時，寫入器會拋出它。ISO 32000-2:2020 廢止了 PDF 1.7 仍允許的構造——最值得注意的是 Standard 14 Type 1 字型（§9.6.2），它們在符合規範的 PDF 2.0 文件中必須被內嵌。
• 攜帶的資料。 與 Pdf14FeatureRejectedException 的形狀相同：繼承 NextPdfException，未覆寫 getContext()（回傳空陣列），並把 feature、reason 與 isoClause 揭露為 public readonly 屬性。
• 解法。 補救被拒絕的功能——例如，內嵌 base 14 字型——或在有逃生口的地方採用已載明的逃生口（對於未內嵌的 base 14 字型，使用 Document::allowNonEmbeddedBase14()）。

PublicKeyEncryptionUnsupportedException

• 何時被拋出。 當文件的 encryptionMode 為 pubkey（公鑰收件人清單）、但寫入器端的公鑰串流主體加密派發尚未接線時，PdfWriter::build() 會在進入點拋出它。事先拒絕可避免悄悄發出一份呼叫端誤以為已加密的未加密 PDF。
• 攜帶的資料。 直接繼承 RuntimeException，因此它不具脈絡感知能力，也沒有 getContext()。它是同一處先前所拋出通用例外狀況的嚴格細化版本，因此既有的 catch (\RuntimeException) 處理器仍可正常運作。
• 解法。 改用受支援的加密模式（以密碼為基礎的加密），而非公鑰收件人清單，或釘選到一個會帶來公鑰加密支援的版本。拋出此例外狀況時，不要把輸出當成已加密。

讀取器與中介資料輸入

UnsupportedPdfStructureException

• 何時被拋出。 當輸入 PDF 落在其受支援範圍之外時，物件圖讀取器會失敗即關閉地拋出它。讀取器支援傳統的交互參照表（ISO 32000-2:2020 §7.5.4）、交互參照串流（§7.5.8）、以物件串流壓縮的物件（§7.5.7）、多修訂的 /Prev 鏈（§7.5.6），以及透過 /XRefStm 的混合參照檔（§7.5.8.4）。任何落在該範圍之外者都會揭露此例外狀況，而非進行部分或臆測的解析。具名建構式對應到各個原因情形：encrypted()、damagedCrossReference()、cyclicReferenceChain()、nonConformantObjectStream()、irresolvableObjectCollision()、truncatedFile() 與 crossReferenceOffsetOutOfBounds()。
• 攜帶的資料。 直接繼承 RuntimeException，因此它不具脈絡感知能力，也沒有 getContext()。它揭露一個型別為 UnsupportedPdfStructureReason（一個列舉）的 public readonly reason 屬性，讓呼叫端可在不解析訊息的情況下依精確的分類分支；可選的 detail 字串與 previous throwable 可能會添加有界、非敏感的脈絡。預設訊息是該原因的不洩漏摘要。
• 解法。 依 reason 分支處理。對於 EncryptedDocument，在讀取前先執行解密步驟，因為解密在讀取器的範圍之外。對於 DamagedCrossReference、TruncatedFile 或 CrossReferenceOffsetOutOfBounds，把該檔案當作格式錯誤或不完整，並重新取得或修復來源。對於 CyclicReferenceChain、NonConformantObjectStream 或 IrresolvableObjectCollision，輸入違反了結構模型，無法照原樣讀取。

PacketTooLargeException

• 何時被拋出。 當內嵌的 XMP 封包超出所設定的位元組上限時，串流式 XMP 中介資料讀取器會拋出它。它是針對實體展開與二次膨脹式輸入的防禦性護欄（以 128 MB 的峰值上限對抗 GB 等級的內嵌 XMP）。
• 攜帶的資料。 繼承 NextPdfException，但未覆寫 getContext()，因此 getContext() 回傳空陣列。診斷資料在其 public readonly 屬性上：byteCount（觀測到的位元組數）與 cap（所設定的上限，以位元組為單位）。訊息會回報兩者。
• 解法。 把超大的中介資料當作惡意或格式錯誤，加以拒絕或略過。若某份合法文件確實需要更大的封包，請刻意提高所設定的上限，並權衡此護欄所要防範的記憶體耗盡風險。

另請參閱

• 錯誤參考索引
• 字型與標記疑難排解 — 針對 NotYetImplementedException、ScriptShaperException 與 IcuRequirementException 的症狀。
• PDF/A 與 PDF/UA 驗證疑難排解 — 針對 Pdf14FeatureRejectedException 與 Pdf20FeatureRejectedException 的症狀。
• 加密與權限疑難排解 — 針對 PublicKeyEncryptionUnsupportedException 與讀取器的 EncryptedDocument 原因。