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-loaderSpring Boot的加载器类。应用层applicationBOOT-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 groupIdorg.springframework.boot/groupId artifactIdspring-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。关键配置项解析指定主类虽然Spring Boot通常能通过SpringBootApplication注解自动找到主类但显式指定是个好习惯尤其是在多模块项目中。configuration mainClasscom.yourcompany.yourapp.Application/mainClass /configuration排除依赖有些依赖你可能不希望打进Fat Jar比如spring-boot-devtools开发工具或者tomcat-embed-jasper如果你使用Undertow。可以使用excludes。configuration excludes exclude groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId /exclude /excludes /configuration启用分层构建Layer要启用分层功能需要显式配置。configuration layers enabledtrue/enabled /layers /configuration打包后除了生成jar还会在target下生成一个layers.idx文件定义了分层信息。同时你可以使用java -Djarmodelayertools -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 groupIdorg.apache.maven.plugins/groupId artifactIdmaven-assembly-plugin/artifactId version3.6.0/version configuration !-- 指定描述符文件位置 -- descriptorsrc/assembly/package.xml/descriptor !-- 打包后生成的文件名后缀 -- appendAssemblyIdfalse/appendAssemblyId finalName${project.artifactId}-${project.version}-release/finalName /configuration executions execution phasepackage/phase goals goalsingle/goal /goals /execution /executions /plugin /plugins /build然后在src/assembly/package.xml文件中定义打包结构assembly xmlnshttp://maven.apache.org/ASSEMBLY/2.2.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd idpackage/id formats formattar.gz/format !-- 也可以同时生成zip: formatzip/format -- /formats includeBaseDirectoryfalse/includeBaseDirectory dependencySets dependencySet outputDirectory/lib/outputDirectory scoperuntime/scope !-- 将runtime和compile范围的依赖放入lib -- useProjectArtifactfalse/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 includestartup.sh/include includestartup.bat/include /includes fileMode0755/fileMode !-- 为shell脚本设置可执行权限 -- /fileSet /fileSets /assembly这样打包后你会得到一个tar.gz文件解压后目录结构清晰包含lib/,config/, 启动脚本和主jar包。3.3 使用 Maven Shade PluginShade插件的配置相对复杂主要用于解决依赖冲突。build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-shade-plugin/artifactId version3.5.0/version executions execution phasepackage/phase goals goalshade/goal /goals configuration createDependencyReducedPomfalse/createDependencyReducedPom filters !-- 可选过滤掉一些不需要的元文件减少包体积 -- filter artifact*:*/artifact excludes excludeMETA-INF/*.SF/exclude excludeMETA-INF/*.DSA/exclude excludeMETA-INF/*.RSA/exclude /excludes /filter /filters relocations !-- 关键配置重定位Guava类 -- relocation patterncom.google.common/pattern shadedPatterncom.yourproject.shaded.guava/shadedPattern /relocation !-- 可以重定位多个有冲突的依赖 -- /relocations transformers !-- 合并多个jar包中的META-INF/services/下的文件对使用Java SPI机制的服务很重要 -- transformer implementationorg.apache.maven.plugins.shade.resource.ServicesResourceTransformer/ !-- 确保主类清单文件正确 -- transformer implementationorg.apache.maven.plugins.shade.resource.ManifestResourceTransformer mainClasscom.yourcompany.yourapp.Application/mainClass /transformer /transformers /configuration /execution /executions /plugin /plugins /build配置完成后执行mvn clean packageShade插件会生成一个包含了重命名后依赖的Uber Jar。这里有一个巨大的坑重命名后你的项目代码中所有导入com.google.common包的地方也必须相应修改为com.yourproject.shaded.guava否则编译器会找不到类。这通常不是我们想要的。因此Shade插件更常用于构建一个给下游使用的SDK或库在这个库里解决掉自己的依赖冲突然后对外提供一个干净的API而不是用于构建一个可执行的Spring Boot应用。对于Spring Boot应用优先使用依赖排除exclusions或统一版本管理来解决冲突。4. 打包实战中的高频问题与深度排查即使配置正确在实际打包和运行过程中依然会遇到各种问题。下面我梳理了几个最常见的问题及其排查思路。4.1 依赖冲突NoSuchMethodError 与 ClassNotFoundException这是最令人头疼的问题之一。现象是本地开发正常打包后运行报错。排查链路确认打包方式首先检查打出的jar包是否真的包含了有问题的依赖。对于Fat Jar可以用jar tf target/your-app.jar | grep -i ‘问题类所在包名’命令在终端查看。或者直接解压jar包查看BOOT-INF/lib目录下是否存在预期的jar文件。分析依赖树使用Maven命令mvn dependency:tree -Dverbose生成详细的依赖树。-Dverbose参数会显示冲突和被忽略的依赖。在输出中搜索有问题的类所在的依赖groupId:artifactId看它被哪些路径引入以及最终生效的是哪个版本。如果发现有两个版本Maven默认会选择“依赖路径最近”的版本。你需要判断这个默认选择的版本是否兼容你的代码。定位冲突根源版本不兼容如果生效的版本过低或过高可能缺少某些方法或类。解决方案是在pom.xml中显式声明你需要的正确版本Maven会优先使用直接声明的版本。重复依赖的不同版本如果两个不同的第三方库A和B分别依赖了C库的v1和v2而v1和v2不兼容。这时需要做“依赖排除”。dependency groupIdcom.library.A/groupId artifactIdA/artifactId version1.0/version exclusions exclusion groupIdcom.conflict.library/groupId artifactIdC/artifactId /exclusion /exclusions /dependency排除掉A库中的C让项目统一使用B库引入的C版本或者反过来。使用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的。正确做法使用Spring的ResourceLoader或Value(“classpath:…”)这是最Spring的方式。Autowired private ResourceLoader resourceLoader; Resource resource resourceLoader.getResource(“classpath:template/email.html”);使用ClassPathResourceResource resource new ClassPathResource(“template/email.html”, this.getClass().getClassLoader());读取文件内容得到Resource对象后通过resource.getInputStream()来读取内容而不是试图获取File对象。检查清单确保资源文件位于src/main/resources目录或其子目录下。打包后它们会出现在jar包的根路径或BOOT-INF/classes下。4.3 打包速度慢与镜像构建优化项目依赖越来越多后每次打包都要复制上百个依赖jarmvn clean package会变得很慢。优化策略利用Docker分层缓存Spring Boot 2.3如前所述使用分层jar。在Dockerfile中FROM openjdk:11-jre-slim as builder WORKDIR application ARG JAR_FILEtarget/*.jar COPY ${JAR_FILE} application.jar RUN java -Djarmodelayertools -jar application.jar extract FROM openjdk:11-jre-slim WORKDIR application COPY --frombuilder application/dependencies/ ./ COPY --frombuilder application/spring-boot-loader/ ./ COPY --frombuilder application/snapshot-dependencies/ ./ COPY --frombuilder application/application/ ./ ENTRYPOINT [“java”, “org.springframework.boot.loader.JarLauncher”]这样只要pom.xml中依赖不变dependencies层就会被缓存大幅加速构建。使用Maven离线模式与本地仓库在CI/CD流水线中可以维护一个稳定的本地Maven仓库镜像。使用mvn -o packageoffline模式可以禁止从远程仓库下载强制使用本地缓存前提是所需依赖已全部在本地。区分打包环境在pom.xml中通过profiles定义不同环境的配置。例如开发环境可以跳过测试并排除一些不必要的插件执行。profile iddev/id properties skipTeststrue/skipTests /properties build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration skiptrue/skip !-- 开发时可能不需要每次都打可执行jar -- /configuration /plugin /plugins /build /profile使用mvn clean package -Pdev来加速开发阶段的打包。4.4 特殊依赖处理系统作用域与本地jar包有些时候你会遇到一些“非标准”的依赖。系统作用域依赖system scope这种依赖不从Maven仓库获取而是指向本地文件系统的一个绝对路径。强烈不推荐在生产项目中使用因为它破坏了Maven的移植性。dependency groupIdcom.special/groupId artifactIdspecial-sdk/artifactId version1.0/version scopesystem/scope systemPath${project.basedir}/lib/special-sdk-1.0.jar/systemPath /dependency问题spring-boot-maven-plugin默认不会将system作用域的依赖打包进Fat Jar你需要额外配置插件configuration includeSystemScopetrue/includeSystemScope /configuration更好的做法将这个jar包安装到本地Maven仓库mvn install:install-file …或部署到私有Nexus仓库然后使用正常的compile作用域依赖。本地项目模块依赖在多模块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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration layers enabledtrue/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 -DoutputFiletarget/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_FILEtarget/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.activeprod来激活特定配置。策略二打包通用配置外部挂载环境特定配置。在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流水线脚本中让每一次构建都可靠、可重复。