在Java后端开发的日常里SpringBoot和Maven这对组合基本是标配中的标配。但很多人对spring-boot-maven-plugin的认知停留在“打包时用一下”的层面甚至有人复制了配置却不知道每个参数在干什么踩了坑也不知道原因。这篇东西我把这个插件从基础配置到进阶玩法完整拆开讲一遍重点放在“为什么这么配”和“怎么配才能提升构建效率”上全是实际项目里能直接用的东西。1. 内容整体设计与思路拆解1.1 这个插件到底解决了什么问题先明确一个核心认知spring-boot-maven-plugin本质上是Maven生命周期的一个扩展它在package阶段介入把普通jar包重新加工成可执行的SpringBoot应用包。没有它你用mvn package打出来的jar就是个普通jar——依赖没有被合并进去java -jar跑不起来因为你缺了所有的第三方库。这个插件做的核心事情有三件repackage重打包、运行SpringBoot应用、build-info生成构建信息。其中repackage是绝对的主角。它的工作方式很有意思假设你自己写了一个可执行的jar里面包含了所有依赖和SpringBoot的loader代码然后插件把原始的jar重命名为xxx.jar.original再把加工后的可执行jar写为xxx.jar。这个过程不是简单的复制文件而是会把类重定位到BOOT-INF/classes、依赖放到BOOT-INF/lib入口类放到BOOT-INF/classesSpringBoot的launcher负责真正启动。理解这个机制很重要。很多人好奇为什么SpringBoot项目打出来的jar是“自带依赖”的其实就是因为repackage做了嵌套jar的合并和loader的注入。这种结构的优势是部署极简一个jar就能分发运行代价是构建和上传的时候jar包体积比较大而且如果你直接在mvn package执行完之后立刻用原始的xxx.jar.original会发现它其实不能独立运行——那只是个中间产物。1.2 为什么需要单独配置而不是默认开箱即用SpringBoot官方parent POM里已经声明了插件所以从SpringBoot 2.x开始你只要继承spring-boot-starter-parent执行package就能得到可执行jar。这看起来“开箱即用”但默认配置只覆盖了最基础的场景。实际工程项目里你会有多环境profile、外部依赖排除、自定义主类、构建信息注入、容器镜像配合等需求这些都没法用“零配置”处理必须显式声明插件并调整参数。从我经手的项目来看凡是上线遇到问题的项目十有八九都是因为配置文件里使用了默认继承而没有显式配置导致信息不透明。比如jar包运行之后发现配置没生效排查半天发现是profile没激活比如公司私服上传时把.original文件也传上去了比如logger冲突导致双下划线报错。这些问题的本质都是对插件配置项不熟悉造成的。2. 核心细节解析与实操要点2.1 插件坐标与基础配置项全解先看一份最常用的完整配置我把它按“必配项”和“选配项”拆开解释。build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId !-- 版本一般由SpringBoot父POM管理不必显式写 -- configuration !-- 指定主类一般可省略但在多模块或特殊启动类场景必须显式 -- mainClasscom.example.demo.DemoApplication/mainClass !-- 打包后排除这些依赖常见于排除冲突的日志实现 -- excludeGroupIdsorg.apache.tomcat,commons-logging/excludeGroupIds !-- 将原始jar保留为xxx.jar.original默认true -- classifierexec/classifier !-- 分模块构建时只对当前模块生效 -- includes include groupIdnothing/groupId artifactIdnothing/artifactId /include /includes !-- 关联外部jar进BOOT-INF/lib -- includeSystemScopetrue/includeSystemScope /configuration !-- 绑定到package生命周期的repackage目标 -- executions execution goals goalrepackage/goal /goals /execution /executions /plugin /plugins /build逐个说明参数的作用这些是我在实际项目里验证过的mainClass指定启动类。单模块项目不写也能自己找多模块或启动类不在默认扫描路径下时必须写否则repackage阶段会报“Unable to find main class”。classifier分类器。加上之后原始jar会保留为xxx-exec.jar同时可执行jar生成为xxx.jar。这个场景最常见的是依赖方只需要普通jar时通过classifier获取非可执行版本。excludeGroupIds排除指定groupId的依赖。典型场景是日志框架冲突比如项目自带logback又排除了commons-logging防止SpringBoot Starter默认带入旧日志。includeSystemScope是否把system scope的依赖打入jar包。用了本地jar依赖systemPath方式时如果这里不设true打包后运行会报ClassNotFound。excludes排除某个具体依赖写入可执行jar注意它需要搭配groupId和artifactId成对使用。实操里最常见的一个迷惑点是为什么我用外部依赖时打包后java -jar还报ClassNotFound十有八九就是includeSystemScope没配置。你maven本地能编译能跑是因为编译期classpath里带着system依赖但repackage时不会默认打包这类依赖。2.2 绑定执行时机为什么必须在package阶段绑定repackageMaven插件目标是绑定在生命周期上的spring-boot:repackage不会自动执行你必须人为绑定。如果只写goalrepackage/goal而没有execution配置那你每次打包要手动执行mvn spring-boot:repackage这不符合构建习惯。正确做法是在executions里绑定到package阶段executions execution idrepackage/id phasepackage/phase goals goalrepackage/goal /goals /execution /executions这里有三个细节值得注意。第一如果不指定phase插件默认会绑定到package阶段但显式声明能让构建流程的可读性更强后面排查CI配置时候少走弯路。第二一个execution可以绑定多个goal实际项目里常见的组合是repackage加build-info后者会生成META-INF/build-info.properties配合InfoContributor把git版本、构建时间暴露到健康检查或监控接口。第三exec分类器场景下如果配置了classifierexec/classifier那么repackage生成的是xxx-exec.jar原始jar还是xxx.jar。这个配置在你要给别人提供普通jar包同时自己又要可执行jar时必须掌握。2.3 运行期目标spring-boot:run的正确打开方式另一个高频目标是run。Maven插件可以直接启动SpringBoot应用配置长这样configuration mainClasscom.example.demo.DemoApplication/mainClass arguments argument--spring.profiles.activedev/argument /arguments jvmArguments jvmArgument-Xms256m/jvmArgument jvmArgument-Xmx1024m/jvmArgument /jvmArguments !-- 是否使用devtools热部署默认false -- useTestClasspathfalse/useTestClasspath /configuration调试阶段用mvn spring-boot:run配合IDE断点也行但我觉得没有直接从IDE里跑方便。这个目标的真正价值在于CI验证比如在流水线里跑一下mvn spring-boot:run确认应用能正常起、端口能通再触发后续的自动化测试。jvmArguments里设置堆参数是最容易忽略的地方因为如果你直接用mvn spring-boot:run跑一个内存需求大的应用默认堆可能只有物理内存的1/4启动后频繁GC界面假死你还要怀疑是不是代码有问题其实只是内存参数没传。提示spring-boot:run默认使用test classpath当你用IDE跑单测时能识别到类但单独命令行执行时某些测试依赖会干扰启动所以建议显式配置useTestClasspathfalse/useTestClasspath。3. 实操过程与核心环节实现3.1 经典单模块项目的完整pom配置我用了一个比较典型的服务端项目把完整pom核心片段贴上这个配置可以直接改改坐标就能用?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIddemo-service/artifactId version1.0.0-SNAPSHOT/version properties java.version1.8/java.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies build finalNamedemo-service/finalName plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration mainClasscom.example.demo.DemoApplication/mainClass !-- 日志冲突时排除旧日志实现 -- excludeGroupIdscommons-logging/excludeGroupIds /configuration executions execution goals goalrepackage/goal goalbuild-info/goal /goals /execution /executions /plugin /plugins /build /project这个配置有几个决策点我要说一下。第一没有显式写插件版本是因为SpringBoot 2.7.18的父POM已经管理了插件版本你写了反而可能和生产环境的版本不一致造成奇怪行为。第二finalName设成服务名让产出物稳定为demo-service.jar而不是自动带上版本号。这在CI脚本里写死了文件名的情况下非常舒服不然每次升级版本号都要同步改脚本。第三build-info目标配合spring-boot-starter-actuator能把build.version、build.time等信息通过/actuator/info暴露出来上线后确认版本非常方便。构建并验证# 跳过测试加速打包 mvn clean package -DskipTests # 查看jar内结构 jar tf target/demo-service.jar | head -30 # 启动验证 java -jar target/demo-service.jar --spring.profiles.activedev运行日志里会出现“Started DemoApplication in X seconds”字样到这一步就算完整走通。3.2 多环境配置的接入方式SpringBoot多环境最常用的是application-{profile}.ymlspring.profiles.active。但这种配置方式依赖外部传入参数如果没有参数就会用默认的很容易出现“本地明明是dev环境打包之后跑到prod配置”的惨案。我在项目里强烈建议把默认的active写在配置里而不是完全依赖外部传入spring: profiles: active: dev然后在pom里结合profile做环境差异化构建profiles profile iddev/id activation activeByDefaulttrue/activeByDefault /activation properties profiles.activedev/profiles.active /properties /profile profile idprod/id properties profiles.activeprod/profiles.active /properties /profile /profiles构建时用mvn clean package -Pprod -DskipTests配合resource插件的过滤能力可以把application.yml中的profiles.active占位符替换成对应的值。注意SpringBoot 2.x的spring-boot-starter-parent已经默认开启了resource filtering所以这里不需要额外配置直接用profiles.active占位符就行。这个组合的好处是构建期就锁死环境配置避免同个jar在不同环境启动时误配。当然如果你坚持一个包跑所有环境那就在启动脚本里显式传入--spring.profiles.activeprod。3.3 依赖瘦身如何把jar体积降下来SpringBoot的可执行jar越来越臃肿是个老问题。一个包含全套web、数据库、消息队列依赖的服务打完包五六百MB很正常。部署时传输慢、容器镜像构建慢、冷启动时扫描类多。我的做法是分层处理把真正的业务代码、框架依赖、外部资源和本地依赖分开。先说一个省事的方案使用spring-boot-maven-plugin自带的layertools。从SpringBoot 2.3开始官方支持分层打包配置configuration layers enabledtrue/enabled /layers /configuration构建后可以用java -Djarmodelayertools -jar app.jar来查看和提取分层。这个能力配合Docker多阶段构建极其好用依赖层不变时Docker构建缓存命中镜像构建速度可以快一个数量级。说句实在话如果你的服务已经上容器这个配置必须要打开收益非常直接——平时改业务代码提交后镜像构建要几分钟开了分层后可能只要十几秒因为公共依赖层直接命中缓存。本地依赖的处理如果pom里依赖了system scope的外部jar默认不会打进可执行jar。比如对接某老系统时只给了一份xxx-sdk.jar本地安装私服又没有只能在pom里写systemPath。这时候要设置includeSystemScopetrue/includeSystemScope但这会让非可执行jar依赖方也引入这个jar容易出问题。更稳妥的做法是手动安装到本地仓库或上传到私服然后按普通依赖处理尽量避免在项目里长期保留systemPath依赖。3.4 加速构建的几种有效手段构建效率是个系统工程插件层面的优化只是一个环节。总结一下我实测有用的几个手段。第一个是跳过测试。研发本地构建时执行mvn clean package -DskipTests但如果测试代码有编译错误-DskipTests还是会编译测试代码的。想要完全不碰测试代码用-Dmaven.test.skiptrue这个参数特别好使但注意它同样跳过测试代码编译如果测试代码有语法错误也不会暴露。建议CI里严格保留单测执行本地开发用-DskipTests发布验证再放开测试。第二个是并行构建。多模块项目可以启用-T 1C让Maven按CPU核心数并行构建多个模块这个参数对单模块项目没有收益但微服务多模块仓库效果显著。实测从4个模块的构建时间从1分半压缩到40秒左右。需要注意并行构建时的依赖顺序Maven会自动按模块依赖关系调度但偶尔有插件不兼容并行构建遇到无法解释的奇怪失败可以先关掉并行试试。第三个是镜像加速。这个属于Maven本身的基础配置但也直接影响构建效率。在~/.m2/settings.xml里配置阿里云镜像是最常见的提速方式mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors但mirror的mirrorOf范围不要写成*只镜像central和公共仓库就够了。如果写成*会把你私服仓库的请求也拦截并转发到阿里云轻则私服依赖拉不下来重则权限认证直接报错。这个问题我在实际项目里踩过团队里有人图省事写*结果公司私服上的包全部404排查半天才发现是镜像把私服地址劫持了。第四个是启用增量构建。Maven本身没有跨模块的增量构建但SpringBoot插件配合spring-boot-maven-plugin的repackage在你只改一个模块时尽量利用-pl和-am参数指定模块列表避免全量构建mvn install -pl user-service -am -DskipTests多个模块的仓库改成这种精准构建后开发时的构建时间能下降一半以上。4. 常见问题与排查技巧实录4.1 打包后无法启动No main class这个报错在repackage阶段就炸原因很简单找不到启动类。排查顺序从这几个方向入手检查启动类位置。SpringBoot默认扫描启动类所在包以及子包启动类如果在某个子包下面没问题但如果启动类不在src/main/java下或者被其他包隔离就找不到。检查mainClass配置。多模块项目里父模块执行package时如果没有显式指定mainClass可能顺带把没有主类的模块也repackage一遍。检查maven打包顺序。多模块项目install时依赖模块先构建但可执行jar的repackage是在当前模块确认当前模块确实是spring-boot应用模块。遇到这种问题直接执行javap -cp target/classes com.example.DemoApplication看类是否存在或者用jar tf看jar结构。在CI日志里搜“Unable to find main class”定位更快。4.2 打包产出物不对xxx.jar.original是什么能不能删遇到这种问题不要慌说明repackage执行成功了。.jar.original是原始jar。群里经常看到有人问它是什么、能不能删能删但下次package时还会生成。如果你实在不想看到它配置classifierexec/classifier就能让原始jar保留为正常名可执行jar带exec后缀。我在无私奉献给其他团队普通jar时用这种模式。4.3 依赖冲突多个版本jar打入包典型表现是启动时报NoSuchMethodError或NoClassDefFoundError比如引入了commons-logging又用了logback或者旧版servlet-api混进依赖树。排查技巧是mvn dependency:tree -Dverbose这会输出完整依赖树找到冲突坐标后在pom里剔除不需要的一方。如果冲突发生在SpringBoot父子依赖和业务依赖之间最稳妥的是在dependencyManagement中统一版本。日志冲突的排除模板我反复用过多次dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-logging/artifactId /exclusion /exclusions /dependency4.4 本地跑通、线上起不来的灵异问题这类问题最常见的原因是profile和环境配置。本地IDE默认加载application-dev.yml线上没传环境参数实际加载了application.yml默认配置可能数据源指向了错误的库或连不上。排查思路是应用启动后先看“The following profiles are active”确认激活的是哪个环境再看日志里有没有数据库连接报错。这类问题有一个很有效的排查手段直接把命令行里额外加上--debug把自动配置的匹配报告打出来哪些条件生效、哪些条件不匹配一目了然。还有一类灵异现象是java -jar跑正常但在sytemd里起不来。大概率是工作目录不对或者是shell里用了相对路径。写systemd单元文件时建议用绝对路径并显式指定WorkingDirectory。4.5 插件版本与SpringBoot版本不匹配用spring-boot-starter-parent时插件版本自动对齐一般没问题。但如果你的项目没有parent而是用dependencyManagement引入SpringBoot BOM就需要手动声明插件版本。用官方BOM的import模式时插件版本不会自动管理这也是新手最容易踩的坑。遇到这种场景用一个跟SpringBoot版本匹配的插件版本即可一般SpringBoot 2.5对应2.5.x2.7对应2.7.x3.x同理。提示SpringBoot 3.x之后用JDK17并替换了jakarta命名空间直接沿用老项目的插件配置往往也能跑但如果同时自定义了较多插件参数建议先用最简单的配置跑通再逐步加参数减少组合问题。5. 进阶场景容器镜像、前端资源与插件组合5.1 Docker镜像构建的最佳拍档SpringBoot的应用镜像重点是充分利用构建缓存。这里以layertools为例。# 先解包分层 java -Djarmodelayertools -jar app.jar extract # 得到分层目录后Dockerfile可以这样写 FROM openjdk:8-jre-alpine AS builder WORKDIR /app COPY --frombuild /app/dependencies/ ./ COPY --frombuild /app/spring-boot-loader/ ./ COPY --frombuild /app/snapshot-dependencies/ ./ COPY --frombuild /app/application/ ./ RUN java -Djarmodelayertools -jar app.jar extract FROM openjdk:8-jre-alpine WORKDIR /app COPY --frombuilder /app/dependencies/ ./ COPY --frombuilder /app/spring-boot-loader/ ./ COPY --frombuilder /app/snapshot-dependencies/ ./ COPY --frombuilder /app/application/ ./ ENTRYPOINT [java, -jar, app.jar]实际项目里我会把依赖分层和业务代码分层两个COPY动作分开。依赖层几乎很少变docker build时该层命中缓存只有业务代码层会重新打包上传。上了这个方案之后服务镜像从每次构建2分钟降到了十几秒区别非常明显。5.2 Vue前端打包进SpringBoot jar有些小团队没有独立部署前端选择把Vue构建产物放进SpringBoot的static目录统一发布。做法是前端构建npm run build产物在dist目录。将dist内容复制进SpringBoot项目的src/main/resources/static。正常mvn package即可前端资源会打进jar。这个过程可以用maven-resources-plugin的copy-resources目标自动化避免每次手动复制plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-frontend-dist/id phasegenerate-resources/phase goals goalcopy-resources/goal /goals configuration outputDirectory${basedir}/src/main/resources/static/outputDirectory resources resource directory${basedir}/../frontend/dist/directory /resource /resources /configuration /execution /executions /plugin这里有一个要注意的点如果前端dist里的文件名带hash多几次构建后static目录会越积越大。最好在copy前先clean掉static目录或者用maven-clean-plugin里的clean目标把static先抹掉不然旧资源全打进jar体积臃肿。5.3 与compiler插件、assembly插件的组合策略SpringBoot插件和maven-compiler-plugin的关系很直接编译的字节码版本直接决定运行环境。JDK8项目升到JDK11时如果编译参数没改还停留在1.8某些新语法特性就无法使用。推荐在pom.properties里显式设置源码与目标版本properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target /propertiesmaven-assembly-plugin是另一个被经常问到的打包插件。如果你是纯SpringBoot应用不需要assembly把依赖打到一个jar里——repackage已经做了。assembly一般用于把脚本、配置、jar包组织成一套发布目录结构。注意两者不要同时把依赖重复打进去容易造成META-INF/services冲突导致某些SPI实现无法加载。我自己遇到过一次某加密组件在纯SpringBoot打包时能跑加了个assembly分发目录之后整个服务起不来排查半天是META-INF/services里多个jar的SPI文件合并出错。6. 未来扩展与个人经验总结如果你正在维护一个多模块仓库、频繁发版、或准备容器化改造spring-boot-maven-plugin是你构建链路里最值得优化的一个核心节点。它不算复杂但每一项配置都直接影响产出物的可用性mainClass错了无法启动classifier错了依赖方拿错产物layers没开启容器构建慢到怀疑人生。从我个人的实践体会来说配置这个插件不需要追求一步到位。我习惯用“最小可运行”起步先按默认配置打出可执行jar本地java -jar跑通再逐步加build-info、加layers、加profile过滤每个config改动后都重新打包启动验证一遍。这样出了问题很容易判断是哪一步引入的。反过来如果你一次性把网上搜来的完整配置塞进去一旦启动失败很难定位是插件问题还是环境问题。最后分享一个小技巧把mvn clean package -DskipTests绑成一个shell脚本别名再配合-pl指定模块基本能把本地构建成本压到最低。这套组合我已经用了很久实测下来无论是“改完代码立刻要验证”还是“发版前完整构建”都比裸的mvn package顺滑得多。
Spring Boot Maven插件深度解析：从打包原理到构建提速
在Java后端开发的日常里SpringBoot和Maven这对组合基本是标配中的标配。但很多人对spring-boot-maven-plugin的认知停留在“打包时用一下”的层面甚至有人复制了配置却不知道每个参数在干什么踩了坑也不知道原因。这篇东西我把这个插件从基础配置到进阶玩法完整拆开讲一遍重点放在“为什么这么配”和“怎么配才能提升构建效率”上全是实际项目里能直接用的东西。1. 内容整体设计与思路拆解1.1 这个插件到底解决了什么问题先明确一个核心认知spring-boot-maven-plugin本质上是Maven生命周期的一个扩展它在package阶段介入把普通jar包重新加工成可执行的SpringBoot应用包。没有它你用mvn package打出来的jar就是个普通jar——依赖没有被合并进去java -jar跑不起来因为你缺了所有的第三方库。这个插件做的核心事情有三件repackage重打包、运行SpringBoot应用、build-info生成构建信息。其中repackage是绝对的主角。它的工作方式很有意思假设你自己写了一个可执行的jar里面包含了所有依赖和SpringBoot的loader代码然后插件把原始的jar重命名为xxx.jar.original再把加工后的可执行jar写为xxx.jar。这个过程不是简单的复制文件而是会把类重定位到BOOT-INF/classes、依赖放到BOOT-INF/lib入口类放到BOOT-INF/classesSpringBoot的launcher负责真正启动。理解这个机制很重要。很多人好奇为什么SpringBoot项目打出来的jar是“自带依赖”的其实就是因为repackage做了嵌套jar的合并和loader的注入。这种结构的优势是部署极简一个jar就能分发运行代价是构建和上传的时候jar包体积比较大而且如果你直接在mvn package执行完之后立刻用原始的xxx.jar.original会发现它其实不能独立运行——那只是个中间产物。1.2 为什么需要单独配置而不是默认开箱即用SpringBoot官方parent POM里已经声明了插件所以从SpringBoot 2.x开始你只要继承spring-boot-starter-parent执行package就能得到可执行jar。这看起来“开箱即用”但默认配置只覆盖了最基础的场景。实际工程项目里你会有多环境profile、外部依赖排除、自定义主类、构建信息注入、容器镜像配合等需求这些都没法用“零配置”处理必须显式声明插件并调整参数。从我经手的项目来看凡是上线遇到问题的项目十有八九都是因为配置文件里使用了默认继承而没有显式配置导致信息不透明。比如jar包运行之后发现配置没生效排查半天发现是profile没激活比如公司私服上传时把.original文件也传上去了比如logger冲突导致双下划线报错。这些问题的本质都是对插件配置项不熟悉造成的。2. 核心细节解析与实操要点2.1 插件坐标与基础配置项全解先看一份最常用的完整配置我把它按“必配项”和“选配项”拆开解释。build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId !-- 版本一般由SpringBoot父POM管理不必显式写 -- configuration !-- 指定主类一般可省略但在多模块或特殊启动类场景必须显式 -- mainClasscom.example.demo.DemoApplication/mainClass !-- 打包后排除这些依赖常见于排除冲突的日志实现 -- excludeGroupIdsorg.apache.tomcat,commons-logging/excludeGroupIds !-- 将原始jar保留为xxx.jar.original默认true -- classifierexec/classifier !-- 分模块构建时只对当前模块生效 -- includes include groupIdnothing/groupId artifactIdnothing/artifactId /include /includes !-- 关联外部jar进BOOT-INF/lib -- includeSystemScopetrue/includeSystemScope /configuration !-- 绑定到package生命周期的repackage目标 -- executions execution goals goalrepackage/goal /goals /execution /executions /plugin /plugins /build逐个说明参数的作用这些是我在实际项目里验证过的mainClass指定启动类。单模块项目不写也能自己找多模块或启动类不在默认扫描路径下时必须写否则repackage阶段会报“Unable to find main class”。classifier分类器。加上之后原始jar会保留为xxx-exec.jar同时可执行jar生成为xxx.jar。这个场景最常见的是依赖方只需要普通jar时通过classifier获取非可执行版本。excludeGroupIds排除指定groupId的依赖。典型场景是日志框架冲突比如项目自带logback又排除了commons-logging防止SpringBoot Starter默认带入旧日志。includeSystemScope是否把system scope的依赖打入jar包。用了本地jar依赖systemPath方式时如果这里不设true打包后运行会报ClassNotFound。excludes排除某个具体依赖写入可执行jar注意它需要搭配groupId和artifactId成对使用。实操里最常见的一个迷惑点是为什么我用外部依赖时打包后java -jar还报ClassNotFound十有八九就是includeSystemScope没配置。你maven本地能编译能跑是因为编译期classpath里带着system依赖但repackage时不会默认打包这类依赖。2.2 绑定执行时机为什么必须在package阶段绑定repackageMaven插件目标是绑定在生命周期上的spring-boot:repackage不会自动执行你必须人为绑定。如果只写goalrepackage/goal而没有execution配置那你每次打包要手动执行mvn spring-boot:repackage这不符合构建习惯。正确做法是在executions里绑定到package阶段executions execution idrepackage/id phasepackage/phase goals goalrepackage/goal /goals /execution /executions这里有三个细节值得注意。第一如果不指定phase插件默认会绑定到package阶段但显式声明能让构建流程的可读性更强后面排查CI配置时候少走弯路。第二一个execution可以绑定多个goal实际项目里常见的组合是repackage加build-info后者会生成META-INF/build-info.properties配合InfoContributor把git版本、构建时间暴露到健康检查或监控接口。第三exec分类器场景下如果配置了classifierexec/classifier那么repackage生成的是xxx-exec.jar原始jar还是xxx.jar。这个配置在你要给别人提供普通jar包同时自己又要可执行jar时必须掌握。2.3 运行期目标spring-boot:run的正确打开方式另一个高频目标是run。Maven插件可以直接启动SpringBoot应用配置长这样configuration mainClasscom.example.demo.DemoApplication/mainClass arguments argument--spring.profiles.activedev/argument /arguments jvmArguments jvmArgument-Xms256m/jvmArgument jvmArgument-Xmx1024m/jvmArgument /jvmArguments !-- 是否使用devtools热部署默认false -- useTestClasspathfalse/useTestClasspath /configuration调试阶段用mvn spring-boot:run配合IDE断点也行但我觉得没有直接从IDE里跑方便。这个目标的真正价值在于CI验证比如在流水线里跑一下mvn spring-boot:run确认应用能正常起、端口能通再触发后续的自动化测试。jvmArguments里设置堆参数是最容易忽略的地方因为如果你直接用mvn spring-boot:run跑一个内存需求大的应用默认堆可能只有物理内存的1/4启动后频繁GC界面假死你还要怀疑是不是代码有问题其实只是内存参数没传。提示spring-boot:run默认使用test classpath当你用IDE跑单测时能识别到类但单独命令行执行时某些测试依赖会干扰启动所以建议显式配置useTestClasspathfalse/useTestClasspath。3. 实操过程与核心环节实现3.1 经典单模块项目的完整pom配置我用了一个比较典型的服务端项目把完整pom核心片段贴上这个配置可以直接改改坐标就能用?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIddemo-service/artifactId version1.0.0-SNAPSHOT/version properties java.version1.8/java.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies build finalNamedemo-service/finalName plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration mainClasscom.example.demo.DemoApplication/mainClass !-- 日志冲突时排除旧日志实现 -- excludeGroupIdscommons-logging/excludeGroupIds /configuration executions execution goals goalrepackage/goal goalbuild-info/goal /goals /execution /executions /plugin /plugins /build /project这个配置有几个决策点我要说一下。第一没有显式写插件版本是因为SpringBoot 2.7.18的父POM已经管理了插件版本你写了反而可能和生产环境的版本不一致造成奇怪行为。第二finalName设成服务名让产出物稳定为demo-service.jar而不是自动带上版本号。这在CI脚本里写死了文件名的情况下非常舒服不然每次升级版本号都要同步改脚本。第三build-info目标配合spring-boot-starter-actuator能把build.version、build.time等信息通过/actuator/info暴露出来上线后确认版本非常方便。构建并验证# 跳过测试加速打包 mvn clean package -DskipTests # 查看jar内结构 jar tf target/demo-service.jar | head -30 # 启动验证 java -jar target/demo-service.jar --spring.profiles.activedev运行日志里会出现“Started DemoApplication in X seconds”字样到这一步就算完整走通。3.2 多环境配置的接入方式SpringBoot多环境最常用的是application-{profile}.ymlspring.profiles.active。但这种配置方式依赖外部传入参数如果没有参数就会用默认的很容易出现“本地明明是dev环境打包之后跑到prod配置”的惨案。我在项目里强烈建议把默认的active写在配置里而不是完全依赖外部传入spring: profiles: active: dev然后在pom里结合profile做环境差异化构建profiles profile iddev/id activation activeByDefaulttrue/activeByDefault /activation properties profiles.activedev/profiles.active /properties /profile profile idprod/id properties profiles.activeprod/profiles.active /properties /profile /profiles构建时用mvn clean package -Pprod -DskipTests配合resource插件的过滤能力可以把application.yml中的profiles.active占位符替换成对应的值。注意SpringBoot 2.x的spring-boot-starter-parent已经默认开启了resource filtering所以这里不需要额外配置直接用profiles.active占位符就行。这个组合的好处是构建期就锁死环境配置避免同个jar在不同环境启动时误配。当然如果你坚持一个包跑所有环境那就在启动脚本里显式传入--spring.profiles.activeprod。3.3 依赖瘦身如何把jar体积降下来SpringBoot的可执行jar越来越臃肿是个老问题。一个包含全套web、数据库、消息队列依赖的服务打完包五六百MB很正常。部署时传输慢、容器镜像构建慢、冷启动时扫描类多。我的做法是分层处理把真正的业务代码、框架依赖、外部资源和本地依赖分开。先说一个省事的方案使用spring-boot-maven-plugin自带的layertools。从SpringBoot 2.3开始官方支持分层打包配置configuration layers enabledtrue/enabled /layers /configuration构建后可以用java -Djarmodelayertools -jar app.jar来查看和提取分层。这个能力配合Docker多阶段构建极其好用依赖层不变时Docker构建缓存命中镜像构建速度可以快一个数量级。说句实在话如果你的服务已经上容器这个配置必须要打开收益非常直接——平时改业务代码提交后镜像构建要几分钟开了分层后可能只要十几秒因为公共依赖层直接命中缓存。本地依赖的处理如果pom里依赖了system scope的外部jar默认不会打进可执行jar。比如对接某老系统时只给了一份xxx-sdk.jar本地安装私服又没有只能在pom里写systemPath。这时候要设置includeSystemScopetrue/includeSystemScope但这会让非可执行jar依赖方也引入这个jar容易出问题。更稳妥的做法是手动安装到本地仓库或上传到私服然后按普通依赖处理尽量避免在项目里长期保留systemPath依赖。3.4 加速构建的几种有效手段构建效率是个系统工程插件层面的优化只是一个环节。总结一下我实测有用的几个手段。第一个是跳过测试。研发本地构建时执行mvn clean package -DskipTests但如果测试代码有编译错误-DskipTests还是会编译测试代码的。想要完全不碰测试代码用-Dmaven.test.skiptrue这个参数特别好使但注意它同样跳过测试代码编译如果测试代码有语法错误也不会暴露。建议CI里严格保留单测执行本地开发用-DskipTests发布验证再放开测试。第二个是并行构建。多模块项目可以启用-T 1C让Maven按CPU核心数并行构建多个模块这个参数对单模块项目没有收益但微服务多模块仓库效果显著。实测从4个模块的构建时间从1分半压缩到40秒左右。需要注意并行构建时的依赖顺序Maven会自动按模块依赖关系调度但偶尔有插件不兼容并行构建遇到无法解释的奇怪失败可以先关掉并行试试。第三个是镜像加速。这个属于Maven本身的基础配置但也直接影响构建效率。在~/.m2/settings.xml里配置阿里云镜像是最常见的提速方式mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors但mirror的mirrorOf范围不要写成*只镜像central和公共仓库就够了。如果写成*会把你私服仓库的请求也拦截并转发到阿里云轻则私服依赖拉不下来重则权限认证直接报错。这个问题我在实际项目里踩过团队里有人图省事写*结果公司私服上的包全部404排查半天才发现是镜像把私服地址劫持了。第四个是启用增量构建。Maven本身没有跨模块的增量构建但SpringBoot插件配合spring-boot-maven-plugin的repackage在你只改一个模块时尽量利用-pl和-am参数指定模块列表避免全量构建mvn install -pl user-service -am -DskipTests多个模块的仓库改成这种精准构建后开发时的构建时间能下降一半以上。4. 常见问题与排查技巧实录4.1 打包后无法启动No main class这个报错在repackage阶段就炸原因很简单找不到启动类。排查顺序从这几个方向入手检查启动类位置。SpringBoot默认扫描启动类所在包以及子包启动类如果在某个子包下面没问题但如果启动类不在src/main/java下或者被其他包隔离就找不到。检查mainClass配置。多模块项目里父模块执行package时如果没有显式指定mainClass可能顺带把没有主类的模块也repackage一遍。检查maven打包顺序。多模块项目install时依赖模块先构建但可执行jar的repackage是在当前模块确认当前模块确实是spring-boot应用模块。遇到这种问题直接执行javap -cp target/classes com.example.DemoApplication看类是否存在或者用jar tf看jar结构。在CI日志里搜“Unable to find main class”定位更快。4.2 打包产出物不对xxx.jar.original是什么能不能删遇到这种问题不要慌说明repackage执行成功了。.jar.original是原始jar。群里经常看到有人问它是什么、能不能删能删但下次package时还会生成。如果你实在不想看到它配置classifierexec/classifier就能让原始jar保留为正常名可执行jar带exec后缀。我在无私奉献给其他团队普通jar时用这种模式。4.3 依赖冲突多个版本jar打入包典型表现是启动时报NoSuchMethodError或NoClassDefFoundError比如引入了commons-logging又用了logback或者旧版servlet-api混进依赖树。排查技巧是mvn dependency:tree -Dverbose这会输出完整依赖树找到冲突坐标后在pom里剔除不需要的一方。如果冲突发生在SpringBoot父子依赖和业务依赖之间最稳妥的是在dependencyManagement中统一版本。日志冲突的排除模板我反复用过多次dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-logging/artifactId /exclusion /exclusions /dependency4.4 本地跑通、线上起不来的灵异问题这类问题最常见的原因是profile和环境配置。本地IDE默认加载application-dev.yml线上没传环境参数实际加载了application.yml默认配置可能数据源指向了错误的库或连不上。排查思路是应用启动后先看“The following profiles are active”确认激活的是哪个环境再看日志里有没有数据库连接报错。这类问题有一个很有效的排查手段直接把命令行里额外加上--debug把自动配置的匹配报告打出来哪些条件生效、哪些条件不匹配一目了然。还有一类灵异现象是java -jar跑正常但在sytemd里起不来。大概率是工作目录不对或者是shell里用了相对路径。写systemd单元文件时建议用绝对路径并显式指定WorkingDirectory。4.5 插件版本与SpringBoot版本不匹配用spring-boot-starter-parent时插件版本自动对齐一般没问题。但如果你的项目没有parent而是用dependencyManagement引入SpringBoot BOM就需要手动声明插件版本。用官方BOM的import模式时插件版本不会自动管理这也是新手最容易踩的坑。遇到这种场景用一个跟SpringBoot版本匹配的插件版本即可一般SpringBoot 2.5对应2.5.x2.7对应2.7.x3.x同理。提示SpringBoot 3.x之后用JDK17并替换了jakarta命名空间直接沿用老项目的插件配置往往也能跑但如果同时自定义了较多插件参数建议先用最简单的配置跑通再逐步加参数减少组合问题。5. 进阶场景容器镜像、前端资源与插件组合5.1 Docker镜像构建的最佳拍档SpringBoot的应用镜像重点是充分利用构建缓存。这里以layertools为例。# 先解包分层 java -Djarmodelayertools -jar app.jar extract # 得到分层目录后Dockerfile可以这样写 FROM openjdk:8-jre-alpine AS builder WORKDIR /app COPY --frombuild /app/dependencies/ ./ COPY --frombuild /app/spring-boot-loader/ ./ COPY --frombuild /app/snapshot-dependencies/ ./ COPY --frombuild /app/application/ ./ RUN java -Djarmodelayertools -jar app.jar extract FROM openjdk:8-jre-alpine WORKDIR /app COPY --frombuilder /app/dependencies/ ./ COPY --frombuilder /app/spring-boot-loader/ ./ COPY --frombuilder /app/snapshot-dependencies/ ./ COPY --frombuilder /app/application/ ./ ENTRYPOINT [java, -jar, app.jar]实际项目里我会把依赖分层和业务代码分层两个COPY动作分开。依赖层几乎很少变docker build时该层命中缓存只有业务代码层会重新打包上传。上了这个方案之后服务镜像从每次构建2分钟降到了十几秒区别非常明显。5.2 Vue前端打包进SpringBoot jar有些小团队没有独立部署前端选择把Vue构建产物放进SpringBoot的static目录统一发布。做法是前端构建npm run build产物在dist目录。将dist内容复制进SpringBoot项目的src/main/resources/static。正常mvn package即可前端资源会打进jar。这个过程可以用maven-resources-plugin的copy-resources目标自动化避免每次手动复制plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-frontend-dist/id phasegenerate-resources/phase goals goalcopy-resources/goal /goals configuration outputDirectory${basedir}/src/main/resources/static/outputDirectory resources resource directory${basedir}/../frontend/dist/directory /resource /resources /configuration /execution /executions /plugin这里有一个要注意的点如果前端dist里的文件名带hash多几次构建后static目录会越积越大。最好在copy前先clean掉static目录或者用maven-clean-plugin里的clean目标把static先抹掉不然旧资源全打进jar体积臃肿。5.3 与compiler插件、assembly插件的组合策略SpringBoot插件和maven-compiler-plugin的关系很直接编译的字节码版本直接决定运行环境。JDK8项目升到JDK11时如果编译参数没改还停留在1.8某些新语法特性就无法使用。推荐在pom.properties里显式设置源码与目标版本properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target /propertiesmaven-assembly-plugin是另一个被经常问到的打包插件。如果你是纯SpringBoot应用不需要assembly把依赖打到一个jar里——repackage已经做了。assembly一般用于把脚本、配置、jar包组织成一套发布目录结构。注意两者不要同时把依赖重复打进去容易造成META-INF/services冲突导致某些SPI实现无法加载。我自己遇到过一次某加密组件在纯SpringBoot打包时能跑加了个assembly分发目录之后整个服务起不来排查半天是META-INF/services里多个jar的SPI文件合并出错。6. 未来扩展与个人经验总结如果你正在维护一个多模块仓库、频繁发版、或准备容器化改造spring-boot-maven-plugin是你构建链路里最值得优化的一个核心节点。它不算复杂但每一项配置都直接影响产出物的可用性mainClass错了无法启动classifier错了依赖方拿错产物layers没开启容器构建慢到怀疑人生。从我个人的实践体会来说配置这个插件不需要追求一步到位。我习惯用“最小可运行”起步先按默认配置打出可执行jar本地java -jar跑通再逐步加build-info、加layers、加profile过滤每个config改动后都重新打包启动验证一遍。这样出了问题很容易判断是哪一步引入的。反过来如果你一次性把网上搜来的完整配置塞进去一旦启动失败很难定位是插件问题还是环境问题。最后分享一个小技巧把mvn clean package -DskipTests绑成一个shell脚本别名再配合-pl指定模块基本能把本地构建成本压到最低。这套组合我已经用了很久实测下来无论是“改完代码立刻要验证”还是“发版前完整构建”都比裸的mvn package顺滑得多。
)
