11_Maven 依赖冲突排查与解决方案实战

在 Java 项目开发中，随着引入的第三方类库越来越多，Maven 依赖冲突是一个经常让人头疼的问题。本文将带大家深入了解什么是依赖冲突、产生的原因，以及如何高效地排查和解决这些问题。

一、什么是依赖冲突？

依赖冲突是指项目中依赖的某一个 jar 包，由于不同的引入路径导致存在多个不同的版本，最终造成类包版本冲突的问题。

为什么会产生依赖冲突？

依赖冲突通常是由类包之间的**间接依赖（传递依赖）**引起的。我们在 pom.xml 中显式声明的每一个依赖，它自身可能还会依赖其他隐式的类包。这些隐式类包会被 Maven 间接引入到我们的项目中，如果不同的显式依赖引入了同一个隐式依赖的不同版本，就会产生冲突。

二、解决依赖冲突的核心思路

解决依赖冲突的核心步骤非常简单：

查：找到产生依赖冲突的 jar 包。
剔：找出我们不想要的版本，手工将其排除在外即可。

三、排查依赖冲突的方法

1. 通过命令行排查 (dependency:tree)

可以使用 Maven 提供的 dependency:tree 命令来检查版本冲突：

复制代码

mvn -Dverbose dependency:tree

执行上述命令后，控制台会输出类似以下的依赖树信息：

复制代码

[INFO] com.sqnugy:pocket-ai-robot:jar:1.0.0
[INFO] +- org.springframework:spring-context:jar:5.2.7.RELEASE:compile
[INFO] |  +- (org.springframework:spring-aop:jar:6.2.6:compile - version managed from 5.2.7.RELEASE; omitted for conflict with 5.2.0.RELEASE)
[INFO] |  +- org.springframework:spring-beans:jar:6.2.6:compile (version managed from 5.2.7.RELEASE)
[INFO] |  |  - (org.springframework:spring-core:jar:6.2.6:compile - version managed from 6.2.6; omitted for duplicate)
[INFO] |  +- org.springframework:spring-core:jar:6.2.6:compile (version managed from 5.2.7.RELEASE)
[INFO] |  |  - org.springframework:spring-jcl:jar:6.2.6:compile (version managed from 6.2.6)
[INFO] |  - org.springframework:spring-expression:jar:6.2.6:compile (version managed from 5.2.7.RELEASE)
[INFO] |     - (org.springframework:spring-core:jar:6.2.6:compile - version managed from 6.2.6; omitted for duplicate)
[INFO] - org.springframework:spring-aop:jar:5.2.0.RELEASE:compile (scope not updated to compile)
[INFO]    +- (org.springframework:spring-beans:jar:6.2.6:compile - version managed from 5.2.0.RELEASE; omitted for duplicate)
[INFO]    - (org.springframework:spring-core:jar:6.2.6:compile - version managed from 5.2.0.RELEASE; omitted for duplicate)

日志解析：

omitted for duplicate：表示该jar包被重复依赖了。
omitted for conflict with xxx：说明该jar包和其他版本冲突了，当前行的版本不会被引入 。例如上面的提示omitted for conflict with 5.2.7.RELEASE，意味着项目最终使用的是5.2.7版本，而5.2.0版本被舍弃。

2. 通过 IDEA 插件排查 (推荐)

如果你使用的是 IntelliJ IDEA，强烈建议安装Maven Helper 插件。安装成功后，打开pom.xml文件，底部会多出一个Dependency Analyzer视图：

视图中主要有以下几个选项：

冲突：查看存在的冲突（重点关注）
All Dependency as List ：以列表形式查看所有依赖
All Dependency as Tree ：以树状形式查看所有依赖

点击存在冲突的jar包，即可明显看到是哪几个包的引入导致了版本冲突：

四、解决冲突的四大策略

假设我们目前的pom.xml如下，项目引入了默认的spring-core5.2.7 版本，但我们期望使用的是 5.2.0 版本，有哪些操作？

复制代码

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.2.7.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-aop</artifactId>
        <version>5.2.0.RELEASE</version>
    </dependency>
</dependencies>

策略一：第一声明者优先原则

Maven解析依赖时，在pom.xml文件中自上而下 ，谁先声明，就优先使用谁的交付依赖。如果我们要使用5.2.0版本的spring-core（由spring-aop提交），只需将spring-aop的声明移到最前面即可：

复制代码

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-aop</artifactId>
        <version>5.2.0.RELEASE</version>
    </dependency>        
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.2.7.RELEASE</version>
    </dependency>
</dependencies>

查看依赖树

复制代码

[INFO] --- dependency:3.8.1:tree (default-cli) @ pocket-ai-robot ---
[INFO] com.sqnugy:pocket-ai-robot:jar:1.0.0
[INFO] +- org.springframework:spring-aop:jar:5.2.0.RELEASE:compile
[INFO] |  +- org.springframework:spring-beans:jar:6.2.6:compile (version managed from 5.2.0.RELEASE)
[INFO] |  |  \- (org.springframework:spring-core:jar:6.2.6:compile - version managed from 6.2.6; omitted for duplicate)
[INFO] |  \- org.springframework:spring-core:jar:6.2.6:compile (version managed from 5.2.0.RELEASE)
[INFO] |     \- org.springframework:spring-jcl:jar:6.2.6:compile (version managed from 6.2.6)
[INFO] \- org.springframework:spring-context:jar:5.2.7.RELEASE:compile
[INFO]    +- (org.springframework:spring-aop:jar:6.2.6:compile - version managed from 5.2.7.RELEASE; omitted for conflict with 5.2.0.RELEASE)
[INFO]    +- (org.springframework:spring-beans:jar:6.2.6:compile - version managed from 5.2.7.RELEASE; omitted for duplicate)
[INFO]    +- (org.springframework:spring-core:jar:6.2.6:compile - version managed from 5.2.7.RELEASE; omitted for duplicate)
[INFO]    \- org.springframework:spring-expression:jar:6.2.6:compile (version managed from 5.2.7.RELEASE)
[INFO]       \- (org.springframework:spring-core:jar:6.2.6:compile - version managed from 6.2.6; omitted for duplicate)

策略2：路径近者优先原则（直接依赖）

直接依赖的优先级和交付依赖。我们可以以中pom.xml显式的方式将目标版本的依赖添加进去，强制指定版本：

复制代码

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.2.7.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-aop</artifactId>
        <version>5.2.0.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-core</artifactId>
        <version>5.2.0.RELEASE</version>
    </dependency>
</dependencies>

策略3：排除依赖（Exclusions）

我们可以把不需要的依赖从它的上级依赖中明确除掉。使用 Maven Helper 插件可以很方便地完成：在视图中右键单击要修复的 jar，选择Exclude即可。

它的基本原理是在pom.xml中自动添加了<exclusions>标签：

复制代码

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.2.7.RELEASE</version>
        <exclusions>
            <exclusion>
                <artifactId>spring-core</artifactId>
                <groupId>org.springframework</groupId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-aop</artifactId>
        <version>5.2.0.RELEASE</version>
    </dependency>
</dependencies>

策略4：版本锁定（依赖管理） - ⭐推荐

在多模块项目或多模块项目中，使用<dependencyManagement>版本锁定是最优雅的做法。它可以统一管理项目的版本号，确保所有模块的依赖版本一致。

复制代码

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
            <version>5.2.0.RELEASE</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.2.7.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-aop</artifactId>
        <version>5.2.0.RELEASE</version>
    </dependency>
</dependencies>

注意：<dependencyManagement>只是声明依赖其版本，并不会自动实现引入。具体的子项目或当前项目中，仍需要显着地式声明需要的依赖（此时可以省略<version>标签）。

五、总结

综上所述，处理 Maven 依赖冲突可以得出以下两点建议：

冲突查 ：强烈推荐使用Maven Helper插件，图形化界面一目了然，省去了看枯燥命令行的烦恼。

注意：<dependencyManagement>只是声明依赖其版本，并不会自动实现引入。具体的子项目或当前项目中，仍需要显着地式声明需要的依赖（此时可以省略<version>标签）。

五、总结

综上所述，处理 Maven 依赖冲突可以得出以下两点建议：

冲突查 ：强烈推荐使用Maven Helper插件，图形化界面一目了然，省去了看枯燥命令行的烦恼。
解决冲突 ：对于企业级开发，个人最推荐使用**版本锁定（<dependencyManagement>）**的方法，这有助于在架构方面保持全局依赖的一致性和可维护性。

11_Maven 依赖冲突排查与解决方案实战