Maven 如何解决依赖冲突？如何定位实际使用的版本？

简化版

Maven 用依赖仲裁（mediation） 在同一个 groupId:artifactId 的多个版本里选一个，规则是**「路径最近优先」——离当前项目路径越短的版本胜出；路径长度相同则先声明的优先**。定位实际用了哪个版本：mvn dependency:tree 看依赖树、mvn help:effective-pom 看合并后配置。修复靠 dependencyManagement/BOM 锁版本、exclusions 排除错误传递依赖、或升级到兼容版本。关键：Maven 只保证「选出一个版本」，不保证这个版本和所有上游库二进制兼容——冲突常在运行期爆发（NoSuchMethodError 等）。

详细版

冲突产生与仲裁规则：

Maven 从直接依赖和传递依赖构建依赖图，同一个坐标出现多个版本时做 mediation：

路径最近优先（nearest wins）：A → 你（1 层）胜过 A → B → 你（2 层）。直接依赖优先于传递依赖。
路径相同则声明顺序优先：两个候选路径一样长，pom 里先声明的那条路径胜出。

你的项目
 ├─ 直接依赖 Guava 31        ← 路径 1 层，胜出
 └─ B → 传递依赖 Guava 28    ← 路径 2 层，被省略
最终 classpath：Guava 31

定位与修复命令：

mvn dependency:tree -Dverbose            # 看依赖树 + 被省略（omitted）的版本和来源
mvn dependency:tree -Dincludes=com.google.guava:guava   # 只看某个依赖
mvn help:effective-pom                   # 看父 POM/BOM/profile 合并后的最终 POM

三种修复手段：

手段	用途
`dependencyManagement` / BOM	统一锁定版本
`<exclusions>`	切断某个错误的传递依赖
Maven Enforcer 插件	CI 中检测依赖收敛、阻止版本漂移

完整版教学

一、为什么会有依赖冲突

Java 项目往往不是直接依赖一个库，而是依赖一串库（传递依赖）：你依赖 Spring，Spring 依赖 Jackson，Jackson 又依赖别的……最终一个庞大的依赖图里，同一个库很可能被不同的上游引入了不同版本。

问题是：classpath 上同一个全限定类名只能有一个版本的字节码——com.google.common.collect.Lists 不能同时存在 Guava 31 和 28 两份。Maven 必须选一个，否则编译和运行就没有确定的结果。这就是仲裁的由来。

二、Maven 的仲裁规则：路径最近优先

Maven 解决「选哪个版本」的核心规则是 nearest definition（路径最近优先）：

项目的直接依赖优于传递依赖，一层传递优于两层传递——离你越近的版本胜出。
如果两个候选版本路径一样长，则按 pom 里声明的先后顺序，先声明的路径胜出。

关键局限：这个规则解决的是「谁进入 classpath」，它不保证被选中的版本和所有上游库都兼容。Maven 只是「选了一个」，至于这个版本会不会让某个需要更高版本的上游库出错，它管不了——这正是冲突的隐患。

候选版本	路径	距离	仲裁结果
Guava 31	当前项目 -> Guava 31	1	胜出
Guava 28	当前项目 -> LibB -> Guava 28	2	被省略
Guava 30	当前项目 -> LibC -> Guava 30	2	被省略

Maven 依赖冲突的心法是：Maven 只负责“选一个版本进 classpath”，兼不兼容还要工程师验证。

三、冲突为什么常在运行期才爆炸

一个反直觉的点：依赖冲突很多时候编译期不报错，运行期才炸。原因：

编译期通常只编译你自己的代码，不会执行所有第三方库的代码路径。你的代码用的那部分 API 恰好在被选中的版本里存在，就编译通过了。
运行期，某个第三方库（B）在执行时调用了只有高版本才有的方法，而 Maven 实际选中了低版本——于是抛 NoSuchMethodError、ClassNotFoundException、LinkageError 或行为异常。

这类错误看起来像代码 bug，本质是 classpath 上的字节码版本不匹配。看到 NoSuchMethodError 要立刻联想到依赖冲突，而不是死磕业务代码。

四、定位实际版本的工具链

要查清「运行时到底用了哪个版本、从哪来的」：

mvn dependency:tree -Dverbose：打印完整依赖树，-Dverbose 会显示被省略（omitted for conflict）的版本和它们的来源——直接看到「谁引入了旧版本、为什么被舍弃」。
mvn help:effective-pom：看父 POM、BOM、profile 合并后的最终 POM——很多版本其实是父 pom 或 BOM 定的，只看当前 pom 看不出来。
检查最终产物：还要看 fat jar / war / 容器的 lib 目录——因为运行环境可能额外塞进另一份 jar（比如 Tomcat 的 lib、Spring Boot fat jar 里的实际版本），运行时真正加载的以这里为准。

三层都要看：pom 声明 → effective POM → 实际打包/运行的 classpath。

pom.xml 声明
  -> 父 POM / BOM / profile 合成 effective POM
  -> dependency tree 仲裁
  -> fat jar / 容器 lib 中的实际 classpath

五、dependencyManagement / BOM 锁版本

最推荐的修复是统一锁定版本：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>31.1-jre</version>   <!-- 强制统一到这个版本 -->
    </dependency>
  </dependencies>
</dependencyManagement>

dependencyManagement 里声明的版本会覆盖仲裁结果——不管传递依赖引入了哪些版本，都被强制统一。用 BOM（如 Spring Boot BOM）更好：它给出一整套经过组合测试、互相兼容的版本坐标，避免手工拼版本的兼容风险（详见「dependencyManagement vs dependencies」专题）。

六、exclusion 不是万能修复

<exclusions> 用来切断某个错误的传递依赖：

<dependency>
  <groupId>com.example</groupId>
  <artifactId>some-starter</artifactId>
  <exclusions>
    <exclusion>   <!-- 排掉它带进来的、我不想要的日志实现 -->
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
    </exclusion>
  </exclusions>
</dependency>

适合场景：某个 starter 带进来一个你不想要的依赖（如冲突的日志实现）。但排除不是万能的——如果排除后上游库运行时真的需要这个类，就会在运行期失败。排除前要确认：要么有替代依赖提供了这些类，要么上游确实用不到。盲目 exclude 可能把「版本冲突」变成「类缺失」。

七、团队级依赖治理

大型项目要做依赖治理，而不是等冲突了才修：

用 BOM 统一版本，减少各模块自行选版本。
Maven Enforcer 插件：在 CI 里做依赖收敛检查（dependencyConvergence），一旦出现同一库多版本就构建失败，阻止依赖漂移。
安全扫描（如 OWASP dependency-check）：查有漏洞的依赖版本。
升级要跑回归测试，尤其关注 日志、Jackson、Netty、Spring 这类横跨很多模块的基础库——它们一旦冲突，影响面极大。

八、常见误区与追问

误区：Maven 会自动选择最安全或最新的版本。 Maven 按路径最近和声明顺序仲裁，不理解 API 兼容性，也不保证选最新。
误区：编译通过就说明没有依赖冲突。 第三方库的某些代码路径可能运行时才调用缺失方法，典型表现是 NoSuchMethodError。
误区：看到冲突就盲目 exclusion。 排除传递依赖前要确认有替代依赖或上游确实不需要，否则会变成类缺失。
追问：路径同样近时 Maven 怎么选？ 按 POM 中依赖声明顺序，先声明的路径胜出。
追问：effective-pom 解决什么问题？ 它能看到父 POM、BOM、profile 合并后的最终配置，定位版本到底从哪里来。
追问：Enforcer 插件在依赖治理中有什么用？ 可以在 CI 中做依赖收敛检查，发现多版本漂移时直接阻止合并。

九、加强记忆

Maven 依赖冲突要分两件事：① Maven 按规则选版本（路径最近优先，直接依赖 > 传递依赖，路径同长则声明顺序优先）；② 工程师判断这个版本是否兼容（Maven 只保证选一个，不保证兼容，冲突常在运行期爆发 NoSuchMethodError/ClassNotFoundException——看到这些要想到依赖冲突）。定位顺序：dependency:tree -Dverbose（看省略版本和来源）→ effective-pom（看合并配置）→ 检查 fat jar/容器 lib（实际运行版本）。修复：dependencyManagement/BOM 锁版本（推荐）、exclusions 排错误传递依赖（排前确认不缺类）、Enforcer 做收敛检查防漂移。基础库（日志/Jackson/Netty/Spring）冲突影响大，升级要回归测试。

简化版

详细版