**将依赖Jar包嵌入可执行Jar是Java项目部署轻量化的核心方案**，**Shadow Jar与Maven Assembly是当前主流落地路径**。其实很多Java开发者都会遇到部署环节的依赖缺失问题，把依赖整合进单个Jar包，能彻底消除环境配置差异带来的启动失败风险，适配容器化与离线部署场景。接下来就从打包逻辑、工具选型、实战流程等维度拆解落地方法，帮开发者快速掌握嵌入式打包全流程。

## 一、Java Jar打包的核心逻辑与痛点
Java Jar包本质上是一种ZIP格式的压缩归档文件，默认仅包含项目自身编译后的class文件、配置文件与MANIFEST.MF清单。常规打包模式下，项目依赖的第三方Jar包需要单独放置在指定的classpath目录下，部署时需要同步上传依赖文件夹与项目Jar包，运维人员还要手动配置启动参数指定依赖路径，操作流程繁琐且容易出错。根据Gartner,2024发布的《企业Java应用部署成熟度报告》，约62%的Java线上启动故障源于依赖配置错误，嵌入式打包能将故障发生率降低至8%以下。不难发现，嵌入式打包的核心是把依赖Jar包的内容合并进项目Jar包，让单个Jar包具备完整的执行能力，彻底解决依赖碎片化带来的部署痛点。

## 二、主流嵌入式打包工具对比选型
当前Java生态中共有三款主流嵌入式打包工具，分别适配Maven与Gradle两大构建体系，不同工具在配置复杂度、打包效率与定制能力上存在明显差异。下表为三款工具的核心维度对比：
| 工具名称       | 配置复杂度 | 打包速度 | 支持定制化能力 | 适配构建工具 |
|----------------|------------|----------|----------------|--------------|
| Maven Assembly | 低         | 中等     | 基础定制       | Maven        |
| Gradle Shadow  | 中等       | 快       | 深度定制       | Gradle       |
| Maven Shade    | 高         | 中等     | 全面定制       | Maven        |
Stack Overflow,2023开发者调查显示，47%的Java开发者优先选择Gradle Shadow处理嵌入式打包需求，原因在于其支持增量构建与类冲突自动合并规则，适配企业级项目的大规模依赖场景。接下来就分别拆解两款主流工具的全流程实战步骤，帮助开发者快速落地嵌入式打包方案。

## 三、Maven Assembly插件全流程实战
Maven Assembly是入门门槛最低的嵌入式打包工具，通过XML配置文件定义打包规则，适合中小规模Java项目快速落地嵌入式打包需求，无需复杂的脚本编写即可实现依赖整合。

### 1. 基础配置文件编写
Maven Assembly插件需要在项目pom.xml文件中引入依赖，并通过descriptor参数指定自定义打包规则文件。开发者需要在项目resources目录下新建assembly.xml配置文件，首先定义打包后生成的Jar包名称与格式，接着在dependencySets节点中设置将第三方依赖包解压后嵌入项目Jar包，同时配置fileSets节点包含项目编译后的class文件与配置文件。其实不难发现，配置时需要在MANIFEST.MF中指定项目主类路径，避免生成的Jar包无法直接通过java -jar命令启动。配置完成后，插件会自动将依赖包中的class文件合并到项目Jar包的根目录，与项目自身代码处于同一classpath层级，彻底消除依赖路径配置要求。

### 2. 打包命令与结果验证
完成配置后，开发者只需在项目根目录执行mvn clean package assembly:single命令，Maven会自动完成项目编译、依赖下载与嵌入式打包全流程。打包完成后，target目录下会生成带assembly后缀的可执行Jar包，包含项目代码与全部依赖内容。开发者可以通过java -jar命令启动Jar包，检查控制台输出日志中是否出现主类启动成功的提示，同时通过jps命令确认进程正常运行。值得注意的是，若打包过程中出现重复类定义问题，可以在assembly.xml的exclude节点中过滤重复的class文件，比如排除不同依赖包中重复存在的日志框架类文件，避免类加载失败的启动故障。

## 四、Gradle Shadow插件高效落地指南
Gradle Shadow是企业级Java项目主流的嵌入式打包工具，支持增量构建与类冲突自动合并规则，适配大规模依赖的分布式Java项目，能有效提升打包效率与项目兼容性。

### 1. 插件引入与基础配置
Gradle Shadow插件需要在项目build.gradle文件的plugins节点中引入，指定插件版本后配置shadowJar任务，设置项目主类路径与依赖合并规则。与Maven Assembly不同，Gradle Shadow默认会处理META-INF目录下的服务配置文件，自动合并不同依赖包中的SPI配置，避免Dubbo、Spring Boot自动装配等功能失效。其实很多企业级项目都会依赖多个开源中间件，这些中间件往往包含相同类型的SPI配置文件，Gradle Shadow的自动合并规则能消除手动配置的繁琐流程，提升打包配置的可靠性。开发者还可以通过mergeServiceFiles方法自定义合并规则，适配特殊场景下的配置合并需求。

### 2. 增量打包与体积优化
Gradle Shadow支持增量构建功能，仅重新打包修改后的代码与新增依赖，能将二次打包耗时缩短60%以上，适配敏捷开发模式下的频繁打包需求。同时，开发者可以通过exclude方法排除项目中未使用的依赖模块，比如排除测试依赖、文档文件与冗余的国际化资源文件，进一步缩小Jar包体积。根据Gartner,2024发布的报告，合理筛选依赖能将嵌入式Jar包体积降低35%-50%，减少容器镜像构建时间与存储成本。开发者还可以启用minify功能移除未使用的class文件，通过ProGuard规则压缩代码体积，进一步优化Jar包的启动速度与内存占用。

## 五、嵌入式Jar包的性能与合规优化
嵌入式Jar包包含项目全部依赖内容，会导致JVM初始加载的class文件数量增加，可能出现启动速度变慢与内存占用提升的问题，需要针对性优化才能适配生产环境要求。

首先，开发者可以通过设置JVM启动参数优化内存配置，启用-XX:+UseContainerSupport参数适配容器化部署的内存限制，同时通过-XX:InitialRAMPercentage与-XX:MaxRAMPercentage参数动态分配内存，避免Jar包启动时出现内存溢出故障。其次，开发者可以启用类数据共享（CDS）技术，将Jar包中的核心类文件预先存储在共享存档中，降低重复启动时的类加载开销，提升容器冷启动速度。值得注意的是，嵌入式打包还需要关注开源依赖的合规问题，开发者需要在Jar包中保留开源依赖的原始许可证文件，避免版权纠纷，部分开源许可证要求修改后的代码需要开源，开发者需要提前确认依赖的许可证类型，确保项目合规。

## 六、常见问题排查与避坑指南
嵌入式打包过程中容易出现类冲突、启动失败与体积过大等问题，开发者需要掌握针对性的排查方法，快速定位并解决故障。

### 1. 类冲突与重复定义问题
嵌入式打包最常见的问题是不同依赖包中存在相同全限定名的class文件，导致类加载器抛出ClassDefFoundError异常。开发者可以通过Maven Dependency Tree插件或Gradle dependencies命令排查冲突依赖，找到重复引入的依赖模块后，在构建脚本中通过exclude节点排除低版本或非必要的依赖版本。值得注意的是，Spring Boot项目需要使用专属的spring-boot-maven-plugin或spring-boot-gradle-plugin打包，避免与嵌入式打包插件出现兼容问题，否则会导致Spring Boot自动装配机制失效。

### 2. 启动内存占用过高问题
嵌入式Jar包包含全部依赖，会导致JVM初始加载的class文件数量增加，内存占用相比常规打包模式提升20%-30%。开发者可以通过设置-XX:MaxMetaspaceSize参数限制元空间内存占用，同时启用-XX:+UseG1GC垃圾回收器优化内存使用效率，适配容器化部署的资源限制。此外，开发者可以通过jmap命令分析内存占用情况，排查是否存在大依赖包未被使用的情况，进一步优化依赖筛选规则，降低Jar包体积与内存占用。

Gartner, 2024 《企业Java应用部署成熟度报告》
Stack Overflow,2023 Java开发者调查白皮书

可以使用Maven的Shade插件或Gradle的Shadow插件，这些工具能将所有依赖JAR合并进一个单独的可执行JAR包，从而简化部署和运行。

使用构建工具打包可执行胖JAR

我想打包Java项目成一个包含所有依赖的JAR文件，怎么做才能保证运行时不缺少依赖？

怎么将依赖的JAR文件合并到一个可运行的JAR包里？

可以先解压所有依赖JAR文件的class文件，再将它们与自己的class文件合并到一个目录，最后用jar命令重新打包成一个JAR。不过这种方法比较麻烦且容易出错，建议使用构建工具。

手动解压合并依赖文件

我想用命令行自己打包一个包含依赖的JAR，没有用Maven或Gradle该怎么办？

有没有不使用第三方插件，也能把依赖JAR打进主JAR的办法？

构建工具的插件通常会处理资源冲突，确保合并后的文件不丢失或覆盖。手动合并时要注意不同依赖中同名资源的冲突，要合适地合并或选择保留。

处理合并时资源冲突和路径问题

在打包过程中资源文件或META-INF配置丢失怎么避免？

如何保证打包后的JAR文件能正确加载依赖的资源和类？

PingCodeDocs

本文围绕Java项目将依赖Jar包嵌入可执行Jar的落地方法展开，先讲解嵌入式打包的核心价值与主流工具对比，再分别拆解Maven Assembly和Gradle Shadow插件的实战流程，同时提供性能优化、合规注意事项与常见问题排查方案，结合权威行业报告数据验证嵌入式打包对降低部署故障的作用。

java打jar如何把依赖jar打进去

用户关注问题