Minecraft 1.20.4插件开发报错：Invalid plugin.yml 求助

问题概述 #

开发首个Minecraft插件时遇到Invalid plugin.yml错误，使用Gradle构建，对应版本1.20.4，核心报错为：

Caused by: java.io.FileNotFoundException: Jar does not contain plugin.yml

完整报错栈：

org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml
    at org.bukkit.plugin.java.JavaPluginLoader.getPluginDescription(JavaPluginLoader.java:170) ~[spigot-api-1.20.4-R0.1-SNAPSHOT.jar:?]
    at org.bukkit.plugin.SimplePluginManager.loadPlugins(SimplePluginManager.java:157) ~[spigot-api-1.20.4-R0.1-SNAPSHOT.jar:?]
    at org.bukkit.plugin.SimplePluginManager.loadPlugins(SimplePluginManager.java:121) ~[spigot-api-1.20.4-R0.1-SNAPSHOT.jar:?]
    at org.bukkit.craftbukkit.v1_20_R3.CraftServer.loadPlugins(CraftServer.java:430) ~[spigot-1.20.4-R0.1-SNAPSHOT.jar:4090-Spigot-b754dcc-38b1f49]
    at net.minecraft.server.dedicated.DedicatedServer.e(DedicatedServer.java:223) ~[spigot-1.20.4-R0.1-SNAPSHOT.jar:4090-Spigot-b754dcc-38b1f49]
    at net.minecraft.server.MinecraftServer.w(MinecraftServer.java:1000) ~[spigot-1.20.4-R0.1-SNAPSHOT.jar:4090-Spigot-b754dcc-38b1f49]
    at net.minecraft.server.MinecraftServer.lambda$0(MinecraftServer.java:304) ~[spigot-1.20.4-R0.1-SNAPSHOT.jar:4090-Spigot-b754dcc-38b1f49]
    at java.lang.Thread.run(Thread.java:1583) ~[?:?]
Caused by: java.io.FileNotFoundException: Jar does not contain plugin.yml

排查与解决方案 #

1. 确认plugin.yml位置 #

必须将plugin.yml放在项目的src/main/resources目录下，Gradle构建时会自动把该目录的文件打包到Jar根目录。如果放在其他路径，构建后的Jar里不会包含这个文件。

2. 验证plugin.yml格式合规 #

文件必须包含Spigot要求的必填项，且格式正确（用空格缩进，禁止制表符），示例如下：

name: CustomPlugin
version: 1.0.0
main: com.yourpackage.MainClass # 替换为你的主类完整包路径
api-version: 1.20
author: YourName
description: 插件功能描述

注意键名拼写准确，比如api-version不能写成apiversion。

3. 检查Gradle构建配置 #

确保build.gradle（或build.gradle.kts）正确配置了资源打包，推荐使用ShadowJar插件打包完整Jar：
Groovy DSL配置示例：

plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '7.1.2'
}

repositories {
    mavenCentral()
    maven { url 'https://hub.spigotmc.org/nexus/content/repositories/snapshots/' }
}

dependencies {
    compileOnly 'org.spigotmc:spigot-api:1.20.4-R0.1-SNAPSHOT'
}

sourceSets {
    main {
        resources {
            srcDirs = ['src/main/resources']
        }
    }
}

执行shadowJar任务生成Jar，不要用默认的jar任务，否则可能缺失资源文件。

4. 手动校验生成的Jar #

构建完成后，在build/libs目录找到生成的Jar文件，用压缩工具打开，确认根目录下存在plugin.yml。如果不存在，回到前两步排查路径和配置问题。

5. 清理缓存后重新构建 #

执行Gradle清理任务，避免缓存导致的异常，再重新构建：

# Linux/macOS
./gradlew clean shadowJar

# Windows
gradlew clean shadowJar

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