Maven项目如何配置插件实现源码与依赖库的合并打包

1. 为什么需要合并打包源码与依赖库

第一次用Maven打包Java项目时，我踩过一个典型的坑：本地运行好好的程序，打成jar包后死活报ClassNotFoundException。折腾半天才发现，默认的maven package命令只会打包项目源码，那些引入的第三方依赖库全都被扔在了外面。这就好比搬家时只打包了自己的衣服，把家具电器全留在旧房子里——新家根本没法正常生活。

在传统Java项目部署场景中，这种"裸奔"的jar包会带来很多麻烦。比如你需要部署一个Web服务，总不能要求服务器上预先安装好所有依赖的Jar包吧？这时候就需要把项目源码和所有依赖库合并打包成一个"胖Jar"(Fat Jar)，就像Spring Boot项目默认做的那样。我接手过几个老项目，发现这种需求在传统Maven项目中特别常见。

合并打包主要解决两个核心问题：一是解决类加载问题，确保所有依赖在运行时可用；二是简化部署流程，真正做到"一次打包，到处运行"。想象你要给客户演示项目，总不能带着几十个依赖Jar包到处跑吧？一个包含所有依赖的可执行Jar才是王道。

2. Maven Assembly Plugin实战配置

2.1 基础配置详解

Maven Assembly Plugin是我最早接触的合并打包工具，它的配置虽然略显繁琐，但功能非常可靠。先来看一个完整的配置案例：

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-assembly-plugin</artifactId> <version>3.3.0</version> <configuration> <archive> <manifest> <mainClass>com.example.MainApp</mainClass> </manifest> </archive> <descriptorRefs> <descriptorRef>jar-with-dependencies</descriptorRef> </descriptorRefs> <appendAssemblyId>false</appendAssemblyId> </configuration> <executions> <execution> <id>make-assembly</id> <phase>package</phase> <goals> <goal>single</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

这里有几个关键配置需要注意：

• descriptorRefs：指定打包描述符，jar-with-dependencies表示包含所有依赖
• appendAssemblyId：控制生成文件的后缀，设为false可以去掉冗长的"-jar-with-dependencies"
• executions：绑定到package阶段，执行mvn package时会自动触发打包

2.2 常见问题排查

在实际使用中，我遇到过几个典型问题。首先是主类配置错误，会导致打包后无法用java -jar运行。建议在配置mainClass时，先在本地的target/classes目录下确认类路径是否正确。

另一个坑是依赖冲突。当多个依赖包含相同类时，Assembly Plugin默认不会处理这种冲突。这时可以配置来精确控制包含哪些依赖：

<configuration> <dependencySets> <dependencySet> <includes> <include>com.google.guava:guava</include> </includes> </dependencySet> </dependencySets> </configuration>

3. Maven Shade Plugin高级用法

3.1 基础配置与优势

相比Assembly Plugin，Maven Shade Plugin的配置更加简洁，也是Spring Boot底层使用的方案。基础配置如下：

<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> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>com.example.MainApp</mainClass> </transformer> </transformers> </configuration> </execution> </executions> </plugin>

Shade Plugin有几个明显优势：

1. 自动处理依赖冲突，可以通过配置策略
2. 支持资源文件合并，比如多个依赖的META-INF/services文件
3. 生成的jar包结构更简洁，不会产生original-前缀文件

3.2 高级特性实践

在复杂项目中，我经常用到Shade Plugin的资源转换功能。比如需要合并多个库的配置文件时：

<transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"> <resource>META-INF/spring.handlers</resource> </transformer> <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"> <resource>META-INF/spring.schemas</resource> </transformer> </transformers>

对于依赖冲突问题，可以通过精确控制：

<filters> <filter> <artifact>log4j:log4j</artifact> <excludes> <exclude>org/apache/log4j/varia/**</exclude> </excludes> </filter> </filters>

4. 两种方案的对比与选型建议

4.1 功能对比

通过实际项目验证，我整理了两个插件的主要区别：

4.2 选型建议

根据我的经验，简单项目用Assembly Plugin就足够了。但当遇到以下场景时，Shade Plugin是更好的选择：

• 项目依赖复杂，存在大量冲突风险
• 需要合并资源文件（如Spring配置）
• 希望保持干净的输出结构
• 后续可能升级到Spring Boot

有个实际案例：我们有个数据转换工具要提供给客户使用，依赖了5个不同的JSON处理库。用Assembly Plugin打包后经常报类冲突，改用Shade Plugin配置冲突解决策略后问题迎刃而解。

5. 进阶技巧与避坑指南

5.1 签名与验证问题

在金融项目中，我们遇到过jar包签名失效的问题。这是因为合并打包会修改class文件，导致原有签名被破坏。解决方案是在打包完成后重新签名：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jarsigner-plugin</artifactId> <executions> <execution> <id>sign</id> <phase>verify</phase> <goals> <goal>sign</goal> </goals> </execution> </executions> </plugin>

5.2 性能优化技巧

大型项目打包时可能会遇到内存溢出，可以通过调整JVM参数解决：

export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m" mvn clean package

另外，使用可以显著减小包体积：

<configuration> <minimizeJar>true</minimizeJar> </configuration>

5.3 多环境打包策略

在实际开发中，我们经常需要为不同环境打不同的包。可以通过profile实现：

<profiles> <profile> <id>prod</id> <build> <plugins> <plugin> <configuration> <excludes> <exclude>**/test/**</exclude> </excludes> </configuration> </plugin> </plugins> </build> </profile> </profiles>

使用时指定profile：

mvn package -Pprod

6. 真实项目案例解析

去年重构一个遗留系统时，我遇到一个典型场景：需要将一个包含20+依赖的Web应用打包成独立可执行jar。最初使用Assembly Plugin，但遇到了：

1. 依赖冲突导致运行时异常
2. 静态资源加载失败
3. 包体积过大（超过100MB）

最终解决方案是：

1. 改用Shade Plugin处理依赖冲突
2. 配置资源转换器合并web.xml
3. 使用排除不必要的依赖
4. 启用移除无用类

改造后的配置如下：

<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> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>com.company.Main</mainClass> </transformer> <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"> <resource>META-INF/spring.handlers</resource> </transformer> </transformers> <filters> <filter> <artifact>*:*</artifact> <excludes> <exclude>META-INF/*.SF</exclude> <exclude>META-INF/*.DSA</exclude> </excludes> </filter> </filters> <minimizeJar>true</minimizeJar> </configuration> </execution> </executions> </plugin>

这个配置成功将包体积减小到45MB，且在各种环境下运行稳定。关键点在于排除了签名文件，合并了Spring配置，并启用了jar最小化。