构建与依赖 / 系统课时

使用 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 输出。

xml
<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 所在目录执行:

bash
mvn org.apache.maven.plugins:maven-dependency-plugin:3.9.0:tree

预期输出

text
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 时执行:

bash
mvn org.apache.maven.plugins:maven-dependency-plugin:3.9.0:tree -Dincludes=com.google.guava:guava

预期输出

text
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 后,插件会把这些节点保留下来并标记省略原因。对同一个示例执行:

bash
mvn org.apache.maven.plugins:maven-dependency-plugin:3.9.0:tree -Dincludes=com.google.guava:guava -Dverbose

预期输出

text
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,有集成测试的项目再运行对应测试阶段,避免“树看起来正确,但运行时缺类或行为变化”的问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 dependency:tree 排查依赖

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通