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

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

使用 dependencies task 列出项目依赖

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

dependencies task 特别适用于分析传递依赖。虽然您的构建文件列出了直接依赖，但该 task 帮助您理解在构建期间解析了哪些传递依赖。

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

理解输出注释

$ ./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 task 使用以下注释标记依赖树

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

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

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

指定依赖配置

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

与 项目和 task 名称 类似，Gradle 允许依赖配置的缩写名称。例如，只要它与唯一的配置匹配，您就可以使用 tRC 而不是 testRuntimeClasspath。

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

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

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

查看示例

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

以下示例声明了一个名为 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 task 识别所选版本

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

以下示例引入了与 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 task，用于从命令行渲染依赖洞察报告。

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

dependencyInsight 接受以下参数

--dependency <dependency> (必填)

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

--configuration <name> (必填)

解析给定依赖的依赖配置。对于使用 Java plugin 的项目，此参数是可选的，因为该插件提供了 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 拒绝了给定版本的依赖。

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

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

强制

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

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

使用构建扫描获取整体视图

构建扫描 中的依赖树显示有关冲突的信息。

为上面的 commons-codec 示例创建了构建扫描，并提供了包含结果的 URL。

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

dependency management dependency insight report build scan

解决不安全配置解析错误

解析配置可能会对 Gradle 的项目模型产生副作用，因此 Gradle 需要管理对每个项目配置的访问。配置可能以不安全方式解析的方式有很多种。Gradle 将为每个不安全访问生成弃用警告。这些都是不良做法，可能会导致奇怪且不确定的错误。

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

例如

  • 来自一个项目的 task 直接在 task 的 action 中解析另一个项目中的配置。

  • task 将来自另一个项目的配置指定为输入文件集合。

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

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

在大多数情况下，可以通过在另一个项目上创建跨项目依赖来解决此问题。有关更多信息，请参阅有关在项目之间共享输出的文档。

如果您发现无法使用这些技术解决的用例，请通过提交 GitHub Issue 并遵守我们的问题准则来告知我们。