本文详解如何通过 maven shade plugin 对依赖进行包重定位（shading），实现在同一项目中安全共存同一依赖的多个版本，避免版本冲突导致的运行时异常。
本文详解如何通过 maven shade plugin 对依赖进行包重定位（shading），实现在同一项目中安全共存同一依赖的多个版本，避免版本冲突导致的运行时异常。
在 Maven 的依赖解析机制中，传递性依赖遵循“最近优先”与“声明优先”原则：当项目直接声明了依赖 B（v2.0），而依赖 A 内部又依赖 B（v1.0）时，Maven 默认会将 v2.0 “提升”为整个项目中 B 的统一版本——这会导致 A 在运行时意外调用 v2.0 的 API，从而引发 NoSuchMethodError、IncompatibleClassChangeError 或逻辑异常。此时，简单的
真正可行的解决方案是 依赖隔离（Dependency Shading）：使用 maven-shade-plugin 将其中一个版本（通常是您主动引入的 v2.0）重命名并重新打包到自定义包路径下，使其与原始依赖（A 所需的 v1.0）完全解耦。这样，A 仍加载 org.example.b.*（v1.0），而您的代码则使用 com.myproject.shaded.b.*（v2.0），二者互不干扰。
✅ 实施步骤（以依赖 B v2.0 为例）
- 在 pom.xml 中添加 shaded 依赖（v2.0）并配置 Shade 插件：
<dependencies>
<!-- 依赖 A（自动拉取其所需的 B v1.0） -->
<dependency>
<groupId>com.example</groupId>
<artifactId>dependency-a</artifactId>
<version>3.5.0</version>
</dependency>
<!-- 显式引入 B v2.0，但不直接暴露其原始包名 -->
<dependency>
<groupId>org.example</groupId>
<artifactId>dependency-b</artifactId>
<version>2.0.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.1</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<artifactSet>
<includes>
<include>org.example:dependency-b</include>
</includes>
</artifactSet>
<relocations>
<relocation>
<pattern>org.example.b</pattern>
<shadedPattern>com.myproject.shaded.b</shadedPattern>
</relocation>
</relocations>
<outputFile>${project.build.directory}/${project.artifactId}-${project.version}-shaded.jar</outputFile>
<!-- 关键：不将 shaded 依赖打入主 jar，仅用于编译期引用 -->
<createDependencyReducedPom>false</createDependencyReducedPom>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>- 在代码中使用 shaded 版本：
// ✅ 正确：使用重定位后的类（v2.0）
import com.myproject.shaded.b.ServiceV2;
public class MyService {
public void doSomething() {
ServiceV2 service = new ServiceV2(); // 调用 v2.0 功能
service.execute();
}
}
// ❌ 错误：避免直接 import 原始包（否则可能意外绑定 v1.0）
// import org.example.b.ServiceV2; // 不要这样写！-
确保编译期可用性：
- 若需在编译阶段引用 dependency-b v2.0 的 API，可保留其
compile （默认），但必须配合 Shade 插件完成包隔离； - 若仅需运行时隔离，也可设为
provided 并由 Shade 插件打包进最终产物。
- 若需在编译阶段引用 dependency-b v2.0 的 API，可保留其
⚠️ 注意事项与最佳实践
- Shading 是侵入性操作：被重定位的类中若含反射调用、SPI 配置（如 META-INF/services/）、或硬编码的类名字符串，需同步更新，否则运行时报错；
- 避免过度 shading：仅对确实存在版本冲突的依赖做处理，不要盲目 shade 整个依赖树；
- 测试必须覆盖双版本场景：验证 A 的行为是否仍符合 v1.0 语义，且您的逻辑正确使用 v2.0；
-
替代方案对比：
- exclusion：仅能排除传递依赖，无法引入新版本；
- dependencyManagement：只能统一版本，无法并存；
- OSGi / JPMS：适合大型模块化系统，但复杂度高，Maven 普通项目不推荐；
- 生产构建建议：将 shaded 构建产物作为独立模块（如 myapp-shaded-b），便于复用与版本管控。
通过合理使用 Maven Shade Plugin 进行包重定位，开发者可在保持依赖 A 完整兼容性的同时，灵活接入新版功能组件，是解决“同依赖多版本共存”这一经典难题的专业级实践方案。
