构建与依赖 / 系统课时
创建包含依赖的可执行 JAR
创建包含依赖的可执行 JAR
普通 mvn package 生成的 JAR 通常只含本项目类,直接执行时仍可能缺少第三方依赖。本课用 Maven Shade Plugin 3.6.2 把项目类、运行时依赖和入口清单合并成一个 JAR,并给出资源冲突与类名冲突的处理办法。
学习目标
- 配置 Shade Plugin,在
package阶段生成可直接java -jar运行的单一 JAR。 - 使用
ManifestResourceTransformer和ServicesResourceTransformer正确处理入口与服务发现资源。 - 能区分资源冲突、签名文件冲突和类包冲突,并用对应手段验证修复结果。
准备一个能证明依赖已打包的入口类
以下示例使用 org.apache.commons:commons-lang3:3.17.0,入口类放在 src/main/java/com/example/App.java。代码故意调用第三方类;如果最终 JAR 没有包含依赖,运行时会立刻出现 NoClassDefFoundError,因此很适合作为验收样例。
package com.example;
import org.apache.commons.lang3.StringUtils;
public class App {
public static void main(String[] args) {
// 调用第三方依赖,验证它确实进入最终可执行 JAR。
String message = StringUtils.upperCase("Maven Shade Ready");
System.out.println(message);
}
}预期结果(完成下一节打包并执行后)
MAVEN SHADE READY用 Shade Plugin 合并依赖并写入 Main-Class
示例固定使用 Maven Shade Plugin 3.6.2;该版本要求 Maven 3.6.3 及以上、JDK 8 及以上来运行插件。下面的 pom.xml 可直接配合上一节入口类使用,最终主制品仍命名为 demo-app-1.0.0.jar。
<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>demo-app</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.17.0</version>
</dependency>
</dependencies>
<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>
<configuration>
<!-- Shading 后原依赖签名失效,避免把旧签名带入新 JAR。 -->
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
<transformers>
<!-- 合并多个依赖中的 META-INF/services 服务提供者文件。 -->
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
<!-- 写入 java -jar 所需的 Main-Class。 -->
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.example.App</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>这条合并链路同时处理项目字节码、依赖字节码和特殊资源,普通的同名资源并不会自动得到语义正确的“合并”。需要合并的资源必须选择对应 transformer,签名文件则应在内容已被改写后排除。

执行完整打包命令:
mvn clean package预期输出的关键结尾
[INFO] BUILD SUCCESS处理资源合并与类包冲突
ServicesResourceTransformer 只负责 META-INF/services 一类服务发现资源;它会把多个依赖中的实现类记录追加到同一个服务描述文件。若项目依赖 SPI、JDBC 驱动或其他 ServiceLoader 机制,遗漏它可能导致打包成功但运行时找不到实现。
先用依赖树确认冲突来自哪里。下面命令针对示例依赖,实际项目可替换为自己的 groupId:artifactId:
mvn dependency:tree -Dincludes=org.apache.commons:commons-lang3预期输出的关键行
[INFO] com.example:demo-app:jar:1.0.0
[INFO] \- org.apache.commons:commons-lang3:jar:3.17.0:compile
[INFO] BUILD SUCCESS如果两个不同依赖携带相同包名,或你要把内嵌库与宿主环境隔离,可以使用 relocation。下面是片段示例,放入 Shade 的 <configuration> 内;它会把该包及字节码中的引用一起改写,反射字符串和外部配置仍需单独验证。
<relocations>
<relocation>
<pattern>org.apache.commons.lang3</pattern>
<shadedPattern>internal.shadow.org.apache.commons.lang3</shadedPattern>
</relocation>
</relocations>生效后重新运行测试和最终 JAR;如果第三方框架通过字符串反射原包名,不能只凭构建成功判断 relocation 安全。
验证最终 JAR 是否真的可独立运行
先直接执行最终制品。Shade 默认在未附加 classifier 时把 shaded JAR 作为项目主制品,因此本例运行 target/demo-app-1.0.0.jar,而不是依赖额外的 -cp 参数。
java -jar target/demo-app-1.0.0.jar预期输出
MAVEN SHADE READY出现 no main manifest attribute 时检查 ManifestResourceTransformer 的 mainClass;出现 NoClassDefFoundError 时检查依赖 scope、过滤规则和依赖树;只有 SPI 功能失效时,优先检查 META-INF/services 是否经过 ServicesResourceTransformer 合并。