Gradle插件调试需让构建进程以调试模式启动并由IDE远程连接：执行./gradlew assembleDebug -Dorg.gradle.daemon=false -Dorg.gradle.debug=true，终端显示监听5005端口后，在Android Studio中通过Remote JVM Debug连接localhost:5005；断点须打在apply、afterEvaluate或doFirst/doLast等执行路径上，且插件模块必须作为project module导入、正确配置repositories和META-INF/gradle-plugins/xxx.properties。
直接在示例项目里 attach 调试 Gradle 插件
插件代码改完后，不能只靠 println 猜逻辑——必须让插件运行时停在断点上。关键不是“启动插件”，而是让 Gradle 构建进程以调试模式启动，再由 Android Studio 连上去。
常见错误现象：断点灰色不生效、Debug 按钮不可点、Gradle 任务飞快跑完没进断点，基本都因为没关 Gradle daemon 或没强制 suspend。
- 确保插件模块已作为
classpath引入示例项目的buildscript.dependencies（不是dependencies块） - 在示例项目根目录下执行命令：
./gradlew assembleDebug -Dorg.gradle.daemon=false -Dorg.gradle.debug=true（Linux/macOS）或gradlew.bat assembleDebug -Dorg.gradle.daemon=false -Dorg.gradle.debug=true（Windows） - 执行后终端会卡住并打印类似
Listening for transport dt_socket at address: 5005—— 这说明 Gradle 已就绪等待 IDE 连接 - 回到 Android Studio，用 Remote JVM Debug 配置连
localhost:5005（不需要提前创建 Run Configuration，直接用菜单 Run → Debug → Add Configuration → Remote JVM Debug）
为什么不能用 Gradle 面板里的 “Debug” 按钮直接调试插件
Android Studio 的 Gradle 面板对「项目内 build.gradle」支持一键 Debug，但对「外部插件模块」无效——它默认连接的是 IDE 自己启动的 Gradle 进程，而插件实际运行在示例项目触发的独立 Gradle 进程里。
如果你强行在面板里右键选 Debug assembleDebug，IDE 会起一个新的、未带 -agentlib 参数的进程，断点自然不触发。
- 插件源码必须在 Android Studio 中已打开（即：插件模块要作为 project module 被导入，不能只是 jar 包）
- 断点只能打在插件的
apply(Project)、Project.afterEvaluate、自定义 Task 的doFirst/doLast等实际执行路径上；buildSrc里的代码可直接断点，但独立插件模块必须走远程 attach - 若用 Kotlin 写插件，确认
build.gradle.kts里已启用org.jetbrains.kotlin:kotlin-gradle-plugin，否则断点位置可能错位
调试时 classpath 找不到插件类的典型原因
Caused by: org.gradle.api.plugins.UnknownPluginException: Plugin with id 'xxx' not found 是最常卡住的一步。这不是代码问题，而是插件没被正确加载进 ClassLoader。
- 检查示例项目的
buildscript.repositories是否包含插件所在路径，比如本地 maven 仓库：maven { url uri('../plugin-module/repo') } - 确认插件的
META-INF/gradle-plugins/xxx.properties文件存在且内容为：implementation-class=com.example.MyPlugin（注意路径拼写、大小写、无空格） - 如果插件是 Groovy 编写的，
build.gradle中必须有apply plugin: 'groovy'和compile localGroovy()，否则编译产物不含 Groovy runtime，运行时报NoClassDefFoundError: groovy/lang/GroovyObject - 不要把插件发布到 Maven Central 或 JCenter——本地调试阶段，所有依赖都应指向
file://或相对路径
调试过程中容易忽略的 Gradle 版本兼容细节
插件开发时用的 Gradle 版本（如 8.7），和示例项目使用的 Gradle 版本（如 8.4）不一致，会导致 Plugin with id 'com.android.application' not found 或 Could not initialize class org.gradle.internal.jvm.JvmVersionDetector。
- 插件模块的
gradle/wrapper/gradle-wrapper.properties中的distributionUrl应与示例项目一致，例如：https\://services.gradle.org/distributions/gradle-8.4-bin.zip - 插件代码中调用 Android DSL（如
project.android）前，务必先判断project.plugins.hasPlugin('com.android.application')，否则非 Android 项目调试会直接 crash - Gradle 8.0+ 默认禁用
compile配置，插件里若还写compile 'xxx'会报错，应统一改为implementation
真正卡住的地方往往不是断点设在哪，而是 Gradle 进程是否真的加载了你的插件类、以及它用的是哪套 ClassLoader。每次改完插件代码，记得 clean 示例项目的 .gradle 目录再重试，避免旧缓存干扰。
