开篇先聊个现象不管你是刚学 SpringBoot 的初学者还是已经写了几年 Java 的老手只要打开一个 SpringBoot 项目的 pom.xml基本都能看到buildplugins这一段里面躺着 spring-boot-maven-plugin、maven-compiler-plugin 这些插件配置。很多人平时根本不碰这块直到某天打包报错、测试跑不起来、或者想打个可执行 jar 给运维部署时才发现自己对 pom 里的 plugin 几乎一无所知。这篇文章就做一件事把 SpringBoot 项目 pom 里的 plugin 插件用法彻底讲透。我会从“plugin 和 dependency 到底有什么区别”这种最基本的概念讲起再到几个核心插件的参数拆解、完整可抄走的配置模板、以及我这些年踩过的插件相关报错和排查思路。适合所有用 Maven 管理 SpringBoot 项目的同学不管你是刚入门还是已经对 Maven 有一定了解看完应该都能对 pom 里的 plugin 有一个系统性的认识。1. 先搞懂 pom 里的 plugin 和 dependency 到底有什么区别很多新手第一次看到 pom 里的dependencies和buildplugins时会下意识把它们当成同一类东西。实际上这俩是完全不同的两个维度理解清楚这一层后面所有插件配置才能看得明白。1.1 从一次“诡异”的打包失败说起先说个真实案例。有次我接手一个老项目同事在 pom 里加了一段依赖想在代码里调用某个库的功能结果mvn clean package一直报找不到这个包。他反复确认坐标没问题、仓库里也有最后才发现他把依赖写进了buildpluginsplugin里而不是dependencies里。这个例子很典型。Maven 的dependencies声明的是“项目运行时和编译期需要引用的库”比如 spring-boot-starter-web、mybatis、lombok 这些。它们会被加到你的 classpath 里让你的 Java 代码能import并调用。而buildplugins里声明的是“Maven 构建过程中要执行的任务”插件本身也是 jar但它们的运行者是 Maven 自身不是你的业务代码。插件的作用是在生命周期里做各种事情比如编译代码、运行测试、打包 jar、拷贝文件、生成文档。说白了dependency 是给你的代码用的工具库plugin 是给 Maven 构建流程用的“执行器”。你的代码里永远不会import一个 plugin 的类但你的构建过程每一步都可能是插件在执行。1.2 plugin 在 Maven 生命周期里的位置搞清楚基本区别后再看 Maven 的构建生命周期就顺理成章了。Maven 的生命周期可以粗暴理解成一条流水线validate → compile → test → package → verify → install → deploy。每个阶段默认绑定了一些插件执行。比如compile阶段默认绑定 maven-compiler-plugintest阶段默认绑定 maven-surefire-pluginpackage阶段绑定 maven-jar-plugin 或 maven-war-plugin。SpringBoot 项目里的 spring-boot-maven-plugin 则是覆盖了repackage目标把本来普普通通的 jar 重打成一个可执行的 fat jar。这也解释了为什么你哪怕不在 pom 里显式声明这些插件mvn 依然能正常编译打包——因为 Maven 有默认绑定的一套插件。但你一旦需要定制行为比如指定 Java 编译版本、跳过测试、自定义 jar 包名就必须在 pom 里显式声明并配置插件参数。插件配置的本质就是覆盖 Maven 的默认行为。2. SpringBoot 项目最常用的几个 Maven 插件逐个拆解下面进入正题逐个拆解 SpringBoot 项目里出场率最高的几个插件。这些插件我基本每个项目都会用到各自的参数和坑也摸得比较透。2.1 spring-boot-maven-plugin可执行 Jar 的幕后功臣这是 SpringBoot 项目的灵魂插件。SpringBoot 官网说得很直白这个插件提供了 SpringBoot 应用的打包、运行、构建信息生成等功能。最核心的 goal 是repackage它会在 Maven 默认的package阶段之后把项目原本打出来的普通 jar 重新组织生成一个可以直接java -jar启动的 fat jar。这里有个关键点很多人不理解SpringBoot 的 fat jar 是“嵌套 jar”结构BOOT-INF/lib里面躺满了所有第三方依赖BOOT-INF/classes才是你自己的代码。普通 jar 和 fat jar 的区别在于fat jar 通过自定义的JarLauncher来加载这些嵌套 jar而不是走标准的 JDKClassLoader。这也是为什么你用java -jar启动 SpringBoot 项目没问题但如果在 IDE 里直接运行测试时依赖不到这些类大概率是 classpath 没配好而不是插件有问题。常见配置参数mainClass指定启动类。如果项目里只有一个SpringBootApplication插件会自动识别不需要手动写但如果有多模块项目或特殊结构就得显式指定。skip设为 true 可以跳过 repackage 目标。比如子模块可能只需要被打成普通 jar 给其他模块依赖不需要可执行包。classifier如果既要可执行 jar又需要普通 jar比如同时作为一个被依赖的模块和一个独立服务可以给可执行的 jar 加一个 classifier比如exec然后依赖方用普通 jar 的坐标引用。一个很实用的场景是配合build-info目标生成META-INF/build-info.properties里面记录构建时间和版本号。你可以通过 actuator 的/info端点直接暴露出来部署上线后一眼看出线上跑的是哪个版本、什么时候构建的。后面第 3.2 节我会给出具体配置。2.2 maven-compiler-pluginJava 版本不是配一下就完事maven-compiler-plugin 负责把 Java 源码编译成 class 文件。很多人以为在pom.xml里声明一下java.version1.8/java.versionSpringBoot 父 POM 提供的属性就完事了其实这个属性最终要传给 maven-compiler-plugin 的source和target参数。source表示源码使用的语法版本target表示生成的字节码目标版本。比如source1.8, target1.8意味着你用 JDK 17 编译也能产出 Java 8 的字节码。但这里有个陷阱source和target只是让你的代码“语法上”兼容低版本如果代码里用了 JDK 17 的 API编译时还是能引用到高版本的方法签名运行时在 Java 8 环境会直接抛出NoSuchMethodError或UnsupportedClassVersionError。所以工程上更推荐设置release8/release。release参数会同时约束源码语法、字节码目标并且限制对 JDK API 的引用范围从源头上避免“编译能过但运行报错”的问题。如果你的项目还跑在 Java 8 上但本地开发用了新 JDK强烈建议把source/target换成release。SpringBoot 3.x 之后最低要求 Java 17已经不再支持 Java 8选型时要注意版本配套。另外如果想在编译时可以-parameters保留参数名比如 Spring MVC 通过参数名绑定请求参数时在插件里加parameterstrue/parameters就行。有些组件如 MyBatis 或 Jakarta Bean Validation 在反射时也会受益于这个参数。2.3 maven-surefire-plugin 与 maven-failsafe-plugin测试跑不跑命运在它们手里maven-surefire-plugin 执行test阶段的单元测试。默认规则是匹配src/test/java下以Test结尾、或类名以Test/Tests开头、或以TestCase结尾的类。如果你写了测试但 mvn 跑的时候没执行大概率是命名没符合规则而不是 JUnit 没配。这个插件最常用的参数是skipTests和maven.test.skip。命令行里跑mvn install -DskipTests只是跳过测试执行但测试代码还是会被编译mvn install -Dmaven.test.skiptrue则连测试代码都不编译。一般 CI 上跑完整测试用前者本地临时打包想省时间用后者但别养成所有构建都 skip 测试的习惯回归问题就是这么漏出去的。另一个配置点是argLine比如在运行测试时设置堆内存或读取环境变量。Java 9 之后的模块系统对反射限制很严格跑测试时如果要用反射访问 JDK 内部 API经常需要在这个参数里加--add-opens。我见过不少项目在本地 IDE 跑测试没问题、一到命令行 mvn 跑就挂最后排查出来就是argLine里缺了这些 JVM 参数。maven-failsafe-plugin 管的是集成测试默认匹配*IT.java或*ITCase.java结尾的类绑定在integration-test阶段。它的特点是即使有测试失败也不会立刻终止构建而是先跑完所有测试最后在verify阶段统一报告失败这样方便把单元测试和集成测试区分开。如果你的项目有需要起完整 Spring 容器或依赖外部服务的测试建议把它们放到src/it或按IT后缀命名用 failsafe 单独管理这样打包时不想跑集成测试也只用跳过 failsafe 一个插件。2.4 maven-jar-plugin / maven-assembly-plugin当默认打包不满足需求时maven-jar-plugin 控制普通 jar 的生成包括 manifest 文件内容、jar 包文件名、excludes排除某些 class 等。SpringBoot 场景下它负责生成那个“原始 jar”spring-boot-maven-plugin 的repackage会基于这个原始 jar 做二次包装。所以如果你发现打包产物里 Manifest 主类不对或者 jar 里多了不该有的文件先看 maven-jar-plugin 的配置对不对。maven-assembly-plugin 则是万能打包器适合自定义各种分发格式。比如想把项目依赖、配置文件、启动脚本打成一个 tar.gz 直接发到服务器上或者做一个包含所有依赖的“thin jar”目录结构assembly 都能干。它用自定义的assembly.xml描述文件来定义什么文件放什么位置灵活度比 spring-boot-maven-plugin 高很多但也更容易配置错我建议只有确实需要自定义发布结构时再去碰它。还有一个小众但很常见的需求项目里的BOOT-INF/lib有大量 jar导致docker build时每个依赖变化都要重新上传所有依赖。这时可以用 maven-dependency-plugin 的copy-dependencies目标把依赖拷到单独目录Dockerfile 里分层拷贝命中缓存的概率会大幅提升。这个优化手段在 CI 构建镜像时尤其有用。3. 一组可直接抄走的 pom 插件配置实战理论讲了半天还是得落到具体配置上。下面给出一套我实际在多个 SpringBoot 项目里验证过的 pom 插件配置模板覆盖多环境资源处理、构建信息生成、测试覆盖率和 Docker 镜像构建你可以直接复制改改就能用。3.1 标准 SpringBoot 多环境 pom 骨架build finalName${project.artifactId}/finalName resources resource directorysrc/main/resources/directory filteringtrue/filtering excludes exclude**/*.jks/exclude exclude**/*.p12/exclude /excludes /resource /resources plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration mainClasscom.example.demo.DemoApplication/mainClass /configuration executions execution goals goalrepackage/goal /goals /execution /executions /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration release8/release parameterstrue/parameters /configuration /plugin /plugins /build这段配置里有个容易忽略的点finalName决定了最终 jar/war 的文件名。如果不设置默认是${artifactId}-${version}.jar版本号变了文件名也跟着变。运维那边如果写死了文件名每次升级都要改脚本所以很多团队会把版本号去掉。resources里的filteringtrue/filtering表示对资源文件做占位符替换。配合 Maven Profile 使用可以在打包时把application.yml里的profile.active替换成指定的环境。比如资源配置spring: profiles: active: profile.active打包时mvn clean package -Pprod就会替换成prod。但注意密码、证书这类东西不要放到被过滤的资源里免得构建过程里出幺蛾子我在配置里专门把jks、p12证书文件排除了因为二进制文件经过过滤会被写坏这是个写进血泪史的问题。3.2 用 build-info 与 Git 信息给 jar 加“身份证”生产环境排查问题时最怕的就是不知道线上跑的是哪次构建。spring-boot-maven-plugin 的build-info目标可以解决这个问题plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId executions execution goals goalrepackage/goal goalbuild-info/goal /goals /execution /executions /plugin执行后会在META-INF/build-info.properties里生成build.time和build.artifact。如果你用 Git 管理代码再加一个 git-commit-id-plugin 或 maven-scm-plugin把 commit hash 和分支信息写进去。配合 Spring Boot Actuator 的/actuator/info就能在浏览器里直接看到当前应用是哪个 commit 构建的。这个能力在多人协作、快速迭代的团队里非常值钱——不用再挨个服务器 diff 文件了。3.3 单元测试与覆盖率插件配置如果你正在搭建一个新项目建议一开始就把测试相关插件配好后面再补的成本会高很多。plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId version2.22.2/version configuration argLine-Dfile.encodingUTF-8/argLine includes include**/*Test.java/include /includes /configuration /plugin plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.8/version executions execution goals goalprepare-agent/goal /goals /execution execution idreport/id phaseverify/phase goals goalreport/goal /goals /execution /executions /pluginsurefire 的argLine加 UTF-8 编码是我吃过亏之后加上的Windows 环境下控制台输出和测试断言里的中文经常因为这玩意变成乱码。JaCoCo 的prepare-agent会在测试启动时插入 agent 统计覆盖率report在verify阶段生成 HTML 报告。如果 CI 上要求覆盖率阈值再加check目标并配置minimum规则不达标直接构建失败。4. 常见插件报错与排查实录最后这部分分享一些我实际遇到过的插件相关报错和排查过程。这些报错在网上被问过无数次但每次出现时还是有一批人被卡住我把排查思路整理成速查表方便你以后直接对照。4.1 non-resolvable parent pom / 依赖下载不下来报错信息大概是Non-resolvable parent POM for com.example:demo:0.0.1-SNAPSHOT: Could not find artifact ...或者The following artifacts could not be resolved。遇到这种问题90% 是仓库访问不到某个依赖了。排查顺序我建议这样走先确认本机 Maven 的 settings.xml 里localRepository指向的目录是否存在且可写再去检查仓库镜像配置国内网络环境下最常用的方案是用阿里云 Maven 仓库镜像在 settings.xml 的mirrors里配置mirrorOfcentral/mirrorOf指向https://maven.aliyun.com/repository/public最后确认 parent 的 groupId/artifactId/version 没写错特别是有多层继承时每一层的 parent 都要能正确解析。遇到某个构件一直下载失败或下载到一半损坏可以先删掉本地仓库里对应的.lastUpdated文件再重新构建。我之前碰到过一次 jar 包下载不完整Maven 死活不肯重新下载清掉.lastUpdated后立即恢复。一个更省事的做法是给 Maven 加-U参数强制更新快照但注意这个参数会拉取所有快照构建会变慢。4.2 could not calculate build plan插件版本不兼容报错里有Could not calculate build plan for Plugin: org.apache.maven.plugins:maven-jar-plugin时通常是插件版本太旧或者插件与当前 JDK 不兼容。比如老版本的 maven-jar-plugin 在 JDK 17 下会因为缺模块访问权而报错。解决思路是显式声明插件版本或者升级 SpringBoot 父 POM 到一个能覆盖这些插件默认版本的新版本。这里有个通用建议除非需要定制否则不要轻易给生命周期核心插件compiler、surefire、jar手动指定过旧的版本跟着 SpringBoot 父 POM 自带的版本走是最稳的。自定义插件的版本再单独管理。4.3 spring-boot-maven-plugin repackage 后 jar 无法运行这个报错有两种典型形态一种是用java -jar启动时提示no main manifest attribute另一种是启动后 Spring 容器初始化一大堆但最终报ClassNotFoundException。第一类问题通常是没有执行repackage目标。SpringBoot 的 starter parent 已经默认帮所有模块声明了 repackage 执行但如果你的项目没有继承 starter parent或者手动覆盖了executions就得显式加上。第二类问题一般是 jar 结构不对或者手动用 maven-assembly-plugin 打出来的“假 fat jar”没有正确的启动器因为普通 jar 嵌套依赖 JDK 是加载不了的。还有一个很容易踩的坑多模块项目里如果 A 模块依赖 B 模块B 模块被 spring-boot-maven-plugin 重新打包成了 fat jarA 模块引用 B 时会把 B 的BOOT-INF/classes当 classpath导致找不到类。解决办法是给 B 的可执行 jar 加classifierexec/classifier让 A 依赖 B 的原始 jar部署时才使用可执行 jar。4.4 配置文件没被拷贝或资源文件乱码如果你发现打包后的 jar 里没有application.yml或者配置文件里的中文变成了乱码十有八九是resources配置出了问题。Maven 默认只把src/main/resources下的文件当成资源一旦你自定义了resources就会覆盖默认行为需要把原来的资源目录重新加回来。二进制文件被filteringtrue处理是最容易静默出错的情况前面提过 jks 证书会被写坏导致运行时 SSL 握手失败而且这种失败不报“文件损坏”而是报一些奇怪的握手错误排查起来非常头疼。我现在的习惯是默认对所有文本资源配置过滤但显式排除**/*.jks、**/*.p12、**/*.key这类二进制文件同时在打包后抽查一下 jar 里的证书文件大小是否和源文件一致。另外如果用到spring-boot-maven-plugin时希望把src/main/resources下的文件在某些环境替换而另一些环境不替换可以结合 Profile 控制过滤的开启和关闭。把环境策略说清楚比让运维在服务器上改配置要稳妥得多。最后再分享一个小技巧我个人在实际操作中养成了一个习惯每次新项目初始化时第一件事就是把pom.xml里插件版本、依赖版本全部显式列出来并写清楚版本号。虽然 SpringBoot 父 POM 帮你管理了大量版本但显式声明关键插件的版本能有效避免“今天本地能跑、明天 CI 挂了”的玄学问题。Maven 的一个特性是如果依赖和插件版本不写会用默认值默认值在不同 Maven 版本下可能不一样这就会带来环境差异。遇到插件问题也不要急着网上乱搜可以先mvn help:effective-pom看当前项目实际生效的 POM 是什么样所有的插件执行、版本都一目了然。这个命令比任何 IDE 的 Maven 面板都诚实能帮你绕过绝大多数“配置了但实际没生效”的困惑。