支援範圍與疑難排解
本頁整理 NBTExplorerCLI 支援的 Minecraft Java Edition 版本設定(Profiles)、說明「CLI 解析驗證」與「尚待實機驗證」的邊界、列出所有退出碼(Exit Codes),並提供常見錯誤的排解步驟。
1. 支援的 Minecraft Java 版 Profile 清單
Section titled “1. 支援的 Minecraft Java 版 Profile 清單”您可以隨時執行 nbtcli capabilities,查詢目前執行檔註冊的命令清單與各 Minecraft DataVersion Profile 的支援宣告:
.\nbtcli.exe capabilities| Profile 名稱 | DataVersion | 維度目錄結構 | 物品資料結構 | 文字組件格式 | 資源包目錄規則 |
|---|---|---|---|---|---|
java-1.20.4 | 3700 | java-dimensions-directory | java-item-tags-1.20.4 | java-text-json (v1) | java-pack-plural |
java-1.21 | 3953 | java-dimensions-directory | java-item-components-1.20.5 | java-text-json (v1) | java-pack-singular |
java-1.21.5 | 4325 | java-dimensions-directory | java-item-components-1.21.5 | java-text-nbt (v1) | java-pack-singular |
java-26.1-snapshot-6 | 4774 | java-dimensions-namespaced | java-item-components-26.1-snapshot-6 | java-text-nbt (v2) | java-pack-singular |
如何判讀 capabilities 的支援範圍
Section titled “如何判讀 capabilities 的支援範圍”針對每個 Profile,capabilities 會分別列出六個面向(layout、itemSchema、textSchema、commandGrammar、compression、packLayout)在五種操作(read、extract、plan、write、recover)上的支援狀態:
- 可讀取(Readable)不等於可寫入(Writable):能用
get或list讀出資料,不代表該結構一定能直接修改或轉為翻譯鍵。在建立計畫(plan)與寫入(apply)時,工具會嚴格檢查該目標類型與版本是否支援寫入。 - CLI 解析驗證與「尚待實機驗證」的區別:
validate、scan、plan與apply負責在 CLI 層級驗證二進位 NBT/區塊結構、JSON 語法、寫前/寫後 SHA-256 雜湊與型別規則。- 通過 CLI 驗證不等同於已在 Minecraft 遊戲客戶端內完成實機測試。涉及遊戲內實際載入畫面、字型排版顯示與機關指令觸發等尚未在遊戲內逐一實測的行為,均屬尚待實機驗證範圍——在正式發布或遊玩修改後的地圖前,請務必使用世界副本進入 Minecraft 遊戲內實機確認。
2. 支援的 21 種世界文字類型(--types)
Section titled “2. 支援的 21 種世界文字類型(--types)”在執行 scan、extract、validate、convert 或 translate start 時,可透過 --types 以逗號分隔篩選以下 21 種文字角色:
- 方塊與告示牌:
Sign、HangingSign、ContainerName、CommandBlock - 書本與講台:
Book、LecternBook、Title、Author - 物品與實體:
ItemName、ItemLore、ArmorStand、EntityName、TextDisplay - 世界與介面狀態:
BossBar、ScoreboardTeam、ScoreboardObjective - 資料包與語言資源:
McFunction、Advancement、CommandStorage、LangKey、TranslationKey
3. 退出碼(Exit Codes)對照表
Section titled “3. 退出碼(Exit Codes)對照表”每次執行指令都會回傳明確的退出碼與 JSON 輸出。當退出碼非 0(success: false)時,請檢視 JSON 中的 error.code、error.message 與 error.details 取得詳細原因。
| 退出碼 | 狀態分類 | 代表意義 | 建議處理方式 |
|---|---|---|---|
0 | 成功完成 | 指令正常完成(包含合法但無符合項目的搜尋,或確認無需變更的操作)。 | 可繼續進行下一步驟。 |
1 | 非預期內部錯誤 | 發生非預期的內部錯誤。 | 請檢查 JSON 中的 error.code 與 error.details,並在重試前先確認世界狀態。 |
2 | 參數或語法錯誤 | 未知的命令或旗標、缺少必要參數值、重複指定選項,或選擇器彼此衝突。 | 請執行 nbtcli help <command> 核對正確參數名稱。此時不會有任何檔案被修改。 |
3 | 狀態衝突或來源已變更 | 世界存檔或工作階段在產生計畫後曾被修改、節點位址具歧義,或重複使用了相同的 operation-id 卻帶入不同內容。 | 請重新掃描世界或匯出最新工作階段分頁,並重新產生計畫。 |
4 | 格式不支援或範圍不完整 | 目標世界使用了未支援的 DataVersion 或結構特性,或選定的範圍無法完整解析。 | 請執行 nbtcli capabilities 查詢支援程度,並使用 --path、--dimension 或 --types 縮小操作範圍。 |
5 | 檔案讀寫、權限或資料損壞錯誤 | 找不到檔案、檔案被遊戲或其他程式鎖定、NBT/JSON 格式損壞,或寫前準備失敗。 | 請確認 Minecraft 已關閉、檢查檔案路徑是否正確,或使用 backup/restore 修復損壞檔案。 |
6 | 超過資源上限或正規表示式逾時 | 輸入大小、翻譯槽位數量、節點深度、輸出大小(上限 64 MiB)或正規表示式配對(100 毫秒)超過安全上限。 | 請透過 --dimension、--region 或 --path 縮小範圍,調降 --page-size,或簡化 --match-pattern。 |
7 | 需要執行復原(Recovery Required) | 寫入作業在提交過程中斷或發生 I/O 錯誤,世界處於待復原狀態。 | 請勿在遊戲中開啟該世界。保留回傳的 planHash 與 stateRoot,先執行 nbtcli status 檢查,再執行 nbtcli recover。 |
8 | 已完成回滾(Rolled Back) | 復原程序已將世界安全退回修改前的驗證狀態,而非完成寫入變更。 | 世界已安全恢復原狀。若仍需套用修改,請重新產生新的計畫檔。 |
130 | 操作已取消 | 操作記錄為已取消狀態。 | 若在寫入期間中断,請在使用該世界前透過計畫雜湊值執行 status 與 recover。 |
4. 常見錯誤與疑難排解
Section titled “4. 常見錯誤與疑難排解”情境 A:世界檔案被鎖定或拒絕存取(退出碼 5)
Section titled “情境 A:世界檔案被鎖定或拒絕存取(退出碼 5)”常見訊息:執行 scan、backup 或 apply 時回傳退出碼 5(IO_ERROR 或 ACCESS_DENIED)。
處理方式:
- 請確認已完全關閉 Minecraft Java 版遊戲客戶端或伺服器程序。
- 關閉其他正在開啟該世界資料夾的軟體(例如其他 NBT 編輯器、壓縮軟體或預覽工具)。
- 對世界副本重新執行指令。
情境 B:寫入中斷並提示 RECOVERY_REQUIRED(退出碼 7)
Section titled “情境 B:寫入中斷並提示 RECOVERY_REQUIRED(退出碼 7)”常見訊息:apply 或 recover 回傳退出碼 7(RECOVERY_REQUIRED)。
處理方式:
- 請勿在 Minecraft 中開啟該世界。
- 從回傳的 JSON 中複製
planHash與stateRoot。 - 執行
nbtcli status <世界路徑> --plan-hash <雜湊值> --state-root <狀態目錄>檢查日誌狀態。 - 執行
nbtcli recover <世界路徑> --plan-hash <雜湊值> --state-root <狀態目錄> --world-offline繼續完成寫入,或加上--rollback安全退回修改前的原始存檔(回傳退出碼8)。
情境 C:建立計畫或工作階段後,世界曾被外部修改(退出碼 3)
Section titled “情境 C:建立計畫或工作階段後,世界曾被外部修改(退出碼 3)”常見訊息:apply 或 translate submit 回傳退出碼 3(CONFLICT)。
發生原因:目標世界中的檔案在您建立修補計畫或翻譯工作階段之後曾發生變動。為了防止覆蓋新資料,工具會拒絕套用過期的計畫。
處理方式:
- 若是一般編輯計畫過期:請對目前的世界檔案重新執行
get --types與set/plan產生新計畫。 - 若翻譯工作階段過期(提示
repair: "start-new-session"),請建立新工作階段,再依翻譯記憶範例輸入新工作階段 ID、完整槽位雜湊、先前工作階段 ID 與術語表版本。
情境 D:部分區塊/檔案損壞或含不支援格式(退出碼 4 或 5)
Section titled “情境 D:部分區塊/檔案損壞或含不支援格式(退出碼 4 或 5)”常見訊息:scan 或 validate 回報 coverageComplete: false,並回傳退出碼 4(不支援的格式)或退出碼 5(檔案損壞,例如 0 位元組的區塊檔或語法錯誤的資料包 JSON)。
處理方式:
- 執行
nbtcli validate <世界路徑>,從輸出 JSON 的逐檔診斷紀錄中找出發生問題的相對檔案路徑。 - 若該檔案有建立過備份,可使用
nbtcli restore <世界路徑> --manifest-hash <雜湊值> --path <相對路徑> --apply --world-offline單獨修復該檔案。 - 若您只需要翻譯或編輯正常的維度與檔案,可使用
--dimension、--region、--path或--types明確指定範圍,避開損壞或不支援的檔案。
情境 E:超過安全資源上限或正規表示式逾時(退出碼 6)
Section titled “情境 E:超過安全資源上限或正規表示式逾時(退出碼 6)”常見訊息:指令回傳退出碼 6(RESOURCE_LIMIT 或 PATTERN_TIMEOUT)。
發生原因:為防止記憶體耗盡或複雜正規表示式卡死,工具設有單檔/單次輸出 64 MiB 上限、工作階段 100,000 個槽位上限、節點深度 256 層上限,以及正規表示式 100 毫秒配對逾時限制。
處理方式:
- 使用
--dimension、--region、--path或--types縮小單次掃描或工作階段的範圍。 - 在建立或匯出翻譯工作階段時調降
--page-size或--page-bytes。 - 簡化
--match-pattern的正規表示式條件。