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><transformerimplementation="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><transformerimplementation="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-jarxxx-shaded.jar