3. 依赖解析日志分析

依赖解析是 Gradle 构建的核心环节，当出现编译报错、运行时类冲突或意外版本时，调试依赖树和解析过程是首要手段。本章围绕 查看依赖树、识别版本冲突、使用 dependencyInsight 任务 和 分析 ResolvedConfiguration 四个工具链展开，帮助你从日志中定位问题源头。

3.1 核心概念与工具速查

3.2 查看依赖树

执行 gradle dependencies 命令会输出全部 Configuration 下的依赖树，包括直接依赖、传递依赖以及冲突标记。典型输出示例如下：

gradle dependencies --configuration runtimeClasspath

runtimeClasspath - Runtime classpath of source set 'main'.
+--- com.google.guava:guava:30.1-jre
|    \--- com.google.guava:failureaccess:1.0.1
+--- org.slf4j:slf4j-api:1.7.36
|    \--- (c) org.slf4j:slf4j-api:1.7.36 (conflict resolved)
\--- ch.qos.logback:logback-classic:1.2.11
     +--- org.slf4j:slf4j-api:1.7.32 -> 1.7.36 (*)
     \--- ch.qos.logback:logback-core:1.2.11

• 直接依赖：以 +--- 开头。
• 传递依赖：以 \--- 或 | \--- 缩进表示。
• 冲突标记：-> 1.7.36 表示被选择的版本；(*) 表示该模块在其他位置已经被选中，此处为引用。

3.3 识别版本冲突

当多个依赖引入同一模块的不同版本时，Gradle 默认使用 最高版本策略（除非配置了强制版本或严格版本）。冲突标记在依赖树中表现为 (*) 和 ->：

• (*) 表示该依赖因为已被其他分支选中而被跳过。
• -> X.Y.Z 显示实际选用的版本。

通过开启 --info 日志可以查看冲突解析的详细决策过程：

gradle dependencies --info | grep -i "conflict\|selected"

3.4 使用 dependencyInsight 任务

当需要追溯某个特定模块的来源时，dependencyInsight 比 dependencies 更精准。它只分析指定模块，并显示所有引入路径以及版本选择原因。

gradle dependencyInsight --dependency slf4j-api --configuration runtimeClasspath

org.slf4j:slf4j-api:1.7.36
  Variant: runtime
  Selection reason: conflict resolution (multiple versions found)
  Requested versions:
      1.7.32     (from org.slf4j:slf4j-api:1.7.32)
      1.7.36     (from ch.qos.logback:logback-classic:1.2.11)
  Selected version: 1.7.36

• Selection reason：说明为何选中该版本（冲突解析、强制、严格等）。
• Requested versions：列出所有引入该模块的路径及其要求的版本。

3.5 分析 ResolvedConfiguration

通过 Kotlin DSL 编程方式访问 ResolvedConfiguration，可以批量检查依赖是否符合预期，适用于编写自动化校验逻辑。常见用法：

tasks.register("checkDependencies") {
    doLast {
        val config = configurations.runtimeClasspath.get().resolvedConfiguration
        val allDeps = config.allModuleDependencies
        val firstLevelDeps = config.firstLevelModuleDependencies
        val artifacts = config.resolvedArtifacts

        // 检查是否有冲突
        val hasConflict = allDeps.any { it.isForce }
        if (hasConflict) {
            throw GradleException("Conflict detected in runtimeClasspath!")
        }

        println("All resolved artifacts: ${artifacts.size}")
        artifacts.forEach { artifact ->
            println("  ${artifact.moduleVersion} => ${artifact.file.name}")
        }
    }
}

• allModuleDependencies：所有已解析的依赖模块（含传递）。
• firstLevelModuleDependencies：仅声明的一级依赖。
• resolvedArtifacts：实际下载的构件列表。

3.6 依赖解析日志分析流程

整个调试流程从声明依赖开始，依次经过 依赖树查看、冲突检测、定向洞察 和 编程验证。下图概括了常用工具之间的关系：

3.7 常见错误与优化策略

• 依赖树输出过长：始终使用 --configuration 限定范围，或通过 grep 过滤关键字。
• 版本冲突标记不明显：养成在 IDE 终端中运行 dependencies 的习惯，颜色高亮可辅助定位。
• 误判冲突原因：不要只看版本号大小，还要关注 selection reason，区分“冲突解决”与“强制版本”。
• ResolvedConfiguration 性能：在大型项目中频繁调用 allModuleDependencies 可能较慢，建议在自定义任务中缓存结果或仅在调试时启用。