快捷導(dǎo)航

解決項(xiàng)目版本沖突之maven-shade插件使用方式

更新時(shí)間：2026年05月17日 10:30:22 作者：數(shù)據(jù)與算法架構(gòu)提升之路

本文介紹了在Maven項(xiàng)目中如何處理三方依賴與已有依賴沖突的問題,使用maven-shade-plugin插件實(shí)現(xiàn)依賴隔離,同時(shí)避免版本不一致導(dǎo)致項(xiàng)目異常,通過重命名依賴包名實(shí)現(xiàn)不同版本共存,解決三方依賴版本不一致問題,另外還提到了在使用過程中一些坑點(diǎn)和解決方案

背景

當(dāng)我們?cè)趍aven項(xiàng)目中引入第三方組件時(shí)，三方組件中的依賴可能會(huì)與項(xiàng)目已有組件發(fā)生沖突。

比如三方組件中依賴httpclient的版本是4.5.x，而項(xiàng)目中已有的httpclient版本是3.1.x，那么此時(shí)就會(huì)產(chǎn)生一下兩種情況：

如果用三方組件的高版本httpclient覆蓋原有的低版本httpclient，有可能會(huì)導(dǎo)致原來(lái)項(xiàng)目啟動(dòng)運(yùn)行失敗。即使高版本兼容低版本，也不能允許開發(fā)人員有這樣高風(fēng)險(xiǎn)的操作
如果在三方maven依賴中對(duì)其對(duì)依賴的httpclient在引入時(shí)使用進(jìn)行排除，使三方組件使用項(xiàng)目中的低版本httpclient，此時(shí)可能會(huì)因?yàn)榘姹静灰恢聦?dǎo)致三方組件無(wú)法使用

在這樣的情況下我們應(yīng)當(dāng)如何保證不影響項(xiàng)目原有依賴版本的情況下正常使用三方組件呢？此時(shí)可以考慮使用maven-shade-plugin插件

maven-shade-plugin介紹

maven-shade-plugin在maven官方網(wǎng)站中提供的一個(gè)插件，官方文檔中定義其功能如下：

This plugin provides the capability to package the artifact in an uber-jar, including its dependencies and to shade - i.e. rename - the packages of some of the dependencies.

簡(jiǎn)單來(lái)說就是將依賴的包在package階段一起打入jar包中，以及對(duì)依賴的jar包進(jìn)行重命名從而達(dá)到隔離的作用。這里為了解決上面的問題我們主要使用第二個(gè)功能特性，使得相同依賴不同版本達(dá)到共存的目的。

解決問題

1.環(huán)境準(zhǔn)備

這里用fastjson來(lái)模擬使用maven-shade-plugin解決項(xiàng)目中不同版本共存問題。原項(xiàng)目此時(shí)使用的是1.1.15版本的fastjson

<!-- 原項(xiàng)目 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.1.15</version>
</dependency>

假引入一個(gè)三方依賴，該依賴使用1.2.75版本的fastjson

<!-- 將引入依賴 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.75</version>
</dependency>

2.解決方案

搭建一個(gè)新的模塊rename-dependencies，專門用于存放1.2.75依賴。在pom文件中添加1.2.75的依賴，然后添加maven-shade-plugin插件。rename-dependencies的pom如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <groupId>com.sk</groupId>
    <artifactId>rename-dependencies</artifactId>
    <version>1.0-SNAPSHOT</version>
    <modelVersion>4.0.0</modelVersion>
    <dependencies>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.75</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.4</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <filters>
                                <filter>
                                    <artifact>*:*</artifact>
                                    <excludes>
                                        <exclude>META-INF/*.SF</exclude>
                                        <exclude>META-INF/*.DSA</exclude>
                                        <exclude>META-INF/*.RSA</exclude>
                                    </excludes>
                                </filter>
                            </filters>
                            <relocations>
                                <relocation>
                                    <pattern>com.alibaba</pattern>
                                    <shadedPattern>shade.com.alibaba</shadedPattern>
                                </relocation>
                            </relocations>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

從配置文件中可以看到，由于maven-shade-plugin插件在解決這個(gè)問題上其實(shí)是通過對(duì)依賴進(jìn)行重命名而達(dá)到隔離的目的，所以配置主要是集中在relocations中。這里將以com.alibaba開頭的包全部重命名為以shade.com.alibaba開頭。

3.引入依賴

將rename-dependencies進(jìn)行打包，打包好之后在原項(xiàng)目中引入rename-dependencies的依賴。此時(shí)在引入rename-dependencies之后，可以在項(xiàng)目下看到該依賴中的fastjson包名發(fā)生了變化。此時(shí)在代碼中調(diào)用fastjson相關(guān)方法，會(huì)提示選擇所需要包，此時(shí)問題解決，兩個(gè)版本的fastjson可同時(shí)使用已經(jīng)兼容。

一些需要注意的坑

描述：引入依賴找不到重命名的shade包

原因：重命名的模塊和需要引入依賴的模塊在一個(gè)項(xiàng)目中，idea優(yōu)先找本項(xiàng)目，所以沒有走倉(cāng)庫(kù)

解決方案：

將模塊從項(xiàng)目maven中移除，右鍵項(xiàng)目-maven-unlink maven projects 新建一個(gè)項(xiàng)目專門來(lái)做依賴

maven-shade-plugins的其他使用打入和排除指定jar包。maven-shade-plugins還有個(gè)功能就是打入和排除指定的jar包，通過和指定。

官方配置示例

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.2.4</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <artifactSet>
                <excludes>
                  <exclude>classworlds:classworlds</exclude>
                  <exclude>junit:junit</exclude>
                  <exclude>jmock:*</exclude>
                  <exclude>*:xml-apis</exclude>
                  <exclude>org.apache.maven:lib:tests</exclude>
                  <exclude>log4j:log4j:jar:</exclude>
                </excludes>
              </artifactSet>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

官方配置示例

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.2.4</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <filters>
                <filter>
                  <artifact>junit:junit</artifact>
                  <includes>
                    <include>junit/framework/**</include>
                    <include>org/junit/**</include>
                  </includes>
                  <excludes>
                    <exclude>org/junit/experimental/**</exclude>
                    <exclude>org/junit/runners/**</exclude>
                  </excludes>
                </filter>
                <filter>
                  <artifact>*:*</artifact>
                  <excludes>
                    <exclude>META-INF/*.SF</exclude>
                    <exclude>META-INF/*.DSA</exclude>
                    <exclude>META-INF/*.RSA</exclude>
                  </excludes>
                </filter>
              </filters>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

排除包內(nèi)資源。

在上面的pom中使用maven-shade-plugin時(shí)，使用來(lái)對(duì)包內(nèi)META-INF下的一些資源進(jìn)行排除。

如上面的配置中排除META-INF下的資源文件

<filters>
    <filter>
        <artifact>*:*</artifact>
        <excludes>
            <exclude>META-INF/*.SF</exclude>
            <exclude>META-INF/*.DSA</exclude>
            <exclude>META-INF/*.RSA</exclude>
        </excludes>
    </filter>
</filters>