Maven build配置 补

maven-shade-plugin 插件（基础用法+自定义按需打包）

一、maven-shade-plugin 简介

maven-shade-plugin 是 Apache Maven 官方 推出的打包插件，也是Java开发中最常用的FatJar打包工具。

核心两大作用：

1. 将项目自身代码+项目所有依赖Jar包，合并打包成一个独立可运行的uber-jar/fat-jar；
2. 支持对依赖包路径进行重命名（Shade），从底层解决项目依赖版本冲突、类名重复冲突问题。

最新稳定版官方坐标

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.6.2</version>

二、插件核心能力

1. 一键打包整合所有依赖

普通 mvn package 仅打包项目自身代码，不引入任何第三方依赖，部署运行容易出现依赖缺失。

而 shade 插件会自动解压 compile、runtime 作用域下所有依赖，统一合并到最终Jar包中。

打包后会生成两个文件：

• 原始Jar：项目名-版本.jar，仅包含项目自身代码
• 聚合Jar：项目名-版本-shaded.jar，包含项目代码+所有依赖

2. 依赖包重定向，解决版本冲突

当项目同时引入同一个框架不同版本（如protobuf、Jackson、Guava等），会出现类重复、NoClassDefFoundError 等异常。

shade 支持字节码层面改写包名 ，无需修改业务源码，实现依赖隔离：

示例：将com.google.protobuf 重命名为 shaded.com.google.protobuf，并自动修改项目内所有引用，彻底规避冲突。

3. 资源合并与精简过滤

1. 自动合并多个依赖中同名META-INF配置资源；
2. 灵活剔除无用资源：签名文件、测试类、冗余配置等；
3. 开启minimizeJar自动扫描代码引用，剔除未使用类，大幅压缩Jar体积。

三、基础pom.xml配置

1. 最简基础配置

直接绑定Maven打包生命周期，执行打包自动生效

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-shade-plugin</artifactId>
      <version>3.6.2</version>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>shade</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

2. 增强实用配置（可运行Jar+冲突解决+资源过滤）

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.6.2</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals><goal>shade</goal></goals>
      <configuration>
        <!-- 指定程序入口主类，支持java -jar直接运行 -->
        <transformers>
          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
            <mainClass>com.example.MyMain</mainClass>
          </transformer>
        </transformers>

        <!-- 依赖包重定向，解决版本冲突 -->
        <relocations>
          <relocation>
            <pattern>com.google.protobuf</pattern>
            <shadedPattern>shaded.com.google.protobuf</shadedPattern>
          </relocation>
        </relocations>

        <!-- 全局资源过滤，剔除无用文件 -->
        <filters>
          <filter>
            <artifact>*:*</artifact>
            <excludes>
              <exclude>META-INF/*.SF</exclude>
              <exclude>META-INF/*.DSA</exclude>
              <exclude>**/*.tests</exclude>
            </excludes>
          </filter>
        </filters>

        <!-- 开启Jar包自动精简 -->
        <minimizeJar>true</minimizeJar>
      </configuration>
    </execution>
  </executions>
</plugin>

四、核心配置参数说明

1. <phase>package</phase>：绑定Maven打包阶段，执行mvn package自动执行打包
2. <mainClass>：配置Jar包启动入口类
3. <relocation>：依赖重定向规则，pattern为原包名，shadedPattern为新包名
4. <filters>：按依赖维度过滤类文件与配置资源，支持通配符
5. <minimizeJar>：开启字节码分析，自动删除项目未引用的闲置类

五、插件优缺点

优点

1. 单文件打包部署，彻底避免线上依赖缺失问题
2. 依赖重定向功能强大，完美解决多版本依赖冲突
3. 所有操作均在打包阶段完成，不改动业务源码
4. 通用性强，支持所有Java普通项目、大数据项目

缺点

1. 全量依赖打包会导致Jar包体积偏大
2. 重定向后的类带有shaded前缀，线上问题排查调试稍繁琐
3. 大型多模块项目容易出现资源重复冲突，需要精细过滤

六、常用业务使用场景

1. 普通Java工具项目、独立后台程序打包发布
2. 项目存在多版本第三方依赖，需要解决类冲突
3. 封装通用SDK、公共工具包，对外提供一体化Jar包
4. Spark、Flink大数据任务打包，集群直接运行无需上传依赖

七、同类打包插件对比

1. maven-assembly-plugin ：仅能打包聚合依赖，不支持依赖重命名，无法解决版本冲突
2. spring-boot-maven-plugin：SpringBoot专属打包插件，内置shade核心能力，仅适配Boot项目
3. maven-shade-plugin：通用型最强，无框架限制，兼顾打包、冲突解决、自定义筛选

八、高级用法：按需自定义打包（自选依赖打包）

很多场景不需要打包全部依赖，maven-shade-plugin 支持自由选择打包内容，可按需打包指定依赖、剔除多余依赖，灵活度极高。

1. 只打包项目自身代码，排除所有第三方依赖

<configuration>
    <keepDependenciesWithProvidedScope>false</keepDependenciesWithProvidedScope>
    <artifactSet>
        <excludes>
            <exclude>*:*</exclude>
        </excludes>
    </artifactSet>
</configuration>

2. 白名单模式：仅打包指定依赖（最常用）

只引入业务必需依赖，其余全部排除

<artifactSet>
    <!-- 只打包指定依赖 -->
    <includes>
        <include>com.alibaba:fastjson</include>
        <include>org.slf4j:slf4j-api</include>
    </includes>
    <!-- 全局排除指定依赖 -->
    <excludes>
        <exclude>org.springframework:*</exclude>
        <exclude>commons-logging:*</exclude>
    </excludes>
</artifactSet>

3. 精准到包级别过滤打包

指定只打包项目内部指定业务包，过滤无用类

<filters>
    <filter>
        <artifact>*:*</artifact>
        <includes>
            <include>com.xxx.biz/**</include>
            <include>com.xxx.util/**</include>
        </includes>
        <excludes>
            <exclude>**/Test*.class</exclude>
            <exclude>**/entity/temp/**</exclude>
        </excludes>
    </filter>
</filters>

4. 自选打包完整整合配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.6.2</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <!-- 按需选择依赖 -->
                <artifactSet>
                    <includes>
                        <include>需要引入的依赖GAV坐标</include>
                    </includes>
                    <excludes>
                        <exclude>需要剔除的依赖</exclude>
                    </excludes>
                </artifactSet>

                <!-- 过滤无用资源 -->
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                            <exclude>META-INF/*.DSA</exclude>
                        </excludes>
                    </filter>
                </filters>

                <!-- 指定启动主类 -->
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.xxx.Main</mainClass>
                    </transformer>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

5. 按需打包三大实用场景

1. 仅打包项目源码，不带任何第三方依赖
2. 项目源码 + 少量指定核心依赖，轻量化打包
3. 默认打包全部依赖，仅剔除冲突、无用依赖

九、打包执行命令

mvn clean package

执行完成后，target 目录下 xxx-shaded.jar 即为最终自定义打包完成的Jar包，直接使用以下命令运行：

java -jar xxx-shaded.jar