插件ID在plugins块不生效的根本原因是Gradle未正确解析：plugins块仅从官方仓库或显式配置的Maven仓库（如mavenLocal()）查找插件，不扫描classpath或buildscript；需确保pluginManagement中声明仓库、META-INF/gradle-plugins/xxx.properties路径与内容准确、插件类正确打包且API版本兼容。
插件 ID 在 plugins 块里不生效，根本原因是没被正确解析
Gradle 的 plugins 块是声明式语法，只认两种来源：Gradle 官方插件仓库（plugins.gradle.org）和项目中通过 mavenLocal() 或自定义 repositories 显式注册的 Maven 仓库。它**不会自动扫描 classpath 或 buildscript 里的依赖**。如果你发布插件到本地 Maven 仓库（~/.m2/repository），但没在 settings.gradle 或根 build.gradle 中配置 mavenLocal()，Gradle 就压根不会去那里找插件 ID。
常见错误现象：Plugin with id 'kim.hsl.plugin' not found，即使你确认 JAR 已生成、groupId 和 artifactId 都对，也照样报错。
- 必须在
settings.gradle（推荐）或根build.gradle的pluginManagement { repositories { ... } }块里显式添加mavenLocal() - 不能只在
buildscript { repositories { mavenLocal() } }里加——那是给旧式apply plugin: 'xxx'用的，对新式plugins { id 'xxx' }无效 - 如果用的是远程仓库（如 Nexus、GitHub Packages），URL 必须可访问，且需配好认证（如
credentials）
META-INF/gradle-plugins/xxx.properties 文件缺失或路径错误
Gradle 通过读取插件 JAR 包内的 META-INF/gradle-plugins/ 下的 .properties 文件来映射插件 ID 到实现类。比如你声明 id 'kim.hsl.plugin'，就必须存在 META-INF/gradle-plugins/kim.hsl.plugin.properties，且内容为：implementation-class=kim.hsl.plugin.Plugin4。路径名和文件名必须严格匹配插件 ID，大小写敏感，不能有空格或非法字符。
容易踩的坑：
- 文件放在了
src/main/resources/META-INF/...，但 Gradle 默认不把resources打包进插件 JAR —— 要确认publishing配置里用了from components.java（Kotlin DSL）或from sourceSets.main（Groovy DSL） - 使用
maven-publish插件时，没在publications里显式 includecomponents.java，导致 JAR 缺少META-INF元数据 - IDEA 自动编译时可能缓存旧版本 JAR，手动删掉
~/.m2/repository/kim/hsl/plugin/下对应目录再重发一次更可靠
插件类未被正确打包进 JAR，或类名/包名拼写不一致
即便 .properties 文件存在，如果 implementation-class 指向的类在 JAR 中找不到，就会报 Could not find implementation class 'kim.hsl.plugin.Plugin4' for plugin 'kim.hsl.plugin'。这通常不是网络或配置问题，而是构建产物本身有问题。
验证方法：解压生成的插件 JAR，检查 kim/hsl/plugin/Plugin4.class 是否真实存在，且路径与 implementation-class 完全一致（包括大小写）。注意 Kotlin 编译后类名可能带 $ 符号，Java 类则不会。
- 确保插件源码放在
src/main/java（Java）或src/main/kotlin（Kotlin），而非src/main/groovy（Groovy 不会自动编译成 JVM 字节码供 Gradle 加载） - 若用 Groovy 写插件，必须显式应用
groovy插件，并在dependencies中添加implementation localGroovy()和implementation gradleApi() - 不要在插件类上加任何注解（如
@CompileStatic），除非你明确知道它不影响字节码生成
Gradle 版本与插件 API 不兼容，导致加载失败静默忽略
Gradle 8.x 开始对插件签名、API 使用做了更严格的校验。如果你用 Gradle 8.5+ 构建插件，但目标项目用的是 7.6，可能出现“找不到插件 ID”或“类找不到”却无明确提示的情况——因为某些 API（如 Project.getExtensions().create() 的新重载）在旧版中不存在，JVM 加载类时直接失败。
排查建议：
- 在插件模块的
build.gradle中，将gradleApi()替换为具体版本，例如implementation 'org.gradle:gradle-api:7.6'，并用相同版本的 Gradle wrapper 发布 - 检查插件代码是否调用了
Provider、ConfigurableFileTree等新版 API；如有，降级或加条件判断 - 在目标项目执行
./gradlew --debug | grep -i "plugin"，看日志里是否出现Skipping plugin 'kim.hsl.plugin' due to version incompatibility类似提示
最稳妥的做法是：插件开发环境的 Gradle 版本 ≤ 目标项目最低支持版本，否则兼容性风险不可控。
