构建与依赖 / 系统课时
使用 dependency:tree 排查依赖
使用 dependency:tree 排查依赖
依赖冲突、版本被覆盖或“明明没声明却出现在 classpath”时,dependency:tree 是最直接的定位工具。本篇用 Maven Dependency Plugin 3.9.0 演示完整树、includes 过滤和 verbose 冲突信息,并给出一套从现象到引入路径的排查顺序。
学习目标
- 能运行
dependency:tree并读懂直接依赖、传递依赖、scope 和被省略节点。 - 能用
-Dincludes把大树缩小到目标 artifact 的相关路径。 - 能用
-Dverbose查看因重复或冲突而被省略的节点。
先准备一个可复现的冲突场景
下面的最小 POM 同时声明 Guice 6.0.0 和 test scope 的 Guava 31.0.1-jre。Guice 自身也会传递依赖 Guava,因此这棵树里存在同一 artifact 的多条路径,适合观察 verbose 输出。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>dependency-tree-demo</artifactId>
<version>1.0.0</version>
<dependencies>
<dependency>
<groupId>com.google.inject</groupId>
<artifactId>guice</artifactId>
<version>6.0.0</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>31.0.1-jre</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>这是完整配置文件,可直接保存为项目根目录的 pom.xml。示例显式锁定 maven-dependency-plugin:3.9.0,避免不同 Maven 安装解析到其他插件版本后产生参数或输出差异。
从完整树确认是谁带进来的
在 pom.xml 所在目录执行:
mvn org.apache.maven.plugins:maven-dependency-plugin:3.9.0:tree预期输出
com.example:dependency-tree-demo:jar:1.0.0
+- com.google.inject:guice:jar:6.0.0:compile
| +- javax.inject:javax.inject:jar:1:compile
| +- jakarta.inject:jakarta.inject-api:jar:2.0.1:compile
| \- aopalliance:aopalliance:jar:1.0:compile
\- com.google.guava:guava:jar:31.0.1-jre:test实际输出还会包含 Maven 插件执行日志,以及 Guava 自己的传递依赖;上面只保留本课要观察的关键行。默认树适合先回答两个问题:目标 artifact 是否存在,以及它最终以什么版本和 scope 留在解析结果中。
用 includes 缩小到目标依赖
includes 的过滤格式是 [groupId]:[artifactId]:[type]:[version],各段可以省略,并支持 * 通配符。只查 Guava 时执行:
mvn org.apache.maven.plugins:maven-dependency-plugin:3.9.0:tree -Dincludes=com.google.guava:guava预期输出
com.example:dependency-tree-demo:jar:1.0.0
\- com.google.guava:guava:jar:31.0.1-jre:test过滤会保留匹配节点及必要的祖先路径。一次查多个目标时可以用逗号分隔模式,例如 -Dincludes=com.google.guava:guava,com.google.inject:guice;只知道组织前缀时可用 -Dincludes=com.google.*,但范围越大,定位价值越低。
用 verbose 看被省略的节点
默认树会隐藏部分冲突或重复节点。加入 -Dverbose 后,插件会把这些节点保留下来并标记省略原因。对同一个示例执行:
mvn org.apache.maven.plugins:maven-dependency-plugin:3.9.0:tree -Dincludes=com.google.guava:guava -Dverbose预期输出
com.example:dependency-tree-demo:jar:1.0.0
+- com.google.inject:guice:jar:6.0.0:compile
| \- (com.google.guava:guava:jar:31.0.1-jre:compile - omitted for duplicate)
\- com.google.guava:guava:jar:31.0.1-jre:test (scope not updated to compile)看到 omitted for duplicate 表示同坐标节点已经由另一条路径保留;如果是版本竞争,输出会标记因冲突而省略的版本。排查时记录“最终保留版本”和“被省略版本”各自的祖先路径,再决定升级直接依赖、在某条路径上做 exclusion,还是用 dependencyManagement 统一版本。
按固定顺序处理真实项目
真实项目里按“完整树 → 精确过滤 → verbose → 修改 POM → 再跑一次”的顺序处理最省时间。例如报错指向 Guava,先用 -Dincludes=com.google.guava:guava 找相关路径,再加 -Dverbose 看省略原因;修改后重复同一条命令,确认旧路径或旧版本已经消失。
不要把 dependency:tree 当成最终运行验证。它能证明 Maven 解析出的依赖图发生了变化,但无法证明应用行为正确。完成依赖调整后仍应执行 mvn test,有集成测试的项目再运行对应测试阶段,避免“树看起来正确,但运行时缺类或行为变化”的问题。