3. 使用 Gradle 内置日志系统定位问题

Gradle 内置了一套基于 SLF4J 的日志系统，支持从开发到 CI 的全链路问题定位。掌握日志级别、命令行选项和输出分析技巧，是调试 Kotlin DSL 脚本的基础技能。本章从原理出发，结合实际命令和输出示例，帮助你快速定位构建失败、依赖冲突和脚本逻辑错误。

3.1 日志级别原理

Gradle 日志按严重程度从高到低分为 ERROR、QUIET、WARNING、LIFECYCLE、INFO、DEBUG 六层。默认显示 WARNING 及以上级别；LIFECYCLE 用于显示任务执行进度（如“Running task :compileKotlin”）；INFO 输出更详细的配置和依赖解析信息；DEBUG 则输出最细粒度的内部执行轨迹。

3.2 命令行选项速查

在 Gradle 命令行中通过以下选项控制日志输出和堆栈信息：

# 提升日志级别到 INFO
./gradlew build --info

# 提升日志级别到 DEBUG
./gradlew build --debug

# 显示完整异常堆栈（简略模式默认只显示一行）
./gradlew build --stacktrace

# 显示全量堆栈（包含所有内层异常）
./gradlew build --full-stacktrace

# 降低日志级别到 QUIET（只输出 ERROR 和 显式 QUIET 消息）
./gradlew build --quiet

# 组合使用：DEBUG + 全堆栈
./gradlew build --debug --full-stacktrace

这些选项可同时使用，但在调试时建议按需选择，避免输出过于冗长影响分析效率。

3.3 日志输出分析流程

下图展示了从问题出现到定位根因的典型调试流程。每一步均依赖不同日志级别获取的信息。

3.4 日志输出分析实战

执行 --info 后，可以观察到 Gradle 如何解析 settings.gradle.kts 和 build.gradle.kts 脚本的配置阶段：

# 使用 --info 执行任务
./gradlew compileKotlin --info

# 典型输出片段（节选）
[INFO] [org.gradle.internal.execution.steps.ValidateStep] Validation of task :compileKotlin took 0.023 secs
[INFO] [org.gradle.api.internal.tasks.compile.CompilerFactory] Compiler factory registered for language 'kotlin'
[LIFECYCLE] [org.gradle.internal.execution.steps.ExecuteTask] Executing task ':compileKotlin' ...

当遇到依赖解析问题时，--info 会输出依赖树和冲突处理策略。若仍无法定位，使用 --debug 查看更底层的类路径计算：

# 使用 --debug 查看依赖解析细节
./gradlew dependencies --debug

# 常见输出模式（节选）
[DEBUG] [org.gradle.api.internal.artifacts.ivyservice.resolveengine.graph.builder.NodeBuilder] Adding dependency: com.example:lib:1.0 -> com.example:sub-lib:2.0
[DEBUG] [org.gradle.internal.component.model] Component 'com.example:sub-lib:2.0' selected for configuration 'compile'

3.5 常见错误与日志定位

• 脚本语法错误：Kotlin DSL 编译失败时，ERROR 日志会显示具体行号和错误类型。例如 Unresolved reference: compile，表示使用了已废弃的 API。
• 依赖冲突：WARNING 日志会提示 Conflict detected: module A 1.0 vs 2.0，配合 --info 可看到冲突解决策略。
• 任务执行失败：ERROR 日志包含异常堆栈，使用 --stacktrace 展开完整调用链，定位到 build.gradle.kts 中具体配置。

3.6 性能与稳定性优化建议

• 避免在生产 CI 中使用 --debug：日志 I/O 会拖慢构建，建议 CI 环境使用默认级别，仅在本地调试时启用深度日志。
• 使用 --stacktrace 替代 --full-stacktrace：后者会输出所有嵌套异常，信息冗余。通常 --stacktrace 已足够。
• 开启 Gradle 的 Build Scan：--scan 选项能生成 HTML 报告，包含更结构化的时间线和警告信息，比纯日志更易分析。
• 定期清理构建缓存：长时间使用 --debug 后，日志和缓存文件可能膨胀，使用 ./gradlew clean 可释放空间。

3.7 日志 API 自定义（扩展知识）

在 Kotlin DSL 脚本中，可以直接使用 Gradle 的日志 API 输出自定义信息：

// build.gradle.kts 片段
tasks.register("printInfo") {
    doLast {
        // 输出到 LIFECYCLE 级别（默认可见）
        logger.lifecycle("自定义信息：任务执行完毕")

        // 输出到 INFO 级别（需要 --info 才能看到）
        logger.info("详细调试信息：变量值为 ${someVar}")

        // 输出到 DEBUG 级别（需要 --debug）
        logger.debug("内部状态：${someInternalState}")
    }
}