Spring Boot项目Maven打包全攻略：从Fat Jar到Docker分层构建

1. 从一次失败的部署说起：为什么打包依赖如此重要

上周，团队里一个刚接手Spring Boot项目不久的新同事，在本地开发环境跑得风生水起的服务，一到测试服务器就“趴窝”了。控制台报错信息是经典的ClassNotFoundException，指向一个第三方工具类。他一脸困惑地问我：“哥，我代码都提交了，服务器上也执行了mvn clean package，怎么还会缺类呢？” 我让他把打出来的jar包解压看了一眼，问题一目了然：一个光秃秃的、只有项目自身编译后class文件的“瘦身”包。这其实就是典型的“依赖没打进包”的问题。对于Spring Boot这种“约定大于配置”的框架，很多开发者会默认认为Maven或Spring Boot插件已经处理好了一切，但实际情况是，打包方式的选择直接决定了你的应用能否独立运行。

“Spring Boot项目使用Maven打包并带上依赖”，这听起来像是一个基础到不能再基础的操作，但恰恰是这个基础环节，隐藏着不少细节和选择。它不仅仅是让程序跑起来，更关乎部署的便捷性、环境的一致性和最终产物的形态。今天，我们就来彻底拆解这个主题，从Maven的几种打包插件讲起，深入到配置的每一个参数，最后再分享几个我踩过坑才总结出来的实战经验。无论你是刚入门的新手，还是想梳理一下这块知识的老鸟，相信都能有所收获。

2. 核心打包策略解析：Fat Jar, Thin Jar 与 Docker 镜像

在动手配置之前，我们必须先理解Maven为Spring Boot项目提供的几种主流打包策略。选择哪种策略，取决于你的部署环境和运维习惯。

2.1 Spring Boot Maven Plugin 与可执行 Fat Jar

这是Spring Boot官方最推荐，也是最常见的方式。通过spring-boot-maven-plugin插件，可以生成一个所谓的 “Fat Jar” 或 “Uber Jar”。这个jar包是“肥胖”的，因为它不仅包含了项目自身编译后的所有类文件（在BOOT-INF/classes目录下），还把所有依赖的第三方库（在BOOT-INF/lib目录下）以及Spring Boot相关的启动加载器（org.springframework.boot.loader）都打包在了一起。

它的工作原理是：插件会重新组织jar包的结构，并提供一个特殊的JarLauncher类作为主入口。当你用java -jar yourapp.jar命令启动时，实际上是JarLauncher在负责创建一个特殊的类加载器，来加载BOOT-INF/lib下的依赖jar和BOOT-INF/classes下的应用类。这种方式的巨大优势在于部署极其简单，只需要一个jar文件和Java运行环境，真正实现了“开箱即用”，非常适合传统的虚拟机或物理机部署。

2.2 Maven Assembly Plugin：自定义打包布局

maven-assembly-plugin是一个更通用、更灵活的打包工具。它不局限于生成单一的jar文件，而是允许你通过一个assembly.xml描述符文件，定义最终打包产物的目录结构。对于Spring Boot项目，你可以用它来生成一个包含“依赖lib目录”、“配置文件目录”和“启动脚本”的发布包（通常是一个tar.gz或zip文件）。

例如，你可以配置将所有的依赖jar包复制到lib/目录下，将应用的jar包（不包含依赖）放在根目录，同时把application.yml和启动脚本（如.sh或.bat）也一并打包。这种方式的优点是结构清晰，便于运维人员查看和修改；同时，依赖库和业务代码分离，如果只更新业务代码，可以只替换应用jar，依赖库无需变动，在某些网络传输受限的场景下有一定优势。但缺点是需要自己编写启动脚本，并正确设置classpath指向lib/目录，部署步骤比Fat Jar稍复杂。

2.3 Maven Shade Plugin：重命名与依赖合并

maven-shade-plugin的功能比spring-boot-maven-plugin更“激进”。它不仅能创建包含依赖的Uber Jar，还能对依赖中的类进行重命名（Relocation），这是它最核心的特性。为什么要重命名？是为了解决依赖冲突。

想象一个场景：你的项目同时依赖了com.google.guava:guava的20.0版本和另一个第三方库some-library，而some-library内部又依赖了guava的18.0版本。Maven通常会根据“最近定义优先”的原则选择一个版本（比如20.0），但some-library中的代码可能调用了18.0版本中某个已被删除的方法，这就会导致运行时NoSuchMethodError。使用Shade插件，你可以将guava的类从原始的com.google.common包名，重定位到yourproject.shaded.com.google.common。这样，你的项目代码使用的是重命名后的、版本确定的guava，而some-library仍然使用它自带的、未被重命名的guava，两者互不干扰，从而彻底解决版本冲突。

不过，对于纯粹的Spring Boot应用，除非遇到棘手的、无法通过Maven依赖排除解决的类冲突，否则一般不需要动用Shade插件，官方的spring-boot-maven-plugin已经足够优秀和简便。

2.4 现代部署：Docker与分层构建（Layer）

在容器化部署成为主流的今天，打包策略又有了新的演进。Docker镜像的构建鼓励使用“分层”的概念，以利用镜像缓存，加快构建和推送速度。Spring Boot从2.3.0版本开始，其Maven插件原生支持创建“分层jar”（Layered Jar）。

这种打包方式会将Fat Jar进一步拆分成多个层：

  • 依赖层（dependencies）：所有BOOT-INF/lib下的第三方依赖jar。
  • 快照依赖层（spring-boot-loader）：Spring Boot的加载器类。
  • 应用层（application）：BOOT-INF/classes下的应用类文件和BOOT-INF/classpath.idx等资源。

在编写Dockerfile时，你可以分别将这些层复制到镜像中。这样，当你只修改了业务代码时，在下次构建Docker镜像时，“依赖层”和“快照依赖层”由于没有变化，可以直接使用缓存，只需要重新构建“应用层”，能极大提升CI/CD的效率。这是传统Fat Jar策略在云原生时代的优化延伸。

3. 手把手配置：三种主流方式的实战详解

理论说完了，我们进入实战环节。下面我将分别演示如何使用上述三种主要插件进行打包配置，并解释每个关键配置项的含义。

3.1 使用 Spring Boot Maven Plugin（推荐）

这是最省心的方式。在Spring Boot项目初始化时，pom.xml里通常已经包含了这个插件。

<build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <!-- 版本通常由 spring-boot-starter-parent 管理，无需显式指定 --> </plugin> </plugins> </build>

执行mvn clean package后，在target目录下你会找到两个jar文件：

  • your-app-0.0.1-SNAPSHOT.jar：这就是可执行的Fat Jar。
  • your-app-0.0.1-SNAPSHOT.jar.original：这是Maven标准插件打出的、不包含依赖的“瘦”jar。Spring Boot插件会以此为基础，重新打包成Fat Jar。

关键配置项解析：

  1. 指定主类：虽然Spring Boot通常能通过@SpringBootApplication注解自动找到主类，但显式指定是个好习惯，尤其是在多模块项目中。

    <configuration> <mainClass>com.yourcompany.yourapp.Application</mainClass> </configuration>

  2. 排除依赖：有些依赖你可能不希望打进Fat Jar，比如spring-boot-devtools（开发工具）或者tomcat-embed-jasper（如果你使用Undertow）。可以使用<excludes>。

    <configuration> <excludes> <exclude> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> </exclude> </excludes> </configuration>

  3. 启用分层构建（Layer）：要启用分层功能，需要显式配置。

    <configuration> <layers> <enabled>true</enabled> </layers> </configuration>

    打包后，除了生成jar，还会在target下生成一个layers.idx文件，定义了分层信息。同时，你可以使用java -Djarmode=layertools -jar your-app.jar list命令查看分层，使用extract命令解压出各层。

注意：使用spring-boot-maven-plugin时，确保你的项目继承了spring-boot-starter-parent或者在其dependencyManagement中引入了spring-boot-dependencies，这样才能管理插件版本和默认配置，避免版本冲突。

3.2 使用 Maven Assembly Plugin

当你需要生成一个包含目录结构的发布包时，Assembly插件是更好的选择。

首先，在pom.xml中引入插件：

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-assembly-plugin</artifactId> <version>3.6.0</version> <configuration> <!-- 指定描述符文件位置 --> <descriptor>src/assembly/package.xml</descriptor> <!-- 打包后生成的文件名后缀 --> <appendAssemblyId>false</appendAssemblyId> <finalName>${project.artifactId}-${project.version}-release</finalName> </configuration> <executions> <execution> <phase>package</phase> <goals> <goal>single</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

然后，在src/assembly/package.xml文件中定义打包结构：

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd"> <id>package</id> <formats> <format>tar.gz</format> <!-- 也可以同时生成zip: <format>zip</format> --> </formats> <includeBaseDirectory>false</includeBaseDirectory> <dependencySets> <dependencySet> <outputDirectory>/lib</outputDirectory> <scope>runtime</scope> <!-- 将runtime和compile范围的依赖放入lib --> <useProjectArtifact>false</useProjectArtifact> <!-- 不把项目自身的jar放进去 --> </dependencySet> </dependencySets> <fileSets> <!-- 将项目自身打出的瘦身jar包放到根目录 --> <fileSet> <directory>${project.build.directory}</directory> <outputDirectory>/</outputDirectory> <includes> <include>*.jar</include> </includes> <excludes> <exclude>*-sources.jar</exclude> <exclude>*-javadoc.jar</exclude> </excludes> </fileSet> <!-- 将配置文件目录打包进config文件夹 --> <fileSet> <directory>${project.basedir}/src/main/resources</directory> <outputDirectory>/config</outputDirectory> <includes> <include>**/*.yml</include> <include>**/*.properties</include> <include>**/*.xml</include> </includes> </fileSet> <!-- 包含启动脚本 --> <fileSet> <directory>${project.basedir}/scripts</directory> <outputDirectory>/</outputDirectory> <includes> <include>startup.sh</include> <include>startup.bat</include> </includes> <fileMode>0755</fileMode> <!-- 为shell脚本设置可执行权限 --> </fileSet> </fileSets> </assembly>

这样打包后，你会得到一个tar.gz文件，解压后目录结构清晰，包含lib/,config/, 启动脚本和主jar包。

3.3 使用 Maven Shade Plugin

Shade插件的配置相对复杂，主要用于解决依赖冲突。

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.5.0</version> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> <configuration> <createDependencyReducedPom>false</createDependencyReducedPom> <filters> <!-- 可选：过滤掉一些不需要的元文件，减少包体积 --> <filter> <artifact>*:*</artifact> <excludes> <exclude>META-INF/*.SF</exclude> <exclude>META-INF/*.DSA</exclude> <exclude>META-INF/*.RSA</exclude> </excludes> </filter> </filters> <relocations> <!-- 关键配置：重定位Guava类 --> <relocation> <pattern>com.google.common</pattern> <shadedPattern>com.yourproject.shaded.guava</shadedPattern> </relocation> <!-- 可以重定位多个有冲突的依赖 --> </relocations> <transformers> <!-- 合并多个jar包中的META-INF/services/下的文件，对使用Java SPI机制的服务很重要 --> <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/> <!-- 确保主类清单文件正确 --> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>com.yourcompany.yourapp.Application</mainClass> </transformer> </transformers> </configuration> </execution> </executions> </plugin> </plugins> </build>

配置完成后，执行mvn clean package，Shade插件会生成一个包含了重命名后依赖的Uber Jar。这里有一个巨大的坑：重命名后，你的项目代码中所有导入com.google.common包的地方，也必须相应修改为com.yourproject.shaded.guava，否则编译器会找不到类。这通常不是我们想要的。因此，Shade插件更常用于构建一个给下游使用的SDK或库，在这个库里解决掉自己的依赖冲突，然后对外提供一个干净的API，而不是用于构建一个可执行的Spring Boot应用。对于Spring Boot应用，优先使用依赖排除（<exclusions>）或统一版本管理来解决冲突。

4. 打包实战中的高频问题与深度排查

即使配置正确，在实际打包和运行过程中，依然会遇到各种问题。下面我梳理了几个最常见的问题及其排查思路。

4.1 依赖冲突：NoSuchMethodError 与 ClassNotFoundException

这是最令人头疼的问题之一。现象是：本地开发正常，打包后运行报错。

排查链路：

  1. 确认打包方式：首先检查打出的jar包是否真的包含了有问题的依赖。对于Fat Jar，可以用jar tf target/your-app.jar | grep -i ‘问题类所在包名’命令在终端查看。或者直接解压jar包，查看BOOT-INF/lib目录下是否存在预期的jar文件。

  2. 分析依赖树：使用Maven命令mvn dependency:tree -Dverbose生成详细的依赖树。-Dverbose参数会显示冲突和被忽略的依赖。在输出中搜索有问题的类所在的依赖（groupId:artifactId），看它被哪些路径引入，以及最终生效的是哪个版本。

    • 如果发现有两个版本，Maven默认会选择“依赖路径最近”的版本。你需要判断这个默认选择的版本是否兼容你的代码。

  3. 定位冲突根源：

    • 版本不兼容：如果生效的版本过低或过高，可能缺少某些方法或类。解决方案是在pom.xml中显式声明你需要的正确版本，Maven会优先使用直接声明的版本。
    • 重复依赖的不同版本：如果两个不同的第三方库（A和B）分别依赖了C库的v1和v2，而v1和v2不兼容。这时需要做“依赖排除”。
      <dependency> <groupId>com.library.A</groupId> <artifactId>A</artifactId> <version>1.0</version> <exclusions> <exclusion> <groupId>com.conflict.library</groupId> <artifactId>C</artifactId> </exclusion> </exclusions> </dependency>
      排除掉A库中的C，让项目统一使用B库引入的C版本，或者反过来。

  4. 使用Maven Helper插件（IDEA）：在IntelliJ IDEA中安装 “Maven Helper” 插件。打开pom.xml，底部会多出一个 “Dependency Analyzer” 标签页。在这里可以非常直观地看到所有依赖冲突（Conflicts），并一键排除。

4.2 资源文件丢失或路径错误

Spring Boot默认从classpath:或classpath:/config/等位置读取配置文件。但在打包后，资源文件的路径结构发生了变化。

问题场景：代码中使用ClassLoader.getResource(“somefile.txt”)或new File(“config/template.xml”)来获取资源，在IDE中运行正常，打包后返回null或FileNotFoundException。

原因与解决方案：

  • 原因：Fat Jar中，所有资源文件都被打包进了jar包内部。File对象无法直接访问jar包内的文件。ClassLoader.getResource可以，但路径是相对于classpath的。
  • 正确做法：
    1. 使用Spring的ResourceLoader或@Value(“classpath:…”)：这是最Spring的方式。
      @Autowired private ResourceLoader resourceLoader; Resource resource = resourceLoader.getResource(“classpath:template/email.html”);
    2. 使用ClassPathResource：
      Resource resource = new ClassPathResource(“template/email.html”, this.getClass().getClassLoader());
    3. 读取文件内容：得到Resource对象后，通过resource.getInputStream()来读取内容，而不是试图获取File对象。
  • 检查清单：确保资源文件位于src/main/resources目录或其子目录下。打包后，它们会出现在jar包的根路径或BOOT-INF/classes下。

4.3 打包速度慢与镜像构建优化

项目依赖越来越多后，每次打包都要复制上百个依赖jar，mvn clean package会变得很慢。

优化策略：

  1. 利用Docker分层缓存（Spring Boot 2.3+）：如前所述，使用分层jar。在Dockerfile中：

    FROM openjdk:11-jre-slim as builder WORKDIR application ARG JAR_FILE=target/*.jar COPY ${JAR_FILE} application.jar RUN java -Djarmode=layertools -jar application.jar extract FROM openjdk:11-jre-slim WORKDIR application COPY --from=builder application/dependencies/ ./ COPY --from=builder application/spring-boot-loader/ ./ COPY --from=builder application/snapshot-dependencies/ ./ COPY --from=builder application/application/ ./ ENTRYPOINT [“java”, “org.springframework.boot.loader.JarLauncher”]

    这样，只要pom.xml中依赖不变，dependencies层就会被缓存，大幅加速构建。

  2. 使用Maven离线模式与本地仓库：在CI/CD流水线中，可以维护一个稳定的本地Maven仓库镜像。使用mvn -o package（offline模式）可以禁止从远程仓库下载，强制使用本地缓存，前提是所需依赖已全部在本地。

  3. 区分打包环境：在pom.xml中通过<profiles>定义不同环境的配置。例如，开发环境可以跳过测试并排除一些不必要的插件执行。

    <profile> <id>dev</id> <properties> <skipTests>true</skipTests> </properties> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <skip>true</skip> <!-- 开发时可能不需要每次都打可执行jar --> </configuration> </plugin> </plugins> </build> </profile>

    使用mvn clean package -Pdev来加速开发阶段的打包。

4.4 特殊依赖处理：系统作用域与本地jar包

有些时候，你会遇到一些“非标准”的依赖。

  1. 系统作用域依赖（system scope）：这种依赖不从Maven仓库获取，而是指向本地文件系统的一个绝对路径。强烈不推荐在生产项目中使用，因为它破坏了Maven的移植性。

    <dependency> <groupId>com.special</groupId> <artifactId>special-sdk</artifactId> <version>1.0</version> <scope>system</scope> <systemPath>${project.basedir}/lib/special-sdk-1.0.jar</systemPath> </dependency>

    问题：spring-boot-maven-plugin默认不会将system作用域的依赖打包进Fat Jar！你需要额外配置插件：

    <configuration> <includeSystemScope>true</includeSystemScope> </configuration>

    更好的做法：将这个jar包安装到本地Maven仓库（mvn install:install-file …）或部署到私有Nexus仓库，然后使用正常的compile作用域依赖。

  2. 本地项目模块依赖：在多模块Maven项目中，子模块被打包为jar。父模块依赖它们时，spring-boot-maven-plugin能够正确地将这些兄弟模块的jar包打包进Fat Jar。无需特殊配置，只要模块间的依赖关系在pom.xml中定义正确即可。

5. 进阶：自定义打包与持续集成流水线集成

对于企业级项目，打包往往不是简单的mvn package，而是CI/CD流水线中的一个关键环节。

5.1 定制化Fat Jar：分类依赖与加载优化

Spring Boot允许你对Fat Jar的内部结构进行更精细的控制。例如，你可以将依赖分组，或者指定某些依赖以ZIP格式存储（在某些场景下加载更快）。

<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <layers> <enabled>true</enabled> <!-- 自定义分层 --> <configuration>${project.basedir}/src/layers.xml</configuration> </layers> </configuration> </plugin>

在src/layers.xml中，你可以定义自己的分层逻辑，比如把不常变的、稳定的第三方库（如数据库驱动、连接池）放在一层，把经常变动的业务依赖放在另一层。

5.2 与CI/CD工具集成（以Jenkins为例）

在Jenkins Pipeline脚本中，打包步骤需要考虑到环境隔离和产物管理。

pipeline { agent any stages { stage(‘Checkout’) { steps { git ‘…’ } } stage(‘Build and Package’) { steps { // 1. 清理并打包，跳过单元测试（可能已在单独阶段执行） sh ‘mvn clean package -DskipTests’ // 2. 对生成的jar包进行重命名，加入构建号，便于追溯 sh ‘mv target/myapp-*.jar target/myapp-${BUILD_NUMBER}.jar’ // 3. 生成依赖树报告，存档用于问题排查 sh ‘mvn dependency:tree -DoutputFile=target/dependency-tree.txt’ } post { success { // 4. 归档制品（jar包和依赖树报告） archiveArtifacts artifacts: ‘target/*.jar, target/dependency-tree.txt’, fingerprint: true // 5. 可选：将jar包推送到制品库（如Nexus） // nexusPublisher nexusInstanceId: ‘nexus’, … } } } stage(‘Docker Build’) { steps { // 6. 使用Dockerfile构建镜像，镜像标签包含构建号 script { docker.build(“my-registry.com/myapp:${env.BUILD_NUMBER}”, “--build-arg JAR_FILE=target/myapp-${env.BUILD_NUMBER}.jar .”) } } } } }

关键点：

  • 环境隔离：确保Jenkins Agent上安装的Maven版本、JDK版本与生产环境要求一致。
  • 产物命名：在jar包名称中嵌入构建号（${BUILD_NUMBER}）或Git提交哈希，是后续部署和回滚的黄金标准。
  • 依赖树存档：将每次构建的依赖树保存下来。当未来某次构建出现依赖相关问题时，可以快速与这次成功的构建进行对比。

5.3 多环境配置与打包

通常，不同环境（开发、测试、生产）需要不同的配置文件（如数据库地址、日志级别）。Spring Boot支持application-{profile}.yml的命名约定。

打包策略：

  • 策略一：所有配置打进包，运行时指定profile。这是最常见的方式。将application.yml,application-dev.yml,application-prod.yml全部打包。通过启动命令java -jar app.jar --spring.profiles.active=prod来激活特定配置。
  • 策略二：打包通用配置，外部挂载环境特定配置。在Docker或Kubernetes部署中，更佳实践是只将不敏感的、通用的配置打进jar包，而将数据库密码、第三方密钥等通过环境变量或外部挂载的配置文件（如K8s ConfigMap）提供。这可以通过@ConfigurationProperties或直接使用${环境变量名}在application.yml中引用实现。

在打包时，可以使用Maven的resources插件过滤资源文件，将Maven属性（如@project.version@）动态写入配置文件。但更推荐使用上述的“外部化配置”方式，它更安全，也更符合十二要素应用的原则。

打包一个Spring Boot项目，远不止是执行一句命令。从理解Fat Jar的原理，到根据部署环境选择最合适的插件和策略，再到处理依赖冲突、资源路径等“暗坑”，每一步都需要清晰的认知和细致的操作。我个人最深刻的体会是：在项目初期就确立好打包和部署规范，能避免后期大量的运维麻烦。对于大多数微服务，直接使用spring-boot-maven-plugin打Fat Jar是最优解；如果走向容器化，务必启用分层构建以利用缓存；而对于复杂的、需要定制目录结构的传统部署，Assembly插件则提供了必要的灵活性。最后，别忘了将打包命令和产出物验证步骤，清晰地写入你的CI/CD流水线脚本中，让每一次构建都可靠、可重复。