Jar 包冲突是 Java 开发中最常见、最棘手的运行时问题之一。它通常在编译时正常，但在运行时报错，导致程序崩溃或行为异常。

🔍 一、Jar 包冲突的表现（典型异常）

当你遇到以下异常时，极有可能是 Jar 包冲突：

💡 关键特征：

• 代码能正常编译打包
• 运行时突然报错，且错误类“明明存在”
• 错误信息指向第三方库中的类（如 com.fasterxml.jackson, org.apache.commons 等）

🧠 二、冲突的根本原因

1. 同一类被多个 Jar 包包含

• 例如：commons-lang3-3.4.jar 和 commons-lang3-3.9.jar 同时存在
• JVM 只会加载第一个找到的类，后续同名类被忽略
• 如果先加载的是旧版本，而代码依赖新版本的方法 → NoSuchMethodError

2. Maven/Gradle 依赖传递导致版本不一致

<!-- A 依赖 commons-lang3:3.4 -->
<dependency>
    <groupId>com.example</groupId>
    <artifactId>lib-a</artifactId>
    <version>1.0</version>
</dependency>

<!-- B 依赖 commons-lang3:3.9 -->
<dependency>
    <groupId>com.example</groupId>
    <artifactId>lib-b</artifactId>
    <version>1.0</version>
</dependency>

→ 最终项目中可能只保留一个版本（由 Maven 的“最近优先”策略决定），但你的代码可能依赖另一个版本的特性。

3. 不同 Jar 包包含相同全限定名的类（包名+类名完全相同）

• 某些厂商会“复制”开源代码并修改（如阿里 Fastjson vs Jackson）
• 或使用 shade 打包时未重命名（如 Hadoop 生态常见）

🛠️ 三、排查方法

✅ 方法 1：使用 Maven 命令查看依赖树

# 查看整个依赖树
mvn dependency:tree

# 查找特定 Jar 的依赖路径
mvn dependency:tree -Dincludes=commons-lang3

# 输出到文件便于分析
mvn dependency:tree -DoutputFile=deps.txt

示例输出：

[INFO] +- com.example:lib-a:jar:1.0:compile
[INFO] |  \- org.apache.commons:commons-lang3:jar:3.4:compile
[INFO] \- com.example:lib-b:jar:1.0:compile
[INFO]    \- org.apache.commons:commons-lang3:jar:3.9:compile

→ 虽然两个版本都声明了，但最终只会保留一个（通常是路径最短或最先声明的）。

✅ 方法 2：检查最终打包的 Jar/WAR 中是否包含重复类

# 解压你的 fat jar
unzip -l your-app.jar | grep "CommonUtils.class"

# 或使用工具
jar -tf your-app.jar | grep "\.class$" | sort | uniq -d

✅ 方法 3：运行时打印类加载路径（调试用）

System.out.println(
    StringUtils.class.getProtectionDomain().getCodeSource().getLocation()
);

→ 可看到实际加载的是哪个 Jar 包。

✅ 四、解决方案（按优先级排序）

🔧 方案 1：依赖排除（最常用）

在 pom.xml 中排除冲突的传递依赖：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>lib-a</artifactId>
    <version>1.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
        </exclusion>
    </exclusions>
</dependency>

🔧 方案 2：统一依赖版本（推荐）

在 <dependencyManagement> 中强制指定版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.12.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

→ 所有子模块都会使用这个版本。

🔧 方案 3：使用 Maven Enforcer 插件（预防）

在 pom.xml 中加入插件，禁止版本冲突：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <executions>
        <execution>
            <id>enforce</id>
            <configuration>
                <rules>
                    <dependencyConvergence/>
                </rules>
            </configuration>
            <goals>
                <goal>enforce</goal>
            </goals>
        </execution>
    </executions>
</plugin>

→ 构建时若发现同一 artifact 有多个版本，直接失败！

🔧 方案 4：重命名包（Shading，终极方案）

适用于无法控制依赖来源的场景（如 Flink、Spark 作业）：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>shade</goal></goals>
            <configuration>
                <relocations>
                    <relocation>
                        <pattern>com.google.common</pattern>
                        <shadedPattern>my.shaded.com.google.common</shadedPattern>
                    </relocation>
                </relocations>
            </configuration>
        </execution>
    </executions>
</plugin>

→ 将冲突的类重命名，彻底隔离。

🔧 方案 5：调整类加载器（高级，慎用）

• 在 OSGi、Tomcat、WebLogic 等环境中，可通过配置类加载顺序解决
• 例如 Tomcat 的 context.xml 中设置 loader 优先级

🚫 五、常见误区

✅ 六、最佳实践

1. 定期执行 mvn dependency:analyze，清理无用依赖
2. 使用 dependencyManagement 统一版本
3. 在 CI 流程中加入 maven-enforcer-plugin
4. 避免手动拷贝 Jar 包到 lib 目录（破坏依赖管理）
5. 对核心库（如 Jackson、Guava、Log4j）严格锁定版本

🔚 总结

💡 记住：Jar 包冲突的本质是 “同一个类，多个实现”。解决的核心思路是 “确保运行时只有一个正确版本被加载”。

如果你提供具体的错误日志和 pom.xml 片段，我可以帮你精准定位冲突源！