构建日志与调试

源：Gradle 官方文档 - Logging | Command Line Interface

掌握 Gradle 的日志系统和调试技巧，能快速定位构建问题，优化构建性能。

日志级别

日志级别说明

Gradle 提供 6 个日志级别，从低到高：

级别	说明	用途
DEBUG	调试信息	详细的构建过程
INFO	信息级别	构建详情
LIFECYCLE	生命周期	默认级别，主要任务执行
WARN	警告	可能的问题
QUIET	安静模式	最少输出
ERROR	错误	构建失败信息

命令行指定日志级别

bash

# Debug 级别（最详细）
./gradlew build --debug

# Info 级别
./gradlew build --info

# Warn 级别
./gradlew build --warn

# Quiet 级别（最少输出）
./gradlew build --quiet

# 简写
./gradlew build -d  # debug
./gradlew build -i  # info
./gradlew build -w  # warn
./gradlew build -q  # quiet

gradle.properties 配置

properties

# 默认日志级别
org.gradle.logging.level=info

构建脚本中打印日志

使用 println

kotlin

// build.gradle.kts
println("Building version: ${project.version}")

tasks.register("myTask") {
    doLast {
        println("Task executed")
    }
}

使用 Logger API

kotlin

// 获取 Logger
val logger = project.logger

logger.debug("Debug message")
logger.info("Info message")
logger.lifecycle("Lifecycle message")  // 默认显示
logger.warn("Warning message")
logger.error("Error message")
logger.quiet("Quiet message")

条件日志

kotlin

if (logger.isInfoEnabled) {
    logger.info("Detailed info: ${computeExpensiveValue()}")
}

命令行调试选项

栈追踪

bash

# 显示栈追踪
./gradlew build --stacktrace

# 显示完整栈追踪
./gradlew build --full-stacktrace

# 简写
./gradlew build -s  # stacktrace
./gradlew build -S  # full-stacktrace

扫描报告

bash

# 生成构建扫描
./gradlew build --scan

构建扫描包含：

构建时间分析
任务执行时间
依赖信息
插件信息
系统信息

Dry Run

bash

# 模拟运行，不实际执行
./gradlew build --dry-run

# 简写
./gradlew build -m

Profile 报告

生成 Profile

bash

./gradlew build --profile

输出位置：build/reports/profile/profile-<timestamp>.html

报告内容：

配置阶段耗时
任务执行耗时
依赖解析耗时
各阶段性能分析

分析 Profile 报告

打开 HTML 报告，关注：

Configuration Time：

配置阶段耗时
识别慢速配置

Task Execution：

每个任务的执行时间
识别性能瓶颈

Dependency Resolution：

依赖解析时间
网络请求耗时

Build Scan 构建扫描推荐

启用 Build Scan

命令行启用：

bash

./gradlew build --scan

总是启用：

kotlin

// settings.gradle.kts
plugins {
    id("com.gradle.enterprise") version "3.16.1"
}

gradleEnterprise {
    buildScan {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishAlways()
    }
}

Build Scan 功能

性能分析：

任务执行时间线
并行执行可视化
缓存命中率

依赖分析：

依赖树
版本冲突
依赖来源

环境信息：

JVM 参数
系统属性
Gradle 属性

日志：

完整构建日志
可搜索
可分享

调试任务

列出所有任务

bash

# 列出所有任务
./gradlew tasks

# 包含所有任务（包括隐藏的）
./gradlew tasks --all

# 列出特定组的任务
./gradlew tasks --group=build

查看任务详情

bash

# 任务帮助
./gradlew help --task <taskName>

# 示例
./gradlew help --task assemble

任务依赖关系

bash

# 查看任务依赖树
./gradlew <task> --dry-run

# 示例
./gradlew build --dry-run

任务执行路径

bash

# 查看任务路径
./gradlew dependencyInsight --task <taskName>

调试依赖

查看依赖树

bash

# 查看所有配置的依赖
./gradlew dependencies

# 查看特定配置
./gradlew dependencies --configuration implementation
./gradlew dependencies --configuration compileClasspath

依赖洞察

bash

# 为什么包含某个依赖
./gradlew dependencyInsight --dependency <group:name>

# 示例
./gradlew dependencyInsight --dependency com.google.code.gson:gson

查看传递依赖

bash

# 查看依赖的传递依赖
./gradlew :app:dependencies --configuration runtimeClasspath

调试构建配置

查看项目属性

bash

# 列出所有属性
./gradlew properties

# 查看特定模块
./gradlew :app:properties

查看项目结构

bash

# 查看项目结构
./gradlew projects

# 详细信息
./gradlew projects -q

查看 buildSrc

bash

# 查看 buildSrc 任务
./gradlew :buildSrc:tasks

调试缓存问题

禁用缓存

bash

# 禁用构建缓存
./gradlew build --no-build-cache

# 禁用配置缓存
./gradlew build --no-configuration-cache

清理缓存

bash

# 清理本地构建缓存
./gradlew cleanBuildCache

# 清理 Gradle 缓存目录
rm -rf ~/.gradle/caches

查看缓存信息

bash

./gradlew build --info | grep "cache"

性能分析工具

Gradle Profiler

安装：

bash

brew install gradle-profiler  # macOS

使用：

bash

gradle-profiler --benchmark --project-dir . assemble

功能：

多次运行取平均值
对比不同配置
生成性能报告

Build Analyzer Android Studio

Android Studio 内置的构建分析工具。

使用：

View → Tool Windows → Build
构建完成后点击 Build Analyzer

功能：

任务执行时间
插件影响分析
配置阶段分析
优化建议

常见问题排查

构建失败

查看详细错误：

bash

./gradlew build --stacktrace

查看完整日志：

bash

./gradlew build --info --stacktrace

配置阶段慢

生成 Profile：

bash

./gradlew build --profile

检查：

Configuration Time
是否有耗时的配置代码

任务执行慢

查看任务执行时间：

bash

./gradlew build --profile

使用 Build Scan：

bash

./gradlew build --scan

依赖问题

查看依赖冲突：

bash

./gradlew dependencies

# 查看特定依赖
./gradlew dependencyInsight --dependency <groupId:artifactId>

缓存问题

禁用缓存测试：

bash

./gradlew clean build --no-build-cache

清理缓存：

bash

./gradlew cleanBuildCache
rm -rf .gradle

调试技巧

临时禁用插件

kotlin

// build.gradle.kts
plugins {
    id("com.android.application")
    // id("com.example.slow-plugin")  // 临时注释
}

隔离问题

最小化复现：

创建最小项目
逐步添加配置
找到问题源

对比构建

对比两次构建：

bash

./gradlew clean build --scan
./gradlew build --scan
# 对比两个 Build Scan URL

检查 Daemon

bash

# 查看 Daemon 状态
./gradlew --status

# 停止 Daemon
./gradlew --stop

# 重新构建
./gradlew build

日志文件

标准输出重定向

bash

# 保存日志到文件
./gradlew build > build.log 2>&1

# 仅保存错误
./gradlew build 2> error.log

# 同时显示和保存
./gradlew build 2>&1 | tee build.log

CI/CD 日志

GitHub Actions：

yaml

- name: Build
  run: ./gradlew build --stacktrace

Jenkins：

自动保存控制台输出。

最佳实践

使用适当的日志级别：

开发：--info
CI：--warn 或默认
调试：--debug

启用 Build Scan：

提供完整构建信息
便于团队协作
远程调试

定期生成 Profile：

监控构建性能
识别性能退化
优化慢速任务

使用 Build Analyzer：

Android 项目首选
可视化分析
优化建议

保留构建日志：

CI 环境保存日志
便于事后分析
追踪历史问题

系统化排查：

从简单到复杂
隔离问题
对比分析

构建日志与调试 ​

日志级别 ​

日志级别说明 ​

命令行指定日志级别 ​

gradle.properties 配置 ​

构建脚本中打印日志 ​

使用 println ​

使用 Logger API ​

条件日志 ​

命令行调试选项 ​

栈追踪 ​

扫描报告 ​

Dry Run ​

Profile 报告 ​

生成 Profile ​

分析 Profile 报告 ​

Build Scan 构建扫描 推荐 ​

启用 Build Scan ​

Build Scan 功能 ​

调试任务 ​

列出所有任务 ​

查看任务详情 ​

任务依赖关系 ​

任务执行路径 ​

调试依赖 ​

查看依赖树 ​

依赖洞察 ​

查看传递依赖 ​

调试构建配置 ​

查看项目属性 ​

查看项目结构 ​

查看 buildSrc ​

调试缓存问题 ​

禁用缓存 ​

清理缓存 ​

查看缓存信息 ​

性能分析工具 ​

Gradle Profiler ​

Build Analyzer Android Studio ​

常见问题排查 ​

构建失败 ​

配置阶段慢 ​

任务执行慢 ​

依赖问题 ​

缓存问题 ​

调试技巧 ​

临时禁用插件 ​

隔离问题 ​

对比构建 ​

检查 Daemon ​

日志文件 ​

标准输出重定向 ​

CI/CD 日志 ​

最佳实践 ​

构建日志与调试

日志级别

日志级别说明

命令行指定日志级别

gradle.properties 配置

构建脚本中打印日志

使用 println

使用 Logger API

条件日志

命令行调试选项

栈追踪

扫描报告

Dry Run

Profile 报告

生成 Profile

分析 Profile 报告

Build Scan 构建扫描推荐

启用 Build Scan

Build Scan 功能

调试任务

列出所有任务

查看任务详情

任务依赖关系

任务执行路径

调试依赖

查看依赖树

依赖洞察

查看传递依赖

调试构建配置

查看项目属性

查看项目结构

查看 buildSrc

调试缓存问题

禁用缓存

清理缓存

查看缓存信息

性能分析工具

Gradle Profiler

Build Analyzer Android Studio

常见问题排查

构建失败

配置阶段慢

任务执行慢

依赖问题

缓存问题

调试技巧

临时禁用插件

隔离问题

对比构建

检查 Daemon

日志文件

标准输出重定向

CI/CD 日志

最佳实践