本文详解如何通过 maven shade plugin 对特定依赖进行包重命名（shading），实现在同一项目中同时使用同一库的多个版本，避免版本冲突导致的运行时异常。
本文详解如何通过 maven shade plugin 对特定依赖进行包重命名（shading），实现在同一项目中同时使用同一库的多个版本，避免版本冲突导致的运行时异常。
在 Maven 的依赖解析机制中，传递性依赖的版本由“最近优先”（nearest definition）和“声明顺序”共同决定，但最终整个项目中每个 groupId:artifactId 只会保留一个实际生效的版本（即所谓的“版本仲裁”）。这意味着：当你显式声明 B:2.0，而依赖 A 内部依赖 B:1.0 时，Maven 默认会将 B:2.0 提升为统一版本——这极易引发 NoSuchMethodError、IncompatibleClassChangeError 等运行时问题，因为 A 的字节码是基于 B:1.0 编译的，无法兼容 B:2.0 的 API 或行为变更。
此时，单纯依靠
✅ 正确实践：Shade B:2.0 实现版本隔离
以下是在 pom.xml 中配置 Shade Plugin，将 dependency-B:2.0 重命名并内嵌到你的项目中：
<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>
<artifactSet>
<includes>
<include>group.id:dependency-B</include>
</includes>
</artifactSet>
<relocations>
<relocation>
<pattern>com.b.lib</pattern>
<shadedPattern>com.yourproject.shaded.com.b.lib</shadedPattern>
</relocation>
</relocations>
<outputFile>${project.build.directory}/${project.artifactId}-${project.version}-shaded.jar</outputFile>
<!-- 关键：不将 shaded 依赖导出为 compile 依赖 -->
<createDependencyReducedPom>false</createDependencyReducedPom>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>? 关键说明：
- artifactSet/includes 精确指定仅对 dependency-B:2.0 执行 shading；
- relocations 将其所有类从原始包（如 com.b.lib.*）迁移至新包（如 com.yourproject.shaded.com.b.lib.*）；
- createDependencyReducedPom=false 确保该 shaded jar 不参与依赖传递，避免污染下游模块；
- 最终你代码中需显式使用 com.yourproject.shaded.com.b.lib.Xxx 类，而非原生 com.b.lib.Xxx。
⚠️ 注意事项与替代建议
- Shading 是侵入性操作：需同步更新所有调用 B:2.0 的代码，改用 shaded 包路径；建议配合 IDE 重构工具批量替换。
- 不适用于含反射/资源加载/ServiceLoader 的库：若 B 依赖 META-INF/services/ 或硬编码类名，需额外配置 ServicesResourceTransformer 并重写服务提供者路径。
- 轻量级场景可考虑多模块拆分：将依赖 A 和依赖 B:2.0 的功能分别置于不同子模块，并通过 API 抽象层通信，物理隔离类路径。
- ❌ 避免滥用
provided 或true ：它们无法解决运行时类加载冲突，仅影响编译/传递范围。
✅ 总结
当 Maven 项目必须共存同一依赖（如 dependency-B）的多个不兼容版本时，唯一健壮且被生产验证的方案是使用 Shade Plugin 进行包重命名（shading）。它通过字节码重写实现运行时类隔离，确保 A 始终绑定 B:1.0，而你的业务代码安全使用 B:2.0 的 shaded 版本。务必注意包路径迁移、资源处理及测试覆盖，以保障稳定性。
