compat-legacy 疑難排解

概覽

大多數遷移問題都落在少數幾種類型之中。以下每一項都會列出症狀、原因與修正方式。不確定特定方法的行為時，請參閱 /integrations/tcpdf-compat/method-coverage/ 以及儲存庫內的權威對照表 docs/TCPDF_COVERAGE.md。

程序過去會在 PDF 錯誤時停止；現在會擲出例外

症狀。 先前在繪製失敗時會停止的程式碼，現在會擲出未被攔截的 RuntimeException，導致該請求或工作回報錯誤。

原因。 舊版 TCPDF 的 Error() 會呼叫 die()。轉接器改為擲出 RuntimeException，這是刻意的設計，讓失敗能被觀察到。

修正。 將繪製入口包在 try/catch 中，並將例外對應到你的錯誤處理契約。請勿恢復 die() 的行為。請參閱 /integrations/tcpdf-compat/production-usage/ § 失敗處理。

new \TCPDF() 仍然解析到真正的 TCPDF 函式庫

症狀。 你已啟用 LegacyBootstrap::enableAliases()，但輸出看起來仍像舊版 TCPDF，或行為沒有改變。

原因。 只有在尚未存在同名類別時，enableAliases() 才會註冊別名。若 tecnickcom/tcpdf 仍可被自動載入，且其中的 \TCPDF 先載入，別名就會被略過，你的程式碼也會繼續使用舊版 TCPDF。

修正。 在遷移期間，請優先採用逐檔明確匯入（use NextPDF\Compat\Tcpdf\TCPDF;），避免每個呼叫處產生歧義。一旦稽核通過，便移除 tecnickcom/tcpdf（請參閱 /integrations/tcpdf-compat/migration/ 階段 5）。請勿在同一個程序中同時執行兩套函式庫並啟用全域別名。

某個方法「能運作」，但我傳入的參數被忽略了

症狀。 呼叫成功並產生 PDF，但你傳入的某個選項（圖片連結、對齊、DPI、書籤顏色……）並未生效。

原因。 該方法屬於靜默忽略集合。它為了原始碼相容性而接受該參數，接著便將其捨棄。這是文件明載的行為，並非錯誤；請參閱 /integrations/tcpdf-compat/method-coverage/ §2。

修正。 執行嚴格模式稽核，找出每一個這類呼叫：

examples/troubleshoot-strict.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

接著捨棄該參數，或依 /integrations/tcpdf-compat/migration/ 階段 4 所示，改用現代 API（$pdf->getDocument()）重新表達。

MultiCell() 的回傳值永遠是 1

症狀。 依據 MultiCell() 回傳值進行分支判斷的程式碼（例如用來計算已使用的高度或行數），行為不正確。

原因。 轉接器的 MultiCell() 回傳的是相容性佔位值 1，而非實際繪製的 cell/line 數量。Write() 同樣回傳 0。

修正。 請勿依據這些回傳值進行分支判斷。若你需要繪製後的高度，請改用 getStringHeight() / getNumLines() 計算，或將該邏輯移至現代 API。

setPDFVersion('1.4') 並未產生 PDF 1.4 檔案

症狀。 你要求了較舊的 PDF 版本，但輸出仍是 PDF 2.0。

原因。 輸出永遠是 PDF 2.0（ISO 32000-2）。setPDFVersion() 屬於不適用集合；轉接器會發出通知並繼續執行。

修正。 移除該呼叫。若某個下游使用方需要較舊的 PDF 版本，請在該使用方端另行處理其限制；轉接器無法降版輸出。

setSignature() 沒有任何作用——PDF 並未被簽署

症狀。 你以憑證呼叫了 setSignature()；輸出的 PDF 卻未包含簽章。

原因。 在此轉接器中，setSignature() 並未於核心引擎實作。在預設模式下它是無動作；在嚴格模式下則會擲出例外。

修正。 簽署需要商業版 NextPDF 與現代簽章 API。請參閱 /integrations/tcpdf-compat/security-and-operations/ § 數位簽章。請勿期待舊版的 setSignature() 呼叫能簽署任何內容。

Output() 損毀了我的 HTTP 回應或 worker 輸出

症狀。 HTTP 回應中出現二進位亂碼，或 worker 記錄被 PDF 位元組污染。

原因。 你在自行控制回應的情境中，使用了會寫入輸出通道的輸出目的地（I/D）。轉接器並不會像舊版 TCPDF 那樣將內容回顯到你的緩衝區，但 I/D 仍會驅動引擎輸出。

修正。 在你自行控制的 worker 與處理器中，使用 Output($path, 'F') 寫入檔案，或使用 Output($name, 'S') 取得位元組並自行輸出。目的地對應關係（不分大小寫、已去除空白）在 tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php 中以斷言驗證：

代碼	回傳	副作用
S	PDF 位元組（%PDF…）	無
F	空字串	寫入檔案
E	base64 MIME 主體	無
FI / FD	空字串	寫入檔案，接著進行引擎輸出
I / D / 未知	空字串	引擎輸出（內嵌/下載）

切換後逐位元組比對的 PDF 斷言失敗

症狀。 比對原始 PDF 位元組的快照測試大範圍失敗。

原因。 此引擎是一套獨立的 PDF 2.0 實作。對於委派的方法，可見輸出是相容的，但位元組並不相同。這是預期的情況。

修正。 重新建立基準檔，改為針對繪製內容（擷取出的文字）、結構（頁數、頁面尺寸）或冒煙檢查（str_starts_with($bytes, '%PDF')）進行斷言。請參閱 /integrations/tcpdf-compat/migration/ 階段 4。

某個舊版 K_* / PDF_* 常數的值不正確

症狀。 你透過常數設定的自訂路徑或預設值並未生效。

原因。 只有在常數尚未被定義時，轉接器才會自動定義它，而且是在首次建構時進行。若你的 define() 在第一個轉接器被建構之後才執行，轉接器的預設值就已經取得優先權。

修正。 在任何轉接器實例被建立之前，於你的啟動程序中定義所有自訂的 K_* / PDF_* 常數。請參閱 /integrations/tcpdf-compat/configuration/ § 設定解析順序。

建構時發現引擎版本不相符

症狀。 在更新相依套件後，建構失敗或行為不如預期。

原因。 此轉接器需要 nextpdf/core ^3.0。若解析出的 core 版本落在該範圍之外，則不受支援。

修正。 執行 composer show nextpdf/core，並將引擎釘選在 ^3.0。請參閱 /integrations/tcpdf-compat/install/ § 驗證引擎版本。

診斷快速參考

問題	查閱位置
方法 X 在這裡實際上做了什麼？	/integrations/tcpdf-compat/method-coverage/、docs/TCPDF_COVERAGE.md
我的哪些呼叫會遺失參數？	嚴格模式稽核（本頁；/integrations/tcpdf-compat/migration/）
為什麼程序沒有在錯誤時停止？	/integrations/tcpdf-compat/security-and-operations/ § 強化行為
為什麼輸出沒有被簽署/不是 PDF/A？	/integrations/tcpdf-compat/security-and-operations/
別名與明確匯入的衝突	本頁；/integrations/tcpdf-compat/boot-and-discovery/

另請參閱

• /integrations/tcpdf-compat/migration/ — 可避免上述大多數問題的分階段遷移
• /integrations/tcpdf-compat/method-coverage/ — 各方法的行為參考
• /integrations/tcpdf-compat/boot-and-discovery/ — 別名註冊與衝突避免
• docs/TCPDF_COVERAGE.md — 權威的涵蓋對照表