簡介

在專案進行到一半時升級遊戲引擎，是遊戲開發中最令人心驚膽戰的日常決策之一。新版 Godot 也許修好了正卡住你的那個 bug — 但也可能悄悄弄壞你投入半年心血打造的場景。正因如此，Godot 社群裡經驗豐富的開發者把版本升級視為一項風險決策，而不是例行公事。

本指南並不是在鼓吹「永遠升級」。它是一份針對 Godot 4.x 到 4.x 遷移的風險管理檢查清單：如何判斷究竟該不該升級、如何做好準備以便能安全退回、版本之間有哪些已知會壞掉的地方，以及 — 最重要的 — 如何實際驗證沒有任何東西壞掉。

究竟該不該升級？

在動手之前，先誠實回答這個問題。升級有實際的成本（遷移工作 + 重新測試），所以效益也必須同樣實在。

應該升級的情況

  • 上游已修復的 bug 正卡住你。 如果困擾你的問題在較新的版本裡已經修好，那麼升級通常比永遠背著一個變通做法更划算。
  • 某個新功能對你的遊戲有實質效益。 不是「聽起來不錯」 — 而是能實際節省開發時間，或是解鎖你需要的某種設計。
  • 你的開發時程很長。 如果專案要花好幾年，小步且頻繁地跳（一次一個次要版本）遠比最後一次巨大的跳躍安全。差距只會越拉越大。

不該升級的情況

  • 即將發行。 上市前的幾週是引入引擎層級變更的最糟時機。先發行，之後再升級。
  • 你需要 C# + Web 匯出。 C# 專案的 Web 匯出在 Godot 4.x 仍然無法使用（於 godot#70796 追蹤中）。如果你在 3.x 依賴這項功能，移到 4.x 就會失去它。
  • 你的目標是舊硬體。 Godot 3.x 能在 OpenGL 2 等級的 GPU 上執行；Godot 4 的 Compatibility 算繪器則需要 OpenGL 3.3 / WebGL 2。如果你的玩家族群用的是老舊機器，3.x 或許真的才是正確的引擎。
  • 關鍵外掛尚未更新。 如果專案依賴的外掛不支援新版本，你就得在自己的遷移問題之外，再背上它的遷移問題。

經驗法則：當具體的效益超過你估算出的具體成本時才升級 — 而不是因為新版本出了。

升級之前 — 準備檢查清單

這裡的每個步驟都是為了：萬一升級出了差錯，你損失的是一個下午，而不是一個專案。

  1. 提交所有變更並建立升級分支。 絕對不要直接升級專案的唯一副本。有了專用分支（不用 git 的話就完整複製一份資料夾），還原只是一道指令，而不是一場搶救行動。
  2. 記錄目前的確切版本（例如是哪個 4.x.y 組建、標準版還是 .NET 版）。當你需要退回或回報 bug 時會用得上。
  3. 保留舊的編輯器執行檔。 Godot 各版本可以並存安裝 — 編輯器只是單一執行檔，兩個都留著毫無成本，還能讓你隨時用舊編輯器開啟舊分支。
  4. 列出你的外掛並逐一確認其支援版本。 檢視 addons/ 的內容，記下每個外掛的來源，並在其儲存庫或 Asset Library 頁面上確認它支援目標版本。
  5. 閱讀你跨越的每個版本的官方升級說明。 官方遷移指南是按版本撰寫的 — 如果你從 4.2 升到 4.4，就要把 4.3 和 4.4 的說明都讀過。
  6. 留下「已知正常」的證據。 為關鍵場景截圖、錄一段簡短的遊玩影片，或者 — 最好的做法 — 撰寫自動化測試情境（下方的測試章節會詳細說明）。升級之後，「外觀和行為是否一樣？」這個問題，只有在你事先記錄了「一樣」的標準時才回答得出來。

升級流程

  1. 用新編輯器開啟分支副本。 開的是升級分支，不是 main。新編輯器會提議進行轉換／重新匯入 — 接受即可。
  2. 讓它完成重新匯入。 .godot 資料夾會從零重新產生。大型專案的首次匯入可能要花上一段時間，而第一輪匯入期間印出的警告通常無害。
  3. 檢查 Output 面板與 Debugger 中新出現的錯誤。 與升級前就存在的錯誤比對（你事先記下來了吧？）。新增的錯誤就是這次遷移的待辦清單。
  4. 實際遊玩關鍵路徑。 開始新遊戲、載入存檔、跑一遍核心玩法循環、開啟主要選單。編輯器階段的錯誤是容易的部分 — 迴歸問題藏在執行期行為裡。
  5. 執行你的測試情境（升級前準備好的那些），並與基準結果比對。
  6. 提交前用 git 檢查工作目錄的差異。 遷移過程中編輯器會改寫檔案：project.godot 會加入新的設定值、.tscn 檔案會被重新儲存，也可能出現新的 .uid 檔案。審視一遍 diff，確切掌握改了什麼 — 然後把它作為一個標示清楚的遷移提交，一次提交完成。

4.x 版本之間的已知破壞點

Godot 4 的次要版本之間大致上相容，但「大致上」這三個字在這句話裡可不輕鬆。以下是根據官方說明與社群回報，最容易踩到的變更。

4.2 → 4.3：TileMap 被棄用，改用 TileMapLayer

Godot 4.3 棄用了 TileMap 節點，改用 TileMapLayer — 每個圖層一個節點，而不是把圖層放在同一個節點裡。既有的 TileMap 仍能運作，但新程式碼和新專案應該使用 TileMapLayer。編輯器內建了擷取工具：選取你的 TileMap，開啟底部的 TileMap 面板，點擊右上角的工具箱圖示，選擇 「Extract TileMap layers as individual TileMapLayer nodes」。

社群回報的陷阱：有回報指出 TileMapLayer 遷移之後，TileSet 物理圖層的碰撞位元被重設為預設值。並非每個人都會遇到，但故障型態很棘手（物件不再碰撞，而且悄無聲息）。轉換之後請明確驗證你的圖塊碰撞。

4.3 → 4.4：.uid 檔案與 GDScript 新增功能

  • Godot 4.4 新增了 .uid 隨附檔案，出現在指令碼和著色器旁邊。請把它們提交到版本控制 — 刪除它們可能會破壞所有用到 uid:// 參照的地方（官方 4.4 升級說明涵蓋了相關變更，例如 @export_file 路徑改為 uid://）。它們看起來像雜物；但並不是。
  • 型別化 Dictionary 等 GDScript 新增功能是向後相容的 — 你的舊程式碼可以照常執行。但採用了新功能的外掛在舊版本上會無法運作，因此跨版本時外掛的行為可能有所不同。

一般情況：任何次要版本之間的細微變化

次要版本之間的算繪調整可能會細微地改變遊戲的外觀 — 光照、反鋸齒、2D 對齊。社群討論裡也有一些在全新專案中無法重現的場景特有迴歸：某個場景升級後行為異常，但在乾淨的專案裡重建同一個場景卻一切正常。如果出現莫名其妙的問題，試試這套隔離流程：關閉編輯器，刪除 .godot 資料夾，重新開啟並讓所有內容重新匯入；如果問題依舊，就在乾淨的專案中重現該場景，判斷元凶是專案累積的狀態，還是引擎本身的變更。

3.x → 4.x 是完全不同的層次

以上的一切都是關於 4.x 到 4.x 的跨越。從 Godot 3 遷移到 Godot 4 完全是另一個類別：GDScript 語法變了、大量節點被改名，TileMap、物理和算繪都被從頭重做 — 而且大多數外掛需要專屬的 4.x 版本。對大型 3.x 專案而言，遷移成本可能逼近重寫的成本，值不值得做是一個真正因專案而異的決定。那次遷移值得（也確實有）自己專屬的文件；本文不會假裝能涵蓋它。

升級後的測試 — 真正的瓶頸

老實說：開發者迴避升級的頭號原因並不是遷移本身 — 而是手動驗證「沒有任何東西壞掉」的代價太高。中型遊戲跑一輪完整的手動迴歸測試，一個週末就沒了。而玩家在發行後才發現的執行期 bug，比任何編輯器錯誤都糟糕得多，因為那已經不是待辦事項，而是商譽問題。

最低限度的手動冒煙測試

  • 從標題畫面開始新遊戲
  • 載入既有的存檔
  • 把核心玩法循環玩上幾分鐘
  • 在你支援的每種解析度與視窗模式下檢查 UI

把前後比對自動化

手動測試無法規模化，也無法告訴你某個精靈偏移了兩個像素。Godot QA 正是為此而生 — 一個免費、MIT 授權、開源的 Godot 測試執行器。它的工作流程與版本升級完美契合：

  1. 升級之前，撰寫（或錄製）涵蓋關鍵路徑的情境 JSON 檔案，並在舊版本上擷取基準截圖。
  2. 升級之後，在新版本上執行一模一樣的情境，並與基準進行像素差異比對。
  3. 失敗之處直接指出迴歸所在，原本要花整個週末的手動重玩，幾分鐘就能搞定。

一個情境不過是由步驟組成的 JSON 清單 — 輸入、等待、斷言、截圖：

{
  "name": "core_loop_smoke",
  "steps": [
    {"type": "wait", "seconds": 1.0},
    {"type": "input", "action": "ui_accept", "pressed": true},
    {"type": "wait", "seconds": 0.5},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "health", "expected": 100, "operator": "eq"},
    {"type": "input", "action": "move_right", "pressed": true},
    {"type": "wait", "seconds": 2.0},
    {"type": "input", "action": "move_right", "pressed": false},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "position:x", "expected": 100.0, "operator": "gt"},
    {"type": "screenshot", "name": "after_move"}
  ]
}

這套情境格式與 Godot MCP Pro 的 run_test_scenario 工具所使用的完全相同，因此連上編輯器的 AI 助手可以替你撰寫這些情境。

如果出了問題

  1. 按版本做二分排查。 如果你一次跨了多個次要版本，就一次一個次要版本地重試升級，找出到底是在哪裡壞掉的。這樣排查範圍就從「所有東西」縮小到一份 changelog。
  2. 清空 .godot 資料夾，讓專案重新匯入。升級後的各種怪異問題中，有出乎意料的比例是陳舊的匯入快取造成的。
  3. 用你的確切錯誤訊息去搜尋引擎的 GitHub issues。 如果是真正的迴歸，往往已經有人回報過 — 有時還附帶變通做法。
  4. 確認是不是外掛在搞鬼。 在專案設定中停用你的外掛後重新測試。如果問題消失了，元凶就是外掛 — 在怪罪引擎之前，先看看有沒有更新的版本釋出。
  5. 接受「留在舊版本」也是一種正當的結果。 如果修復成本超過升級的效益，就退回分支、按兵不動，並設個提醒在下一個版本推出時再試一次。那不是失敗 — 那是風險管理發揮了作用。

什麼時候按兵不動才是正解

有些專案就是不該升級，這一點值得直說：已發行或即將發行的遊戲、需要 Web 匯出的 C# 專案、以舊硬體為目標的遊戲，以及建立在大幅修改的自訂引擎組建上的專案。在這些情況下，你正在用的版本都在善盡職責。升級是工具，不是美德 — 目標是一款完成的遊戲，而不是一個嶄新的引擎。

常見問題

升級之後還能降級嗎？

不行，至少沒有可靠的辦法。一旦新編輯器重新儲存了你的場景和資源，它們就不再向後相容舊編輯器。安全退回的唯一途徑是從版本控制還原 — 這正是升級分支存在的理由。

可以一次跳過好幾個版本嗎？

小步跳比較安全。官方升級說明是按版本撰寫的，所以每一跳都有明確的檢查清單 — 一次跨多個版本會把所有清單同時疊在一起，讓你更難分辨是哪個變更弄壞了什麼。

次要版本真的會弄壞東西嗎？

很少，但確實會。大多數專案跨次要版本都沒有問題，但社群回報的極端案例確實存在 — 碰撞位元被重設、場景特有的算繪迴歸。這正是升級前基準測試重要的原因：它們把「是不是壞了什麼？」從一種感覺變成一項測量。

這份檢查清單適用於 3.x → 4.x 嗎？

清單本身適用 — 開分支、保留舊執行檔、留下基準、事後測試。破壞點清單則不適用：3 到 4 的遷移規模大得多（GDScript 語法、節點改名、系統重做），而且有自己專屬的官方文件。