插件安装、启停与排错

你从群里下了一个 .jar，放进 plugins/，重启服务端，终端刷了几十行，插件却像没装一样：游戏里没有新命令，配置文件也没生成。

插件排错其实只有三个问题：核心认不认它、版本对不对、依赖全不全。按这三件事的顺序排，大部分“装了没反应”都能在十分钟内定位。

本页要点

这一页解决“装了没反应”：先确认核心，再核对版本，最后补依赖。
能装插件的核心只有 Paper、Purpur、Leaves、Leaf、Spigot、CraftBukkit 和 PowerNukkitX。
装错核心，插件文件在也不会被读；Fabric、Forge 这些加载器装的是模组。
三个装法：上传（SAF）、URL 安装、Modrinth 一键装，装完必须重启。
应用不会自动装依赖；同名或同主类冲突只能删掉其中一个。

先确认：插件只能装在 Bukkit 系核心上#

插件（plugin）是服务端的外挂程序，运行在服务端进程里，能给游戏加命令、加玩法。它和模组（mod）是两套机制，文件常常都叫 .jar，但互不通用。

核心	能不能装插件	说明
Paper、Purpur、Leaves、Leaf、Spigot、CraftBukkit	能	统称 Bukkit 系，插件生态通用
PowerNukkitX	能（PNX 插件）	只认 PNX 自己的插件，不是 Bukkit 插件
Fabric、Forge、NeoForge、Quilt	不能	这些是模组加载器，装的是模组
Vanilla、Velocity、BungeeCord	不能	原版没有插件 API；代理端在应用里也不提供插件入口
PocketMine-MP、Allay、BDS	不能	基岩核心，插件格式不同或没有入口

Paper 上装 Forge 模组、Fabric 上装 Bukkit 插件，结果都是“文件在，但没人读”：插件进 plugins/，模组进 mods/。插件和模组的完整区别见核心、插件、模组、代理端：一次讲清；Bukkit 系内部怎么选，见 Paper 系核心。

Java 版本也是前提

插件是 Java 字节码，服务端用 Java 8 跑、插件却按 Java 17 编译，加载时直接报 UnsupportedClassVersionError。1.21+ 通常用 Java 21，1.17–1.20.6 用 Java 17，1.16 及以下用 Java 8。对应关系见游戏版本与 Java 版本。

插件从哪下载：四个来源，怎么判断可信#

“能下载”不等于“能信”：插件运行在服务端进程里，权限和你一样大，能读配置、改世界、对外发请求。来源选错，轻则版本不兼容，重则被植入后门。

来源	适合找什么	优点	要注意
Hangar	Paper 系插件	项目页会标兼容的核心与版本	仍需确认插件本身的版本范围
SpigotMC	Bukkit/Spigot 插件，数量最多	资源页信息全，评论区能看到踩坑	下载前看清“测试过的版本”，别下成别的分支
Modrinth	插件与模组都有	版本、加载器筛选清楚，应用内可直接搜	红字警告不阻止安装，要自己确认
GitHub Releases	有开源仓库的插件	能看到源码、更新记录、issue	只认项目官方仓库，别下陌生人的 fork

判断可信度，看四样东西：项目页是否指向官方源码仓库、最近一次更新是什么时候、支持哪些 MC 版本、issue 里有没有大量“加载失败”。网盘、群文件、论坛附件、“破解版”“优化版”一律不碰。外部链接清单见官方文档与可信资料链接。

版本要对上三样：MC、核心 API、Java#

一个插件能不能加载，至少要看三个版本：

Minecraft 版本：插件页会写支持范围。跨大版本通常不兼容，改过 NMS 的插件尤其如此。
核心 API：plugin.yml 里的 api-version 表示它按哪个 API 编译。插件标的 API 比服务端新，服务端会拒绝加载；Paper 专属插件（带 paper-plugin.yml）在 Spigot 上也跑不起来。
Java 版本：服务端的 Java 不能低于插件编译时用的版本，Java 版本一低，加载阶段就报错。

plugin.yml 是插件的身份证，常见字段有这些：

YAML

name: <插件名>
main: <主类>
version: <插件版本>
api-version: '1.21'
depend: [<前置插件>]
softdepend: [<可选前置>]

打开插件详情，Minexa 会把可读字段列出来；读不出来时提示“未能解析 plugin.yml 元信息”，多半不是标准 Bukkit 插件。

装插件的三个入口与启停规则#

装插件有三个入口，选一条就行：

应用上传（SAF）：服务端管理 → 插件 → 上传，选手机里的 .jar，文件会被复制到当前核心的 plugins/。
URL 安装：填一个能直接下载 jar 的链接和保存文件名，适合你已经有确切直链的情况。
Modrinth 搜索：在插件页搜关键词，按 MC 版本和加载器筛选，一键安装，落点是 plugins/<项目名>.jar。

「文件」页或 FTP 也能把 jar 放进 plugins/，但放深一层等于没装。

启停和删除的规则要分清：

禁用不是删除，而是把插件文件名前面加一个 -；启用时去掉。文件还在，配置也还在。
删除会移除 jar；应用还会问你要不要“同时删除插件数据目录”，这个勾选默认是打开的，删之前想清楚是不是只想临时停用。
服务端运行中不能启停、不能删除，页面会红字提示先停服；上传不一定会被拦，但新插件要重启才会加载。

一次完整的安装：从下载到验证#

停服。先点「停止」，等终端不再输出、状态变成未运行。
下载。从 Hangar、SpigotMC、Modrinth 或项目官方 GitHub 下载与你的 MC 版本、核心类型匹配的 jar。
上传。服务端管理 → 插件 → 上传，选中 jar；或者用文件管理放进 plugins/。
启动。回概览点「启动」，等 Done 出现。
看日志。搜索插件名，确认有 Enabling <插件名> 这类加载记录，没有 Could not load。
进游戏验证。用插件文档里写的命令试一次；没有报错，再装下一个。

最容易省掉的是第 1、5 步。

加载成功的三个证据#

插件页“已安装”的数量只代表扫描到了文件，真正的加载成功有三个证据：

证据	在哪看	说明
日志里有 `Enabling <插件名>`	终端 / `logs/latest.log`	核心确实初始化了这个插件
`/plugins` 里插件名没有标红	游戏内或控制台	Bukkit 系核心认为它已启用
插件自己的命令能用	游戏内	功能真的注册上了

反过来也一样：日志里出现 Could not load、Error occurred while enabling，或 /plugins 里标红，都说明插件没正常工作。Done 只代表服务端起来了，不代表插件加载成功。

配置放哪，改完怎么生效：先重启，别把 `/reload` 当万能#

大多数 Bukkit 插件第一次成功启动后，会在 plugins/ 下生成自己的数据目录，常见结构是：

文本

plugins/
├── <插件名>.jar
└── <插件名>/
    ├── config.yml
    └── data/

改配置的通用流程是：停服 → 编辑 → 启动。和改 server.properties 一样，很多插件只在启动时读一次配置；少数插件有自己的重载命令，以文档为准。

编辑 YAML 时缩进只能用空格、冒号后留一个空格。格式错一个字符，整份配置可能读不出来并报 YAMLException。Minexa 的编辑器不校验语法，保存成功不等于格式正确。

改配置前先复制一份

插件配置通常不大，但改坏了不一定能自动恢复。把 plugins/<插件名>/ 整个目录导出成 zip，再动手改；出问题就整目录换回去。带经济的插件尤其要这样，配置里可能存着玩家余额。

插件页底部有一个「插件热重载」按钮，运行中会发一条 reload。它能救急，但救不了所有情况：

它依赖每个插件在 onDisable 里清掉自己注册的监听器、任务和缓存，很多插件做不到，重载几次后同一个事件可能被处理两遍。
很多插件没为热重载设计：配置只读一次，重载后仍是旧值；有的重载到一半抛异常，留下半初始化状态。

判断标准很简单：换 jar、加依赖、删插件，reload 一律无效。

你改了什么	能不能只 reload
某个插件自己的配置文件，且插件文档说支持 reload	可以试
新增/删除/替换插件 jar	必须重启
新增/升级前置依赖	必须重启
改核心版本、改 Java 版本	必须重启

Minexa 没有独立“重启”按钮：先点「停止」，等它退出，再点「启动」。停止最多等 180 秒，超时不会强杀。

缺依赖与冲突：日志里先看这几行#

Minexa 不会自动解析和安装依赖。Modrinth 安装只把选中的 jar 放进 plugins/，depend 和 softdepend 只在详情里展示，装不装要你判断。

缺依赖时，终端里常见的信号：

日志

[ERROR]: Could not load 'plugins/<插件文件>.jar' in folder 'plugins'
org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [<前置插件>]

日志

java.lang.ClassNotFoundException: <某个类>
java.lang.NoClassDefFoundError: <某个类>

日志

[ERROR]: Could not load 'plugins/<插件文件>.jar': Invalid plugin.yml

对应处理：

日志关键词	含义	怎么办
`UnknownDependencyException`	硬依赖缺失	按插件页写的名字装前置
`Unknown/missing dependency`	同上，换了种说法	检查前置是否放进了 `plugins/`
`ClassNotFoundException` / `NoClassDefFoundError`	缺类，可能是前置缺失或版本不对	装对应版本的前置，别混版本
`Invalid plugin.yml`	插件描述文件损坏或不标准	重新下载，确认不是半截文件
`Unsupported api-version`	插件 API 比服务端新	换插件版本，或升级核心
`UnsupportedClassVersionError`	Java 版本太低	换 Java 或换插件版本

依赖分两种：depend 是硬依赖，缺了插件直接不加载；softdepend 是软依赖，缺了通常只是部分功能不启用。硬依赖缺失时别反复重装同一个 jar，先回插件页看它依赖谁。

同名、同主类、抢同一条命令#

Minexa 会检查两类冲突：插件名重复（两个 jar 声明同一个 name，忽略大小写）和主类重复（两个 jar 指向同一个 main）。命中时页面会出现红色的「检测到插件冲突（可能导致加载失败）」盒子，最常见的原因是“旧版本没删，又传了新版本”，处理办法只有一个：同名或同主类冲突，删掉其中一个就好。

还有一类冲突应用检测不到：两个插件注册了同一条命令，表现是命令能执行但只有一个插件响应。这种看日志里的注册警告，逐个禁用排查。

性能与安全：少装、慢加、留后路#

每多一个插件，服务端每 tick 就多一份活；插件写得不好，TPS（每秒游戏刻，20 满分）会直接掉下来。

一次只加一个：装完启动，看 Done、看有没有报错、进游戏试一下，再加下一个。一次加五个，出问题你不知道该删谁。
别迷信“优化插件”：有些“优化”“清理”插件本身就在高频扫描实体，越装越卡。先看 TPS 与 MSPT。
升级前备份：插件大版本升级可能改配置格式，旧配置不一定能回滚。

删插件前先备份它的数据目录

领地、经济、权限类插件的数据都在 plugins/<插件名>/ 里。删除时勾了“同时删除插件数据目录”，这些数据会一起消失，重装也回不来。只想临时停用就用禁用开关；确定要删，先导出整服或至少那个数据目录。

另外，插件能执行任意代码，等于把服务器交给作者。来路不明的 jar，不要因为“功能很香”就装。

上机自查

插件页列表里能看到刚放的 jar，文件名和下载时一致，不带 - 前缀。
终端里搜插件名能搜到 Enabling <插件名>，没有 Could not load。
游戏内执行 /plugins，插件名不是红色的，插件命令能跑通一次。
是停服后重启验证的，不是只点了「插件热重载」。
装之前备份过整服，或至少导出过 plugins/<插件名>/。

下一步#

插件页每个按钮的具体行为：插件与模组管理
模组装法、依赖和二分法排查：模组安装、依赖与排错
启动报错、插件没加载：模组冲突与插件报错