指南
如何修复 Minecraft 插件错误
更新于 2026年10月18日
插件无法加载时，服务器几乎总会说明原因：原因就在启动时的控制台里，在插件名字的上下几行。学会读懂日志的这一部分，大多数错误一分钟就能修好。下面是常见的错误及其含义。
写明你的服务器版本，以及插件应该做什么。
用 Codexe 生成这个分步说明
1.打开启动日志
查看控制台，或服务器文件夹中的
logs/latest.log。如果用的是托管面板，就用它的控制台或文件管理器。2.搜索插件的名字
找到第一个提到它的错误。以
[ERROR]或[WARN]开头、下面跟着堆栈跟踪的行才是关键。3.阅读第一行和“Caused by”行
第一行说明什么失败了；最后一个
Caused by:行通常说明原因。带有插件自身包名的行，指出了它代码中出问题的位置。4.对照下面的列表
大多数启动错误都是版本、Java 或依赖的问题，消息会告诉你是哪一种。
5.一次修复一处，然后重启
改一处，重启（不要用
/reload），再看一遍日志。一个插件的错误可能会引发其他插件的错误。
常见错误
| 你看到的 | 含义 | 解决方法 |
|---|---|---|
Unsupported API version 1.21 | 插件的 api-version 比你的服务器更新。 | 获取适用于你服务器的版本，或者升级服务器。 |
Could not load 'plugins/X.jar'，并伴有 Invalid plugin.yml 或 Jar does not contain plugin.yml | 插件的描述文件缺失或有 YAML 错误，或者这个文件根本不是插件。 | 确认你下载的是插件本身，而不是它的源代码、模组或 zip。如果是你自己构建的，修复 plugin.yml。 |
UnsupportedClassVersionError，“class file version 65.0” | 插件需要的 Java 比服务器运行的更新（61 = Java 17，65 = Java 21，69 = Java 25）。 | 用那个 Java 运行服务器，或者为你的 Java 重新构建插件。 |
NoClassDefFoundError 或 ClassNotFoundException | 插件需要的某个类不存在：缺少某个依赖插件，某个库没有打包进 .jar，或者这个 API 在该版本上不存在。 | 安装错误中提到的插件（Vault、ProtocolLib），或者使用适用于你版本的构建。 |
Unknown/missing dependency plugins | depend 中列出的某个插件没有安装。 | 把它装进 plugins/。 |
Error occurred while enabling X (Is it up to date?) | 插件已加载，但在 onEnable 中崩溃了。 | 阅读 Caused by 行：通常是配置错误或缺少依赖。 |
Ambiguous plugin name | plugins/ 中有同一个插件的两个 .jar 文件。 | 删掉旧的那个。 |
与加载无关的错误
- 插件是绿色的，但命令提示“Unknown command”：
plugin.yml中缺少这个命令，或者另一个插件用了同样的名字。 - “I'm sorry, but you do not have permission”：玩家缺少权限节点。在插件页面上查到该节点，再用你的权限插件授予它。
- 修改 config.yml 后出错：YAML 要用空格而不是制表符，开头是
:或&的文本要加引号。 - 重启后正常，/reload 后出问题：插件不支持
/reload。改为重启。
你的服务器需要哪个 Java
Minecraft 1.20.5 及更新版本需要 Java 21，26.x 需要 Java 25；1.18 到 1.20.4 需要 Java 17。用服务器所用的那个 Java 运行 java -version（在托管面板上，通常是一个叫 Docker 镜像或 Java 版本的设置）。为旧版 Java 构建的插件可以在新版 Java 上运行，反过来则不行。
修复用 Codexe 制作的插件
在 Codexe 上制作的插件会针对你选择的版本编译，并在标记为就绪之前检查 plugin.yml 是否有效。在测试服务器上，日志标签页会实时显示日志并高亮错误，导出日志可以把它保存为文件。在项目聊天中描述你看到的情况（“插件在 /plugins 中是红色的，日志里写着……”），Codexe 就会修改代码并重新构建。如果 Codexe 交付的文件原封不动地编译失败，用 AI 修复会免费修好它们。
常见问题
服务器日志在哪里？
服务器文件夹中的 logs/latest.log，记录的是本次运行。之前的运行记录以 .log.gz 文件的形式放在同一个文件夹里。
一个插件会弄坏另一个插件吗？
会：缺失或损坏的依赖会让所有需要它的插件都无法运行。先修复日志中的第一个错误，再处理其他的。
分享我的日志安全吗？
基本安全，但先检查一下：日志可能包含 IP 地址，某些插件的报错中还可能带有数据库密码。
为你的服务器重新构建一个坏掉的插件
这条提示词打开后即可直接发送：
“一个名为 SimpleWarps 的 Paper 1.21.4 插件，用来替换我那个已经无法加载的旧插件：带名称的 /setwarp、/warp 和 /delwarp，/warps 在界面中列出所有传送点，设置和删除需要 warps.admin 权限，传送点在重启后保留，消息在 config.yml 中。”
用 Codexe 生成这个