如何把插件更新到新的 Minecraft 版本

逐步說明

1. 1.先試試舊的 .jar

   把它放到新版本的測試伺服器上，查看主控台。如果能載入也能正常運作，你可能什麼都不用改。

2. 2.修改 API 相依套件

   在 pom.xml 或 build.gradle 裡，把 paper-api 或 spigot-api 改成新版本。

3. 3.更新 api-version 和 Java

   在 plugin.yml 設定 api-version（例如 '1.21'），並針對新版本需要的 Java 編譯：1.20.5 之前是 Java 17，1.20.5 起是 Java 21，26.x 則是 Java 25。

4. 4.修正無法編譯的部分

   建置後逐一處理錯誤：被改名的材料、被移除的方法、改變了的事件類別。編譯器會列出它們，並附上檔案和行號。

5. 5.更新相依插件

   你的插件用到的其他插件（Vault、PlaceholderAPI、ProtocolLib、WorldGuard）也需要支援新 Minecraft 版本的版本，建置檔和伺服器上都要更新。

6. 6.在新版本上測試

   把它載入到裝有相同插件的新版本伺服器上，試遍每個指令和功能，而不只是確認能啟動。

最常出問題的地方

• 材料和列舉名稱：1.13 更新把大多數物品和方塊都改了名；之後的版本也會新增、改名或移除一些。使用舊名稱或數字 id 的程式碼會出錯。
• 被移除的已棄用方法：標記為已棄用好幾個版本的方法，最後都會消失。
• 物品資料：從 1.20.5 開始，物品 NBT 被資料元件取代。直接修改物品 NBT 的插件需要重寫那個部分；一般的 ItemMeta API 則可以繼續使用。
• NMS 和反射：使用伺服器內部類別的程式碼，幾乎每個版本都會壞掉。盡量改用 API，或改用 ProtocolLib 這類函式庫。
• 函式庫版本：為舊版 Java 建置、被打包進去的函式庫，在新版 Java 上可能會失敗。

跨越多個版本的更新

從 1.8 或 1.12 升到 1.21，與其說是更新，不如說是重寫所有碰到物品、方塊和粒子的部分。請一次針對新的 API 完成，不要一個版本一個版本地升級，而且設定檔很可能也要換成新的材料名稱。

如果插件必須同時支援多個版本，就針對你支援的最舊版本編譯，並避免使用之後才加入的 API，或替每個版本分別建置。

用 Codexe

在 Pro 以上的方案中，你可以用 ZIP 匯入插件的原始碼，然後提出要求，例如「這是我的 Paper 1.20.4 插件。把它更新到 Paper 1.21.4」。Codexe 會從建置檔讀取 Minecraft 版本，用該版本需要的 Java 建置，並依照所建置 API 的真實簽章修正編譯錯誤。如果是你在 Codexe 上做的插件，直接在專案聊天中要求新版本就行了。

編譯成功證明插件能在新的 API 上建置。接著還要在測試伺服器上試用，因為版本之間的行為差異不會以編譯錯誤的形式出現。

常見問題