Spigot服务器加载CustomServer插件报错：Unsupported API version 1.2

问题描述 #

我正在为Spigot服务器开发CustomServer插件，启动服务器时无法加载该插件，报错信息如下：

[Server thread/ERROR]: Could not load 'plugins\CustomServer.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: Unsupported API version 1.2
        at org.bukkit.craftbukkit.v1_20_R1.util.CraftMagicNumbers.checkSupported(CraftMagicNumbers.java:317) ~[spigot-1.20-R0.1-SNAPSHOT.jar:3797-Spigot-7e2af8b-091027a]
        at org.bukkit.plugin.java.JavaPluginLoader.loadPlugin(JavaPluginLoader.java:141) ~[spigot-api-1.20-R0.1-SNAPSHOT.jar:?]
        at org.bukkit.plugin.SimplePluginManager.loadPlugin(SimplePluginManager.java:394) ~[spigot-api-1.20-R0.1-SNAPSHOT.jar:?]
        at org.bukkit.plugin.SimplePluginManager.loadPlugins(SimplePluginManager.java:301) ~[spigot-api-1.20-R0.1-SNAPSHOT.jar:?]
        at org.bukkit.craftbukkit.v1_20_R1.CraftServer.loadPlugins(CraftServer.java:429) ~[spigot-1.20-R0.1-SNAPSHOT.jar:3797-Spigot-7e2af8b-091027a]
        at net.minecraft.server.dedicated.DedicatedServer.e(DedicatedServer.java:219) ~[spigot-1.20-R0.1-SNAPSHOT.jar:3797-Spigot-7e2af8b-091027a]
        at net.minecraft.server.MinecraftServer.w(MinecraftServer.java:973) ~[spigot-1.20-R0.1-SNAPSHOT.jar:3797-Spigot-7e2af8b-091027a]
        at net.minecraft.server.MinecraftServer.lambda$0(MinecraftServer.java:304) ~[spigot-1.20-R0.1-SNAPSHOT.jar:3797-Spigot-7e2af8b-091027a]
        at java.lang.Thread.run(Thread.java:833) ~[?:?]

我的plugin.yml配置如下：

name: CustomServer
version: '1.0'
main: me.user.customserver.CustomServer
api-version: 1.20

请问为何会出现此错误，该如何解决？

问题原因 #

报错提示的Unsupported API version 1.2和配置里的1.20不符，本质是Spigot的API版本解析逻辑存在bug：当api-version以非字符串格式（无引号）填写带两位小数的版本号时，会被错误截断为前两位（比如把1.20识别成1.2），导致服务器认为你使用了不支持的旧版API。

解决方法 #

有两种可靠的修复方式：

• 方式一：将api-version改为字符串格式
  修改plugin.yml中的api-version字段，用单引号或双引号包裹版本号：

  name: CustomServer
  version: '1.0'
  main: me.user.customserver.CustomServer
  api-version: '1.20'
  

• 方式二：移除api-version字段
  如果上述方法无效，也可以直接删除api-version字段，Spigot会自动适配当前服务器的API版本。不过推荐保留该字段，以便明确插件的兼容性范围。

修改完成后重新打包插件，替换plugins文件夹中的旧jar包，重启服务器即可正常加载插件。

内容的提问来源于stack exchange，提问作者Entropire