如何在 Maven 项目中同时使用同一依赖的不同版本

花韻仙語

发布时间：2026-02-21 10:35:11

985人浏览过

来源于php中文网

原创

如何在 Maven 项目中同时使用同一依赖的不同版本

本文详解如何通过 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），二者互不干扰。

视野自助系统小型企业版2.0 Build 20050310

自定义设置的程度更高可以满足大部分中小型企业的建站需求，同时修正了上一版中发现的BUG，优化了核心的代码占用的服务器资源更少，执行速度比上一版更快主要的特色功能如下： 1）特色的菜单设置功能，菜单设置分为顶部菜单和底部菜单，每一项都可以进行更名、选择是否隐藏，排序等。 2）增加企业基本信息设置功能，输入的企业信息可以在网页底部的醒目位置看到。 3）增加了在线编辑功能，输入产品信息，企业介绍等栏

下载

✅ 实施步骤（以依赖 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 插件打包进最终产物。

⚠️ 注意事项与最佳实践

Shading 是侵入性操作：被重定位的类中若含反射调用、SPI 配置（如 META-INF/services/）、或硬编码的类名字符串，需同步更新，否则运行时报错；
避免过度 shading：仅对确实存在版本冲突的依赖做处理，不要盲目 shade 整个依赖树；
测试必须覆盖双版本场景：验证 A 的行为是否仍符合 v1.0 语义，且您的逻辑正确使用 v2.0；
替代方案对比：
- exclusion：仅能排除传递依赖，无法引入新版本；
- dependencyManagement：只能统一版本，无法并存；
- OSGi / JPMS：适合大型模块化系统，但复杂度高，Maven 普通项目不推荐；
生产构建建议：将 shaded 构建产物作为独立模块（如 myapp-shaded-b），便于复用与版本管控。