NextPDF Backport Builder 疑難排解
這是建構工具，而不是執行階段相依套件。本頁列出的每個徵狀，都是維護者或 CI 主機上的建構期狀況，不會在下游應用程式中出現。
建構流程會依序執行五個階段。一旦遇到第一個失敗點就會停止，並印出階段名稱與訊息。請先查看該階段，再到下方對照原因。這些階段包括合併來源、執行 Rector 降級、產生 composer.json、複製靜態資產，以及驗證輸出。已對照 scripts/build.php（run() 與 step()）驗證。
階段：合併來源
標題為「階段：合併來源」的區段「找不到來源儲存庫 ''，位置：」
標題為「「找不到來源儲存庫 ''，位置：」」的區段合併流程會在複製前驗證每一個預期的來源儲存庫；若有缺漏，會以該儲存庫名稱與路徑中止。PHP 8.1 目標預期 nextpdf、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter，以及在納入 Pro 時的 nextpdf-Pro。PHP 7.4 目標僅預期 nextpdf。已對照 scripts/merge-sources.php（run() 驗證迴圈、__construct() 儲存庫對應表）驗證。
解決方式：將這些儲存庫簽出成同層目錄，放在傳入 --source-dir 的路徑底下，並使用上述確切的目錄名稱。試跑（dry-run）會列出它將讀取的每一個儲存庫。可在完整建構前用它確認目錄配置。
階段：執行 Rector 降級
標題為「階段：執行 Rector 降級」的區段Rector 以非零結束碼結束
標題為「Rector 以非零結束碼結束」的區段協調器會回報 Rector failed on <label> (exit code: N) 並停止。此標籤會指出失敗階段：public package、pro package、enum pre-processing 或 full downgrade。已對照 scripts/build.php（runRectorPass()）驗證。
列舉預設值上的預設參數解析器當機（PHP 7.4）
標題為「列舉預設值上的預設參數解析器當機（PHP 7.4）」的區段這正是 PHP 7.4 目標採用雙階段流程的原因。Rector 的預設參數值解析器遇到作為建構子提升參數預設值的列舉案例時會當機。第 1 階段（rector-php74-enums.php）會先把列舉轉換為常數清單類別。接著第 2 階段的完整流程就不會再看到列舉案例預設值。若你略過協調器，直接針對含有列舉的原始碼執行完整的 PHP 7.4 設定，就會遇到這個當機。已對照 scripts/build.php（runRector() 註解與雙階段順序）與 rector/config/rector-php74-enums.php 驗證。
基準測試指令碼使 Rector 當機
標題為「基準測試指令碼使 Rector 當機」的區段rector-php81.php 與 rector-php74.php 會略過 */tests/Benchmark/*。這些指令碼參考了 Rector 無法解析的外部 PDF 函式庫，因而讓預設參數解析器當機。若有基準測試路徑被處理，表示略過用的萬用字元樣式缺漏，或路徑與預期不同。已對照 withSkip() 呼叫驗證。
MHASH_XXH* 當機（PHP 7.4）
標題為「MHASH_XXH* 當機（PHP 7.4）」的區段rector-php74.php 會略過 DowngradeHashAlgorithmXxHashRector。這條內建規則遇到 xxHash 常數時會當機。原始碼並未使用 xxHash，因此略過是安全的。已對照 rector/config/rector-php74.php（withSkip()）驗證。
階段：Rector 後續修正（僅 PHP 7.4）
標題為「階段：Rector 後續修正（僅 PHP 7.4）」的區段這些修正會在兩個階段之間執行，用來改寫列舉轉類別規則留下的樣式。若 PHP 7.4 輸出仍牽涉到 EnumClass::Case->value、->name、以實例方法形式呼叫的原列舉方法，或在未解析型別上使用具名引數的剖析錯誤，代表修正未比對到該樣式。clone-with 限制在此同樣適用：引數比對並非遞迴，因此帶有巢狀括號的覆寫值不會被改寫。已對照 scripts/build.php（postProcessFixups()、fixEnumMethodCallSites()、applyFixups()）與 rector/rules/DowngradeCloneWithRector.php（記載於文件的限制）驗證。
階段：產生 composer.json
標題為「階段：產生 composer.json」的區段這個階段會把處理過的 src/ 與 tests/ 從建構暫存目錄移到輸出目錄，接著寫出產生的 composer.json。此處的失敗幾乎都是檔案系統狀況所致：輸出目錄不可寫入，或因為 Rector 沒有產出任何內容而導致建構暫存樹缺漏。已對照 scripts/build.php（adjustComposer()、moveTree()）驗證。
階段：複製靜態資產
標題為「階段：複製靜態資產」的區段這個階段會從核心來源儲存庫複製 LICENSE，並寫出產生的 CHANGELOG.md。當授權檔不存在時，複製會靜默略過，建構仍會繼續；變更記錄則一律寫出。此處的失敗代表輸出目錄在建構期間變成不可寫入。已對照 scripts/build.php（copyStaticAssets()）驗證。
階段：驗證輸出
標題為「階段：驗證輸出」的區段「找不到輸出的 src/ 目錄」/「在輸出中找不到 PHP 檔案」
標題為「「找不到輸出的 src/ 目錄」/「在輸出中找不到 PHP 檔案」」的區段驗證需要一個非空的 output/src。空目錄樹表示合併沒有複製任何內容，或檔案移動失敗。已對照 scripts/build.php（validateOutput()）驗證。
「語法驗證：已略過（需要 PHP 執行階段）」
標題為「「語法驗證：已略過（需要 PHP 執行階段）」」的區段這是預期內狀況，不是錯誤。建構主機執行的是現代版 PHP，而不是目標版本，因此本機階段只會計算檔案數量，並印出可用於真正語法檢查的 Docker 指令。具權威性的語法閘門是發行工作流程中建構後的 php -l 步驟，並在實際目標執行階段下執行。已對照 scripts/build.php（validateOutput()）與 .github/workflows/build.yml（PHP 8.1/PHP 7.4 語法檢查步驟）驗證。
已知限制
標題為「已知限制」的區段這些限制是降級做法本身固有的。它們已對照各規則與專案 README.md 的「Known Limitations」驗證：
- 唯讀屬性會被移除。
readonly會被去除，讓 clone-with 展開後的明確屬性指派在較舊執行階段上合法。降級後的輸出不再由執行階段強制不可變性。 - 在 PHP 8.1 上不會強制套用
#[Override]。 該屬性可能仍會保留，但較舊執行階段不會對它採取任何動作。 - PHP 7.4 目標僅含核心。 框架轉接器、tcpdf 相容層及 Pro 並不屬於 PHP 7.4 發行版的一部分，這是由建構指令碼結構決定的。
- Pro 是獨立套件且僅限 PHP 8.1。 沒有 PHP 7.4 的 Pro 建構。
- clone-with 引數比對並非遞迴。 含巢狀括號的覆寫值不會被轉換，且只有字串陣列鍵會解析為屬性名稱。
- /integrations/backport/configuration/：規則與旗標參考。
- /integrations/backport/production-usage/：CI 閘門與發行通道。