插件与 API 版本兼容性

插件是针对特定版本的服务器 API 构建的。版本不匹配要么会导致插件无法加载，要么会在运行过程中引发错误。

兼容性由什么决定

• 游戏版本。 为 1.20 构建的插件通常无法在 1.21 上运行：内部类发生了变化。
• 核心。 Bukkit/Spigot/Paper 是“自下而上”兼容的：Bukkit 插件可以在 Paper 上运行，但如果使用了 Paper 特有的 API，则反过来不行。
• 依赖项。 Vault、PlaceholderAPI、ProtocolLib——它们的版本也必须匹配。

api-version

插件的 plugin.yml 中会指定：

api-version: 1.21

如果这一行完全缺失，服务器会将插件视为旧版插件并启用兼容模式——日志中会出现一条警告。这不是错误，而是插件过于老旧的标志。

典型症状

安装前检查

控制面板中的“插件与模组”目录会按您的核心和版本进行筛选，并在安装前提示不兼容问题——如何安装。手动上传时，请查看插件页面：上面始终会列出支持的版本范围。