Gradle插件开发必须声明gradleApi()以提供核心类型，选localGroovy()或kotlin-gradle-plugin确定语言，依赖须用implementation gradleApi()而非手动指定版本，且需配置META-INF/gradle-plugins/xxx.properties注册插件ID。
Gradle插件开发必须声明的构建脚本依赖
不配对 buildscript 里的依赖，插件类连编译都过不了——这是新手最常卡住的地方。Gradle 插件本身是运行在 Gradle 构建生命周期里的代码，它的编译和运行环境跟普通业务模块完全不同，必须显式引入 Gradle API 和相关工具类。
-
gradleApi()：必须声明，提供Project、Task、Extension等核心类型，没有它连Plugin都无法实现 -
localGroovy()（Groovy 插件）或implementation 'org.jetbrains.kotlin:kotlin-gradle-plugin'（Kotlin 插件）：选其一，决定插件语言；Groovy 更轻量，Kotlin 类型安全更好 - 若需发布插件到 Maven 仓库，加
id 'maven-publish'；若要打成 jar 并验证，加id 'java-library'
插件项目中不能写在 dependencies {} 块顶层的依赖
很多人把插件依赖像业务模块一样写在 dependencies 块里，结果编译报错说找不到 Plugin 接口。这是因为插件的“宿主”是 Gradle 运行时，不是你项目的 classpath。所有与 Gradle 框架交互的依赖，必须进 buildscript 或用 implementation gradleApi() 这种特殊方式声明。
- 错误写法：
dependencies { implementation 'org.gradle:gradle-core:8.10' }—— Gradle 不认这种手动指定版本的写法，会冲突 - 正确写法：
dependencies { implementation gradleApi() }，让 Gradle 自动匹配当前构建所用的版本 - 测试依赖如
gradleTestKit()必须放在testImplementation下，且只能用于test任务，不能参与插件主逻辑编译
为什么你的插件在 IDEA 里标红、同步失败
IDEA 同步 Gradle 插件项目时频繁报 Cannot resolve symbol Plugin，大概率是没启用正确的语言支持或遗漏了插件应用。这不是代码问题，是工程元信息缺失。
- 确保根
build.gradle（或build.gradle.kts）里已apply plugin: 'groovy'或plugins { id 'org.jetbrains.kotlin.jvm' } - 检查
src/main/groovy（或kotlin）路径是否被 IDEA 识别为 Sources Root；右键目录 → “Mark as Sources Root” - 如果用了 Kotlin，必须在
build.gradle中显式配置sourceCompatibility = JavaVersion.VERSION_17（与你本地 Gradle 版本 JDK 一致），否则 IDE 解析器会挂掉
发布前最容易漏掉的依赖项
能本地跑通不代表能发出去。很多插件打包后在别人项目里加载失败，根本原因是缺少元数据声明或依赖传递控制。
- 必须加
id 'maven-publish'，并在publishing块中声明from components.java，否则生成的 jar 没有gradle-plugins.properties - 若插件内部调用了第三方库（比如
gson），要用implementation声明，但得确认它不会和宿主项目冲突——建议用compileOnly+runtimeClasspath分离，或直接 shade 进插件 jar - 插件 ID 注册文件
src/main/resources/META-INF/gradle-plugins/com.example.myplugin.properties必须存在，内容为implementation-class=com.example.MyPlugin，缺了它，别人plugins { id 'com.example.myplugin' }就会报 “Plugin with id ‘…’ not found”
真正麻烦的从来不是写几行 apply 或 project.extensions.create，而是这些隐性依赖和元信息——它们不出现在编译错误里，却能让插件在 99% 的场景下静默失效。
