如何把插件更新到新的 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 上构建。之后还要在测试服务器上试用，因为版本之间的行为变化不会以编译错误的形式出现。

常见问题