Gradle 提供了工具来导航依赖项管理的结果,让你更精确地了解 Gradle 如何以及为何解析依赖项。你可以渲染完整的依赖图,识别给定依赖项的来源,并查看为何选择了特定版本。依赖项可以来自构建脚本声明或传递性关系。
要可视化依赖项,可以使用
-
dependencies
任务 -
dependencyInsight
任务 -
一个 构建扫描
使用 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
任务使用以下注解标记依赖树
指定依赖项配置
要专注于特定的依赖项配置,请使用可选的 --configuration
参数。
类似于项目和任务名称,Gradle 允许使用依赖项配置的缩写名称。例如,只要能匹配唯一的配置,你可以使用 tRC
代替 testRuntimeClasspath
。
以下示例显示了 Java 项目中 testRuntimeClasspath
配置的依赖项
$ gradle -q dependencies --configuration testRuntimeClasspath
$ gradle -q dependencies --configuration tRC
要查看项目中的所有配置列表,包括插件提供的配置,请运行 resolvableConfigurations
报告。有关更多详细信息,请参阅插件文档,例如 Java 插件文档此处。
查看示例
以下示例声明了一个名为 scm
的自定义依赖项配置,其中包含 JGit 依赖项
configurations {
create("scm")
}
dependencies {
"scm"("org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r")
}
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 的传递性依赖项添加
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")
}
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.
理解选择原因
依赖项洞察报告的“选择原因”部分列出了选择某个依赖项的原因。
原因 | 含义 |
---|---|
(不存在) |
除了存在直接或传递的引用之外,没有其他原因。 |
已请求:<文本> |
依赖项出现在图中,并且包含时带有 |
已请求:不匹配版本 <版本列表> |
依赖项以动态版本出现,其中不包含列出的版本。后面可能跟有 |
已请求:拒绝版本 <版本列表> |
依赖项以丰富版本出现,其中包含一个或多个 |
通过冲突解决:在版本 <版本列表> 之间 |
依赖项多次出现,带有不同的版本请求。这导致了冲突解决以选择最合适的版本。 |
通过约束 |
依赖项约束参与了版本选择。后面可能跟有 |
通过祖先依赖 |
存在一个带有 |
通过规则选择 |
依赖项解析规则覆盖了默认选择过程。后面可能跟有 |
拒绝:版本 <版本> 通过规则,原因 <文本> |
一个 |
拒绝:版本 <版本>:<属性信息> |
依赖项具有动态版本,并且某些版本与请求的属性不匹配。 |
强制 |
构建通过强制平台或解析策略强制使用该依赖项的版本。 |
如果存在多个选择原因,洞察报告会列出所有原因。
解决不安全的配置解析错误
解析配置可能会对 Gradle 的项目模型产生副作用,因此 Gradle 需要管理对每个项目配置的访问。配置可能会以多种方式被不安全地解析。Gradle 会为每次不安全访问生成弃用警告。这些都是不良实践,可能导致奇怪和不确定的错误。
如果你的构建有不安全访问的弃用警告,则需要修复它。
例如
-
一个项目的任务在其操作中直接解析另一个项目的配置。
-
一个任务将另一个项目的配置指定为输入文件集合。
-
一个项目的构建脚本在评估期间解析另一个项目的配置。
-
项目配置在 settings 文件中解析。
在大多数情况下,可以通过在另一个项目上创建跨项目依赖项来解决此问题。有关更多信息,请参阅在项目之间共享输出的操作指南。
如果你发现无法使用这些技术解决的用例,请遵循我们的问题指南在 GitHub 上提交一个问题告诉我们。