Java 打包运行：如何包含 Maven 依赖项

本文深入解析了 Maven 项目打包为可独立运行 JAR 时如何正确处理第三方依赖（如 Spring、Kafka Streams）的核心难题，直击 `java -jar` 启动失败的常见根源——默认打包不包含依赖导致的类加载异常；重点推荐并手把手演示了“外置依赖 + MANIFEST.MF 自动 Class-Path 注入”这一兼顾安全性、可维护性与生产合规性的最佳实践：通过 `maven-dependency-plugin` 将 runtime 依赖精准复制到 `dist/lib/`，再由 `maven-jar-plugin` 自动生成带路径引用的清单文件，最终实现一键运行、签名无损、调试友好、审计友好的企业级分发方案。

本文详解如何将 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

在 中添加以下两个插件（注意：需定义 mainClass 属性）：

<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 项目的可持续交付之道。

到这里，我们也就讲完了《Java 打包运行：如何包含 Maven 依赖项》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！