本文详解如何将 Maven 项目打包为可独立运行的 JAR，并确保所有第三方依赖（如 Spring、Kafka Streams）被正确包含或定位，支持 java -jar 一键启动。
本文详解如何将 maven 项目打包为可独立运行的 jar，并确保所有第三方依赖（如 spring、kafka streams）被正确包含或定位，支持 `java -jar` 一键启动。
在 Maven 项目中，执行 mvn package 默认仅将源码编译后的 class 文件打包进 JAR，而不会包含 pom.xml 中声明的依赖（如 spring-core、kafka-streams）。因此，直接运行 java -cp target/slab-1.0-SNAPSHOT.jar App 会因 ClassNotFoundException 或 NoClassDefFoundError 失败——这正是你遇到的问题根源。
解决该问题有两大主流方案：构建“胖 JAR”（Uber-JAR） 或 分离依赖 + 自动配置 Classpath。本文推荐后者（即“依赖外置 + Manifest 指定 classpath”），因其兼顾可维护性、签名兼容性与调试便利性，特别适合生产环境分发。
✅ 推荐方案：外置依赖 + 自动 Classpath 注入
通过 maven-dependency-plugin 将所有 runtime 依赖复制到 dist/lib/ 目录，并用 maven-jar-plugin 在 MANIFEST.MF 中自动写入 Class-Path 条目，最终实现 java -jar dist/slab-1.0-SNAPSHOT.jar 一键运行。
? 配置 pom.xml
在
立即学习“Java免费学习笔记（深入）”；
<properties>
<mainclass>me.jeusdi.slab.App</mainclass> <!-- 替换为你的主类全限定名 -->
</properties>
<build>
<plugins>
<!-- 步骤1：配置 JAR 的 MANIFEST -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version>
<configuration>
<outputDirectory>${project.build.directory}/dist</outputDirectory>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
<addClasspath>true</addClasspath>
<classpathPrefix>lib/</classpathPrefix>
<mainClass>${mainclass}</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<!-- 步骤2：复制依赖到 dist/lib -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.6.1</version>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/dist/lib</outputDirectory>
<includeScope>runtime</includeScope>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>? 关键说明：
- addClasspath=true 启用自动 Class-Path 生成；
- classpathPrefix=lib/ 表示依赖 JAR 位于 lib/ 子目录（相对路径）；
- includeScope=runtime 确保只复制 runtime 和 compile 范围依赖（排除 test、provided）；
- 主类必须通过 mainClass 显式指定，否则 java -jar 无法识别入口。
▶️ 构建与运行
执行以下命令完成构建：
mvn clean package
成功后，项目根目录下将生成：
target/dist/
├── slab-1.0-SNAPSHOT.jar ← 含 MANIFEST.MF（含 Class-Path: lib/spring-core-6.0.5.jar lib/kafka-streams-3.4.0.jar ...）
└── lib/
├── spring-core-6.0.5.jar
├── spring-context-6.0.5.jar
├── kafka-streams-3.4.0.jar
└── ... （其他依赖）随后即可直接运行：
java -jar target/dist/slab-1.0-SNAPSHOT.jar
✅ JVM 将自动按 MANIFEST.MF 中的 Class-Path 加载所有依赖，无需手动 -cp。
⚠️ 注意事项与最佳实践
- 签名兼容性：此方案保留原始依赖 JAR 的数字签名（如 Spring 官方发布的 JAR），避免 Uber-JAR 可能导致的 SecurityException，符合企业安全审计要求。
- 目录结构不可变：slab-1.0-SNAPSHOT.jar 必须与 lib/ 目录同级；移动 JAR 时务必同步移动整个 dist/ 文件夹。
-
避免版本冲突：若多个依赖传递引入同一库的不同版本，Maven 默认采用“最近胜利”策略；建议配合 mvn dependency:tree -Dverbose 检查并用
显式排除冗余。 -
替代方案对比：
- spring-boot-maven-plugin（推荐用于 Spring Boot 项目）：自动生成 fat jar，但会重打包所有类，破坏原始签名；
- maven-shade-plugin：生成真正单文件 uber-jar，适合 CLI 工具分发，但不适用于需验证依赖签名的场景。
✅ 总结
Maven 默认不打包依赖是设计使然，而非缺陷。通过组合 maven-jar-plugin 与 maven-dependency-plugin，你能在保持依赖完整性、签名有效性与部署灵活性的前提下，实现专业级的 Java 应用分发。只需一次配置，后续 mvn package && java -jar 即可开箱即用——这才是企业级 Java 项目的可持续交付之道。
