2. 理解 Gradle 构建生命周期与调试入口

Gradle 的构建过程并非一次性执行所有任务，而是严格划分为三个有序的阶段：Initialization（初始化）、Configuration（配置）和 Execution（执行）。每个阶段都有特定的职责，也对应着不同的调试时机。只有深入理解这三个阶段的边界与内部钩子，你才能精确地在合适的位置插入断点、日志或断言，从而高效定位脚本问题。

2.1 三阶段概览

下表对比了三个阶段的核心职责、触发时机以及典型的调试入口：

2.2 Initialization 阶段：从哪里开始调试

初始化阶段只执行 settings.gradle.kts 文件。此时 Gradle 会确定哪些模块参与构建，以及应用哪些插件（如 com.android.application）。

• 调试重点：检查项目包含、插件声明是否正确。
• 断点位置：在 settings.gradle.kts 中任意行设置断点（IDE 支持）。
• 日志级别：--info 可查看初始化过程中 Gradle 搜索的 settings 文件路径。
• 常见错误：settings.gradle.kts 语法错误会导致构建立即失败，无后续阶段日志。

2.3 Configuration 阶段：钩子与断点密集区

配置阶段是 Kotlin DSL 脚本运行最复杂的部分——所有 build.gradle.kts 会被逐行解释执行，Task 对象被创建并注册到依赖图中。此时的调试既要关注 DSL 闭包内的逻辑，也要关注 Gradle 提供的生命周期钩子。

// 在任意 build.gradle.kts 中监听配置完成
gradle.afterProject {
    println("After project: ${this.name} - 配置阶段已完成")
}

// 监听任务图准备就绪
gradle.taskGraph.whenReady { graph ->
    graph.allTasks.forEach { task ->
        println("Registered task: $task")
    }
}

推荐的调试策略：

• 在 dependencies、android 等 DSL 块内设置行断点。
• 使用 gradle.projectsLoaded 和 gradle.projectsEvaluated 包裹日志输出。
• 若配置阶段耗时过长，通过 --profile 生成性能报告定位慢闭包。

2.4 Execution 阶段：任务运行时的调试

执行的调试主要聚焦于任务动作的正确性和性能。你可以通过 Task 的 doFirst 和 doLast 插入临时调试代码，而无需修改任务本身的实现。

tasks.register("customTask") {
    doFirst {
        println("doFirst - 即将执行任务动作")
    }
    doLast {
        println("doLast - 任务执行完成")
    }
}

// 或通过 Gradle API 为所有任务添加 doLast
gradle.taskGraph.afterTask { task ->
    println("afterTask: $task finished")
}

命令行参数也是执行阶段的重要调试工具：

# 查看任务执行顺序
gradle build --dry-run
# 显示详细日志（包含每个任务的开始/结束时间）
gradle build --info
# 仅执行特定任务并输出异常堆栈
gradle compileKotlin --stacktrace

2.5 三阶段调试入口结构图

下图展示了三个阶段之间的关系，以及每个阶段典型的调试介入点（红色断点符号、蓝色日志输出、绿色钩子）。

2.6 常见错误与调试陷阱

• 配置阶段抛出异常但不知道是哪行：在 build.gradle.kts 中大量使用 apply 或 plugins 块时，异常堆栈可能指向 Gradle 内部。推荐使用 --stacktrace 并配合 println 缩小范围。
• Task 明明注册了但未执行：检查是否正确配置了依赖关系或启用了条件判断。在 taskGraph.whenReady 中输出所有 registered tasks。
• 初始化阶段修改 settings 后缓存不刷新：强制清理 ~/.gradle/caches 或使用 --rerun-tasks。

2.7 最佳实践：按阶段分层调试

在实际项目中，建议将调试日志按阶段分层输出，避免信息混乱：

// 在 settings.gradle.kts 中
gradle.settingsEvaluated {
    logger.lifecycle("=== Initialization: settings evaluated ===")
}

// 在 build.gradle.kts 中
gradle.projectsLoaded {
    logger.lifecycle("=== Configuration: all projects loaded ===")
}
gradle.taskGraph.whenReady {
    logger.lifecycle("=== Execution: task graph ready ===")
}
gradle.buildFinished { result ->
    logger.lifecycle("=== Build finished: $result ===")
}