Gradle 提供了工具来浏览依赖管理的结果，让您更精确地了解 Gradle 如何以及为何解析依赖。您可以渲染完整的依赖图，识别给定依赖的来源，并查看为何选择特定版本。依赖可以来自构建脚本声明或传递关系。

要可视化依赖，您可以使用

  • dependencies 任务

  • dependencyInsight 任务

  • Build Scan

使用 dependencies 任务列出项目依赖

Gradle 提供了内置的 dependencies 任务，用于从命令行渲染依赖树。默认情况下，该任务显示单个项目中所有配置的依赖。依赖树显示每个依赖的所选版本，并提供冲突解决信息。

dependencies 任务对于分析传递性依赖特别有用。虽然您的构建文件列出了直接依赖，但该任务可帮助您了解在构建过程中解析了哪些传递性依赖。

$ ./gradlew dependencies
要渲染在 buildscript classpath 配置中声明的依赖图，请使用buildEnvironment 任务。

理解输出注解

$ ./gradlew :app:dependencies

> Task :app:dependencies

------------------------------------------------------------
Project ':app'
------------------------------------------------------------

annotationProcessor - Annotation processors and their dependencies for source set 'main'.
No dependencies

compileClasspath - Compile classpath for source set 'main'.
\--- com.fasterxml.jackson.core:jackson-databind:2.17.2
     +--- com.fasterxml.jackson.core:jackson-annotations:2.17.2
     |    \--- com.fasterxml.jackson:jackson-bom:2.17.2
     |         +--- com.fasterxml.jackson.core:jackson-annotations:2.17.2 (c)
     |         +--- com.fasterxml.jackson.core:jackson-core:2.17.2 (c)
     |         \--- com.fasterxml.jackson.core:jackson-databind:2.17.2 (c)
     +--- com.fasterxml.jackson.core:jackson-core:2.17.2
     |    \--- com.fasterxml.jackson:jackson-bom:2.17.2 (*)
     \--- com.fasterxml.jackson:jackson-bom:2.17.2 (*)

...

dependencies 任务使用以下注解标记依赖树

  • (*)：表示传递性依赖子树的重复出现。Gradle 对每个项目只展开一次传递性依赖子树；重复出现只显示子树的根，后跟此注解。

  • (c)：此元素是依赖约束，而不是依赖。在树的其他地方查找匹配的依赖。

  • (n)：无法解析的依赖或依赖配置。

指定依赖配置

要关注特定的依赖配置，请使用可选的 --configuration 参数。

与项目和任务名称一样，Gradle 允许依赖配置使用缩写名称。例如，您可以使用 tRC 代替 testRuntimeClasspath，只要它与唯一的配置匹配即可。

以下示例显示了 Java 项目中 testRuntimeClasspath 配置的依赖关系

$ gradle -q dependencies --configuration testRuntimeClasspath
$ gradle -q dependencies --configuration tRC

要查看项目中所有配置的列表（包括插件提供的配置），请运行 resolvableConfigurations 报告。有关更多详细信息，请参阅插件的文档，例如 Java 插件的此处。

查看示例

考虑一个使用 JGit 库来执行发布过程中的源代码控制管理 (SCM) 操作的项目。您可以借助自定义依赖配置来声明外部工具的依赖。这可以避免污染其他上下文，例如生产源代码的编译类路径。

以下示例声明了一个名为 scm 的自定义依赖配置，其中包含 JGit 依赖

build.gradle.kts
configurations {
    create("scm")
}

dependencies {
    "scm"("org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r")
}
build.gradle
configurations {
    scm
}

dependencies {
    scm 'org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r'
}

使用以下命令查看 scm 依赖配置的依赖树

$ gradle -q dependencies --configuration scm

------------------------------------------------------------
Root project 'dependencies-report'
------------------------------------------------------------

scm
\--- org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r
     +--- com.jcraft:jsch:0.1.54
     +--- com.googlecode.javaewah:JavaEWAH:1.1.6
     +--- org.apache.httpcomponents:httpclient:4.3.6
     |    +--- org.apache.httpcomponents:httpcore:4.3.3
     |    +--- commons-logging:commons-logging:1.1.3
     |    \--- commons-codec:commons-codec:1.6
     \--- org.slf4j:slf4j-api:1.7.2

A web-based, searchable dependency report is available by adding the --scan option.

使用 dependencyInsight 任务识别所选版本

一个项目可能直接或传递地请求相同依赖的两个不同版本，这可能导致版本冲突。

以下示例引入了一个与 commons-codec:commons-codec 的冲突，它既作为直接依赖又作为 JGit 的传递依赖添加

build.gradle.kts
repositories {
    mavenCentral()
}

configurations {
    create("scm")
}

dependencies {
    "scm"("org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r")
    "scm"("commons-codec:commons-codec:1.7")
}
build.gradle
repositories {
    mavenCentral()
}

configurations {
    scm
}

dependencies {
    scm 'org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r'
    scm 'commons-codec:commons-codec:1.7'
}

Gradle 提供了内置的 dependencyInsight 任务，用于从命令行渲染依赖洞察报告。

依赖洞察提供有关单个配置中单个依赖的信息。给定一个依赖，您可以识别其版本选择的原因和来源。

dependencyInsight 接受以下参数

--dependency <dependency> (强制)

要调查的依赖。您可以提供完整的 group:name，或其一部分。如果多个依赖匹配，Gradle 将生成一份涵盖所有匹配依赖的报告。

--configuration <name> (强制)

解析给定依赖的依赖配置。对于使用Java 插件的项目，此参数是可选的，因为该插件提供 compileClasspath 作为默认值。

--single-path (可选)

只渲染一条到依赖的路径。

--all-variants (可选)

渲染所有变体的信息，而不仅仅是选定的变体。

以下代码片段演示了如何针对 scm 配置中名为 commons-codec 的依赖的所有路径运行依赖洞察报告

$ gradle -q dependencyInsight --dependency commons-codec --configuration scm
commons-codec:commons-codec:1.7
  Variant default:
    | Attribute Name    | Provided | Requested |
    |-------------------|----------|-----------|
    | org.gradle.status | release  |           |
   Selection reasons:
      - By conflict resolution: between versions 1.7 and 1.6

commons-codec:commons-codec:1.7
\--- scm

commons-codec:commons-codec:1.6 -> 1.7
\--- org.apache.httpcomponents:httpclient:4.3.6
     \--- org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r
          \--- scm

A web-based, searchable dependency report is available by adding the --scan option.

理解选择原因

依赖洞察报告的“选择原因”部分列出了选择某个依赖的原因。

原因 含义

(不存在)

除了直接或传递引用之外，没有其他原因存在。

被请求：<文本>

依赖项出现在图中，并且包含带有because 文本。

被请求：版本不匹配 <版本>

依赖项以动态版本出现，其中不包含列出的版本。后面可能跟有 because 文本。

被请求：拒绝版本 <版本>

依赖项以包含一个或多个 reject 的丰富版本出现。后面可能跟有 because 文本。

因冲突解决：版本之间 <版本>

依赖项多次出现，具有不同的版本请求。这导致冲突解决以选择最合适的版本。

通过约束

一个依赖约束参与了版本选择。后面可能跟有 because 文本。

通过祖先

存在一个带有 strictly 的丰富版本，它强制执行此依赖的版本。

按规则选择

依赖解决规则推翻了默认选择过程。后面可能跟有 because 文本。

拒绝：<版本> 因为 <文本>

ComponentSelection.reject 拒绝了给定版本的依赖项。

拒绝：版本 <版本>：<属性信息>

依赖项具有动态版本，某些版本不匹配请求的属性。

强制

构建通过强制平台或解析策略强制执行依赖的版本。

如果存在多个选择原因，洞察报告将列出所有这些原因。

使用 Build Scan 获取全局视图

Build Scan 中的依赖树显示了冲突信息。

上面 commons-codec 示例的 Build Scan 已创建，并提供了包含结果的 URL。

前往 Dependencies 选项卡并导航到您想要的依赖项。选择 Required By 选项卡以查看依赖项的选择原因和来源

dependency management dependency insight report build scan

解决不安全的配置解析错误

解析配置可能会对 Gradle 的项目模型产生副作用，因此 Gradle 需要管理对每个项目配置的访问。配置可能以多种方式不安全地解析。Gradle 会针对每个不安全访问发出弃用警告。这些都是不良实践，可能导致奇怪和不确定的错误。

如果您的构建有不安全访问弃用警告，则需要修复它。

例如：

  • 一个项目的任务在任务的操作中直接解析另一个项目中的配置。

  • 一个任务将另一个项目中的配置指定为输入文件集合。

  • 一个项目的构建脚本在评估期间解析另一个项目中的配置。

  • 项目配置在 settings 文件中解析。

在大多数情况下，这个问题可以通过在其他项目上创建跨项目依赖来解决。有关在项目之间共享输出的更多信息，请参阅操作指南。

如果您发现无法使用这些技术解决的用例，请根据我们的问题指南提交 GitHub 问题告知我们。