Spigot插件加载失败：主类未继承JavaPlugin问题排查

启动Spigot服务器时，TownTheServer-1.0-SNAPSHOT.jar插件无法加载，服务器抛出InvalidPluginException及ClassCastException，提示主类me.fixegg.towntheserver.CityCreateCommand未继承JavaPlugin。本地编译无语法错误，但服务器加载时触发异常。

错误日志 #

[Server thread/ERROR]: Could not load 'plugins/TownTheServer-1.0-SNAPSHOT.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: java.lang.ClassCastException: class me.fixegg.towntheserver.CityCreateCommand cannot be cast to class org.bukkit.plugin.java.JavaPlugin (me.fixegg.towntheserver.CityCreateCommand is in unnamed module of loader org.bukkit.plugin.java.PluginClassLoader @6d06d69c; org.bukkit.plugin.java.JavaPlugin is in unnamed module of loader java.net.URLClassLoader @1d44bcfa)
at org.bukkit.plugin.java.JavaPluginLoader.loadPlugin(JavaPluginLoader.java:141) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at org.bukkit.plugin.SimplePluginManager.loadPlugin(SimplePluginManager.java:418) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at org.bukkit.plugin.SimplePluginManager.loadPlugins(SimplePluginManager.java:321) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at org.bukkit.craftbukkit.v1_20_R1.CraftServer.loadPlugins(CraftServer.java:419) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:274) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1101) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at net.minecraft.server.MinecraftServer.lambda$spin$0(MinecraftServer.java:320) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
at java.lang.Thread.run(Thread.java:833) ~[?:?]
Caused by: java.lang.ClassCastException: class me.fixegg.towntheserver.CityCreateCommand cannot be cast to class org.bukkit.plugin.java.JavaPlugin (me.fixegg.towntheserver.CityCreateCommand is in unnamed module of loader org.bukkit.plugin.java.PluginClassLoader @6d06d69c; org.bukkit.plugin.java.JavaPlugin is in unnamed module of loader java.net.URLClassLoader @1d44bcfa)
at org.bukkit.plugin.java.JavaPluginLoader.loadPlugin(JavaPluginLoader.java:133) ~[spigot-1.20.1.jar:3634-Spigot-8008d5e-6d79ab8]
... 7 more

相关代码与配置 #

CityCreateCommand.java #

package me.fixegg.towntheserver;

import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class CityCreateCommand implements CommandExecutor {
    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        if (!(sender instanceof Player)) {
            sender.sendMessage("只有玩家可以执行此命令");
            return true;
        }
        Player player = (Player) sender;
        // 命令逻辑
        player.sendMessage("城市创建命令执行");
        return true;
    }
}

plugin.yml #

name: TownTheServer
version: 1.0-SNAPSHOT
main: me.fixegg.towntheserver.CityCreateCommand
author: Fix Egg
commands:
  createcity:
    description: 创建城市
    usage: /<command>

pom.xml #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>me.fixegg</groupId>
    <artifactId>TownTheServer</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <dependencies>
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.20.1-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

问题原因及解决方案 #

核心问题 #

plugin.yml中指定的main类是CityCreateCommand，但这个类仅实现了CommandExecutor（命令执行器），并未继承Spigot插件的核心基类JavaPlugin。Spigot强制要求插件主类必须继承JavaPlugin，否则无法识别为合法插件，进而抛出类型转换异常。

修复步骤 #

1. 创建插件主类
   新建继承JavaPlugin的类作为插件入口，示例代码如下：

   package me.fixegg.towntheserver;
   
   import org.bukkit.plugin.java.JavaPlugin;
   
   public class TownTheServer extends JavaPlugin {
       @Override
       public void onEnable() {
           getLogger().info("TownTheServer插件已启用");
           // 注册命令执行器
           getCommand("createcity").setExecutor(new CityCreateCommand());
       }
   
       @Override
       public void onDisable() {
           getLogger().info("TownTheServer插件已禁用");
       }
   }
   

2. 修改plugin.yml的main配置
   将main字段指向新创建的主类：

   name: TownTheServer
   version: 1.0-SNAPSHOT
   main: me.fixegg.towntheserver.TownTheServer
   author: Fix Egg
   commands:
     createcity:
       description: 创建城市
       usage: /<command>
   

3. 重新编译打包
   执行Maven命令重新构建插件：

   mvn clean package
   

   将新生成的jar包放入服务器plugins目录，重启服务器即可正常加载。

额外说明 #

• JavaPlugin是Spigot插件的核心类，负责管理插件生命周期（启用、禁用），以及注册命令、事件监听器等核心操作。
• 命令执行器仅负责处理具体命令逻辑，不能作为插件主类使用。
• 编译无错误是因为代码语法合规，但Spigot加载插件时有额外校验规则，要求主类必须继承JavaPlugin。

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