本文介绍通过 maven shade plugin 对特定依赖进行包重命名（shading），实现在同一项目中安全共存同一库的多个版本，彻底解决因传递依赖版本覆盖导致的兼容性问题。
本文介绍通过 maven shade plugin 对特定依赖进行包重命名（shading），实现在同一项目中安全共存同一库的多个版本，彻底解决因传递依赖版本覆盖导致的兼容性问题。
在 Maven 的依赖解析机制中，版本仲裁（Version Resolution）遵循“最近优先”原则：当项目直接声明了依赖 B 的 2.0 版本，而依赖 A 传递引入了 B 的 1.0 版本时，Maven 默认会选择路径更短的直接声明（即 2.0），导致 A 在运行时实际加载的是 B-2.0 —— 这正是你遇到的兼容性崩溃根源。此时，单纯使用
✅ 推荐方案：使用 Maven Shade Plugin 进行依赖 Shading
Shade 插件可将指定依赖（如 B-2.0）及其所有字节码重命名包路径并重新打包进你的项目 JAR，使其与原始依赖（A 所用的 B-1.0）完全隔离。A 仍通过原包名（如 org.example.b.*）调用 B-1.0，而你的代码则通过新包名（如 shaded.org.example.b.*）调用 B-2.0，互不干扰。
▶ 示例配置（将 dependency B-2.0 进行 shading）
在 pom.xml 中添加 Shade 插件配置：
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<!-- 仅对 B-2.0 进行重命名，保留 A 的 B-1.0 不变 -->
<relocations>
<relocation>
<pattern>org.example.b.</pattern>
<shadedPattern>shaded.org.example.b.</shadedPattern>
</relocation>
</relocations>
<!-- 可选：排除不需要的资源，避免冲突 -->
<filters>
<filter>
<artifact>org.example:dependency-b</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
<!-- 确保 shaded 产物不包含主 JAR 的重复类 -->
<createDependencyReducedPom>false</createDependencyReducedPom>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>⚠️ 注意事项：
- Shading 仅影响你项目最终生成的 fat-jar（或 shade 输出），开发阶段 IDE 编译/调试时需配合 maven-shade-plugin 的 shade 目标执行，或使用 mvn clean package 触发。
- 被 shaded 的类在源码中需显式使用新包名引用（如 new shaded.org.example.b.SomeClass()），否则编译失败；建议将 B-2.0 的相关逻辑封装在独立模块或工具类中，降低侵入性。
- 若 B 是强反射型库（如依赖 Class.forName("org.example.b.X")），需同步修改反射字符串为 shaded.org.example.b.X，否则运行时报 ClassNotFoundException。
- 避免对日志框架（SLF4J、Log4j）、JSON 库（Jackson）等广泛被其他组件使用的基础设施类 shading，易引发隐式冲突。
? 替代方案对比（不推荐用于此场景）
| 方案 | 是否解决本问题 | 原因 |
|---|---|---|
| ❌ 否 | 导致 A 缺失必要类，启动失败 | |
| 使用 |
❌ 否 | 无法让 A 和你的代码分别使用不同版本 |
| 拆分为多模块项目（A 单独模块 + B-2.0 单独模块） | ⚠️ 有限适用 | 若 A 与你的代码无直接调用，可隔离类加载器，但增加架构复杂度，且无法解决同 JVM 内共存需求 |
✅ 总结
当必须在同一应用中使用同一依赖的多个不兼容版本时，Shading 是 Maven 生态中最成熟、最可控的技术方案。它不改变依赖本身的语义，而是通过字节码重写实现运行时隔离。关键在于：明确目标依赖（B-2.0）、精准配置包重命名规则、并在业务代码中适配新包路径。正确实施后，Project → A → B(1.0) 与 Project → shaded-B(2.0) 将彻底解耦，兼容性问题迎刃而解。
