📚 课程目录第1章 Gradle简介与安装

第1章：Gradle Kotlin DSL 调试环境搭建

核心目标：在 IntelliJ IDEA / Android Studio 中搭建可断点调试的 Gradle Kotlin DSL 脚本环境，确保脚本执行时可进入 IDE 调试模式，观察变量、堆栈与构建流程。

1.1 调试原理概述

Gradle Kotlin DSL 脚本本质上是运行在 JVM 上的 Kotlin 代码。Gradle 内置了远程调试支持：通过 --debug-jvm 参数或 org.gradle.debug 属性，让 Gradle 守护进程（Daemon）在指定端口监听调试器连接。IDE 作为调试器附加到该端口后，可以对 build.gradle.kts、settings.gradle.kts、buildSrc 及自定义插件中的 Kotlin 代码设置断点并逐步执行。

版本兼容警告：Gradle 7.0+ 默认使用 Kotlin 1.4+，Gradle 8.0+ 使用 Kotlin 1.8+。调试环境必须保证 JDK、Gradle、Kotlin 插件三者版本相互匹配，否则可能出现断点无效或构建失败。

1.2 环境搭建流程

以下步骤按照典型开发场景排列，请根据实际项目调整。

安装 JDK 17 或更高版本（推荐 JDK 21），并配置 JAVA_HOME 环境变量。
安装 Gradle 8.x（例如 8.7），可从 gradle.org 下载或通过 SDKMAN 管理。
安装 IntelliJ IDEA 2023.3+ 或 Android Studio Hedgehog+，确保内置 Kotlin 插件已启用（File → Settings → Plugins → Kotlin）。
创建或打开已有 Gradle 项目，确认使用 *.gradle.kts 后缀。
配置 Gradle 调试属性（见 1.3 节）。
在 IDE 中导入项目，等待同步完成。
启动调试会话（见 1.4 节）。

1.3 必备配置清单

配置项	位置	典型值	说明
`org.gradle.debug`	`gradle.properties`	`true`	启用 Gradle 远程调试模式，在 5005 端口监听。
`org.gradle.daemon`	`gradle.properties`	`true`	必须使用守护进程，否则调试模式无效。
`org.gradle.jvmargs`	`gradle.properties`	`-Xmx2g -XX:MaxMetaspaceSize=512m`	可额外传递 JVM 参数，不影响调试。
Kotlin 插件版本	`build.gradle.kts` 或 `settings.gradle.kts`	`org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21`	与 Gradle 版本兼容，建议使用最新稳定版。

示例：gradle.properties 文件内容

org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m
org.gradle.daemon=true
org.gradle.debug=true

添加后无需重新导入，Gradle 会在下次构建时自动启用调试模式。

1.4 启动调试会话

有两种方式连接调试器：

方式一（推荐）：在 IDEA 中创建 “Remote JVM Debug” 运行配置，Host=localhost，Port=5005，然后点击 Debug 按钮。随后在终端执行 ./gradlew build，构建会暂停直到调试器连接。
方式二：直接使用命令行 ./gradlew build --debug-jvm，Gradle 会在 5005 端口等待调试器。此时在 IDEA 中选择 “Attach to Process” 或手动启动 Remote Debug 配置。

连接成功后，在 build.gradle.kts 中任意行设置断点（单击行号），执行对应任务即可触发断点。

常见陷阱：如果断点无效，检查是否在 *.gradle.kts 文件上设置了 “Kotlin” 语言级别；确保 IDE 已正确索引项目（File → Invalidate Caches and Restart）。另请确认 Gradle 守护进程未被其他进程占用端口。

1.5 调试环境结构图

1.6 调试技巧与常见错误

问题现象	原因	解决方案
调试器无法连接	Gradle 守护进程未以调试模式启动	检查 `gradle.properties` 中 `org.gradle.debug=true` 且 `org.gradle.daemon=true`
断点变灰或无效	IDE 未将 `.gradle.kts` 识别为 Kotlin 源文件	右键文件 → Mark as → Kotlin Script；或清除索引重启
启动调试后构建立即完成	守护进程已缓存，未重新加载属性	执行 `./gradlew --stop` 再重新构建
Kotlin 版本不匹配	Gradle 内置 Kotlin 版本与插件版本冲突	在 `settings.gradle.kts` 中统一指定 Kotlin 版本

  最佳实践：调试构建脚本时，建议使用 --no-build-cache 避免缓存干扰；对于大型项目，可在 gradle.properties 中添加 org.gradle.parallel=false 以减少多线程断点跳跃。

1.7 性能与稳定性优化

调试结束后关闭调试模式：将 org.gradle.debug 改为 false 或删除该属性，否则所有构建都会等待调试器连接，严重影响 CI。
使用 Gradle Build Cache：调试期间可关闭缓存，但日常开发应开启：org.gradle.caching=true。
缩短脚本编译时间：将复杂逻辑移入 buildSrc 或独立插件，利用 Kotlin 编译增量。
避免在脚本中执行耗时 IO：调试时尤其明显，尽量使用惰性 API（Provider、lazy）。

通过以上配置，你已经可以像调试普通 Kotlin 程序一样，对 Gradle Kotlin DSL 脚本设置断点、单步执行、查看表达式与变量。下一环节将围绕脚本的生命周期与钩子机制展开，深入理解构建过程的可调试点。