2. 日志级别配置与调试输出

2.1 日志级别概述

Gradle 的日志系统基于 Apache Ant 的日志等级，共分为 5 个级别（从高到低）：ERROR、WARN、LIFECYCLE、INFO、DEBUG。默认情况下，Gradle 仅输出 LIFECYCLE 及以上级别的日志。在调试构建脚本时，提升日志级别是获取内部状态信息最直接的手段。

级别	命令行短选项	典型输出内容
ERROR	（默认）	严重错误信息
WARN	-w / --warn	潜在问题警告
LIFECYCLE	（默认）	任务执行进度、关键步骤
INFO	-i / --info	任务内详细状态与变量值
DEBUG	-d / --debug	Gradle 内部决策、依赖解析过程

2.2 在 Kotlin DSL 中使用 logger 对象

在 build.gradle.kts 中可以直接使用预定义的 logger 对象。它提供了与日志级别对应的方法：

• logger.error(...)
• logger.warn(...)
• logger.lifecycle(...) – 默认级别，始终可见（除非使用 –quiet）
• logger.info(...) – 仅当日志级别≥INFO 时输出
• logger.debug(...) – 仅当日志级别≥DEBUG 时输出

示例：在自定义任务中输出调试信息：

tasks.register("printVars") {
    doLast {
        logger.lifecycle("生命周期的输出，总是可见")
        logger.info("INFO 级别：构建目录为 $buildDir")
        logger.debug("DEBUG 级别：系统属性: ${System.getProperties()}")
    }
}

2.3 设置日志级别的方法

日志级别可以通过命令行、gradle.properties 或环境变量设置：

命令行参数

gradle --info build           # 输出 INFO 及以上日志
gradle --debug build          # 输出 DEBUG 及以上日志
gradle --warn build           # 只输出 WARN 和 ERROR
gradle -q build               # –quiet，只输出 ERROR

gradle.properties 持久化配置

org.gradle.logging.level=info   # 可选：debug / info / warn / quiet

2.4 开启 stacktrace

当构建异常时，默认只显示简短错误。开启 stacktrace 可获得完整调用栈，便于定位问题根源：

gradle --stacktrace build       # 简短 stacktrace（截断至 20 行）
gradle --full-stacktrace build  # 完整 stacktrace

也可以在 gradle.properties 中设置：

org.gradle.logging.stacktrace=internal   # 或 all / full

2.5 利用 --info / --debug 查看详细日志

调试复杂构建时，--info 和 --debug 是核心工具：

• --info：显示任务执行中每个插件的状态、依赖解析过程中的缓存命中、任务输入/输出变化等。
• --debug：显示 Gradle 内部决策（如配置阶段、构建缓存键计算、任务图构建等），信息量极大，通常需重定向到文件再分析：gradle --debug build 2>&1 | tee build.log

日志输出示例（部分摘录）：

# --info 下可见
[INFO] [org.gradle.api.Project] Evaluating project ':app' using BuildScript 'build.gradle.kts'

# --debug 下可见
[DEBUG] [org.gradle.cache.internal.DefaultFileLockManager] Waiting to acquire file lock for .../.gradle/buildOutputCleanup/buildOutputCleanup.lock

2.6 常见错误与避坑

• 日志级别理解错误：误将 logger.info() 调用当作永久输出，但默认不显示。
• 混淆 –info 与 –debug：–debug 包含所有 –info 内容，但量级不同。
• 未过滤无关任务日志：多项目构建中，–debug 会输出所有子项目的内部日志，建议使用 --info --exclude-task :sub:test 缩小范围。

2.7 性能与稳定性优化

• 条件日志输出：使用 logger.isInfoEnabled 等判断避免字符串拼接开销：

  if (logger.isInfoEnabled) {
      logger.info("复杂信息: ${expensiveCalculation()}")
  }

• 日志重定向：将 DEBUG 日志输出到文件，避免干扰控制台可读性：gradle --debug build 2>debug.log
• 启用缓存后减少日志：利用构建缓存时，–info 级别的日志已足够诊断大多数问题。

2.8 本章核心流程图：日志输出控制流程

该流程图展示了从命令行参数到最终日志输出的完整控制链路：参数解析后，根据设定的日志级别（默认、–info、–debug、–warn）决定内部 logger 是否输出特定级别的信息，最终影响调试可见性。