1. 问题现场一个典型的Spring Boot打包失败场景今天下午我正在为一个内部工具项目做版本发布前的最后打包。项目基于Spring Boot 2.7.x之前一直运行良好。当我信心满满地在终端敲下mvn clean package -DskipTests后熟悉的构建进度条开始滚动。然而几秒钟后控制台突然“爆红”一个刺眼的错误信息跳了出来[ERROR] Failed to execute goal org.springframework.boot:spring-boot-maven-plugin:2.7.18:repackage (default) on project my-tool: Execution default of goal org.springframework.boot:spring-boot-maven-plugin:2.7.18:repackage failed: Unable to find a single main class from the following candidates [com.example.MyApplication, com.example.AnotherMainClass]或者更常见的一种变体是[ERROR] Failed to execute goal org.springframework.boot:spring-boot-maven-plugin:3.1.5:repackage (default) on project api-service: Unable to find main class又或者是直接提示插件本身找不到[ERROR] Plugin org.springframework.boot:spring-boot-maven-plugin:3.0.0 or one of its dependencies could not be resolved: Could not find artifact org.springframework.boot:spring-boot-maven-plugin:jar:3.0.0 in central (https://repo.maven.apache.org/maven2)无论具体措辞如何核心都指向了org.springframework.boot:spring-boot-maven-plugin这个插件在执行repackage目标时失败了。对于任何使用Spring Boot和Maven的开发者来说这绝对是一个高频“拦路虎”。它看似简单背后却可能隐藏着从项目配置、依赖管理到环境设置的多种问题。这篇文章我就结合自己多次踩坑和帮同事排查的经验把这个问题的来龙去脉、排查思路和解决方案彻底讲透让你下次遇到时能快速定位手到病除。2. 核心插件spring-boot-maven-plugin 到底在干什么要解决问题必须先理解问题。这个错误的核心是spring-boot-maven-plugin插件执行失败。所以我们首先得搞清楚这个插件在package阶段扮演了什么角色。在标准的Maven生命周期中package阶段默认会调用maven-jar-plugin生成一个普通的.jar文件。这个JAR文件只包含你项目编译后的类文件和资源不包含项目所依赖的第三方库它们通常在~/.m2/repository下。如果你直接运行java -jar yourapp.jar会因找不到依赖而报ClassNotFoundException。spring-boot-maven-plugin的repackage目标goal彻底改变了这一点。它的核心工作可以概括为“重新打包”或“重构包”拦截默认打包它在Maven的package阶段之后执行会“拦截”由maven-jar-plugin生成的原始JAR文件通常称为original-*.jar。创建可执行Fat JAR它读取项目的所有依赖包括传递依赖将这些依赖的.jar文件全部解压并将其中的.class文件和你项目的.class文件一起重新打包到一个新的、更大的JAR文件中。这个新JAR就是所谓的“Fat JAR”或“Uber JAR”。嵌入启动器更重要的是它会将Spring Boot特有的启动器类org.springframework.boot.loader.JarLauncher等打包进去并修改JAR的清单文件MANIFEST.MF指定这个启动器作为主类。当你执行java -jar时实际上是这个启动器最先运行它负责在内存中构造正确的类加载路径LaunchedURLClassLoader从而能够加载Fat JAR内部嵌套的所有依赖类。所以当插件报错时本质是它在执行上述复杂打包逻辑的某个环节遇到了障碍。接下来我们就按图索骥从最常见到最隐蔽的原因逐一拆解。3. 原因一主类Main Class无法确定或找不到这是导致Unable to find main class错误的最直接原因。插件需要知道哪个类是Spring Boot应用的入口以便正确配置MANIFEST.MF。3.1 项目中有多个标注了SpringBootApplication的类这是最经典的情况。Spring Boot插件会扫描项目寻找带有SpringBootApplication注解的类。如果找到多个它就“懵了”不知道应该把哪个设为可执行JAR的主类。排查与解决全局搜索在项目的src/main/java目录下全局搜索SpringBootApplication。你可能会意外地发现除了你熟知的主启动类在某个测试目录src/test/java或者某个被错误放置的配置类中也存在这个注解。清理测试类确保src/test/java下的测试启动类没有错误地添加了SpringBootApplication。测试启动类应该使用SpringBootTest并且通常不需要打包进生产JAR。明确指定如果确实需要多个配置类或者结构特殊你必须在pom.xml中显式地告诉插件主类是哪一个。build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration !-- 明确指定主类 -- mainClasscom.example.yourreal.MainApplication/mainClass /configuration /plugin /plugins /build3.2 主类不在默认的扫描范围内插件默认会在编译输出的类路径中寻找主类。如果你的项目模块结构复杂例如多模块项目或者打包时做了一些特殊的过滤可能导致主类文件没有被包含进即将被打包的类文件集合里。排查与解决检查编译输出执行mvn clean compile后去target/classes目录下查看你的主类如com/example/Application.class是否存在。多模块项目注意在父模块执行package时如果子模块的打包方式packaging是jar且该子模块包含了启动类那么插件应该在那个子模块中运行。确保插件配置在正确的子模块的pom.xml中而不是在父模块中。父模块的packaging通常是pom它本身不包含代码也就不需要这个插件。3.3 使用了非标准的构建配置有些项目可能使用了maven-shade-plugin或其他插件对输出进行了深度处理这可能会干扰spring-boot-maven-plugin对主类的识别。或者你在pom.xml中通过properties或插件配置错误地指定了一个不存在的类作为主类。排查与解决检查pom.xml配置仔细核对mainClass配置的值确保包名和类名完全正确没有拼写错误。插件执行顺序如果使用了maven-shade-plugin通常需要将spring-boot-maven-plugin放在它后面执行因为repackage目标需要基于一个已存在的JAR文件进行操作。你可以通过调整插件在pom.xml中的声明顺序或使用executions标签来定义阶段phase来控制。4. 原因二插件版本不匹配或依赖解析失败错误信息中如果包含Could not find artifact或Plugin ... could not be resolved这就进入了依赖管理的领域。4.1 插件版本与Spring Boot版本不兼容这是升级Spring Boot版本时极易踩的坑。spring-boot-maven-plugin的版本应该与项目使用的spring-boot-starter-parent或spring-boot-dependenciesBOM物料清单中定义的版本保持一致。排查与解决查看父POM或依赖管理如果你的项目继承了spring-boot-starter-parent那么插件版本通常无需显式声明会自动继承父POM中的版本。检查父POM的版本是否是你期望的。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version !-- 插件也会使用这个版本 -- relativePath/ /parent使用dependencyManagement如果没有使用父POM而是通过dependencyManagement导入BOM那么你也需要在插件声明中指定版本或者确保BOM也管理了插件版本Spring Boot的BOM通常包含。dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version3.1.5/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement build plugins !-- 此时可以不写版本由BOM管理 -- plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build版本冲突如果项目中其他插件或依赖强制指定了另一个版本的spring-boot-maven-plugin可能会引起冲突。使用mvn dependency:tree -Dincludesorg.springframework.boot:spring-boot-maven-plugin命令查看插件依赖树。4.2 Maven仓库网络问题或本地仓库损坏有时候问题无关配置而是环境问题。Maven无法从远程仓库如Maven Central下载插件或其依赖。排查与解决检查网络和代理确保你的网络可以访问Maven中央仓库。如果公司使用内网镜像如Nexus检查settings.xml配置是否正确。清理本地仓库Maven本地仓库默认在~/.m2/repository中的文件可能损坏。可以尝试删除该插件对应的目录然后重新构建强制Maven重新下载。# 例如删除 spring-boot-maven-plugin 3.1.5 的本地缓存 rm -rf ~/.m2/repository/org/springframework/boot/spring-boot-maven-plugin/3.1.5/ mvn clean package -U # -U 参数强制更新快照和释放版使用-o离线模式测试执行mvn clean package -o。如果离线模式成功但在线模式失败基本可以断定是网络或远程仓库问题。如果离线模式也失败则可能是本地仓库损坏或配置有误。5. 原因三项目结构或打包配置问题项目的打包方式packaging和资源过滤配置也可能导致插件工作异常。5.1 打包类型Packaging不是jarspring-boot-maven-plugin的repackage目标默认只对packaging类型为jar或war的项目生效。如果你的项目pom.xml中设置的是packagingpom/packaging插件将不会执行或者执行时找不到合适的工件artifact进行处理。排查与解决对于需要生成可执行JAR的模块确保其packagingjar/packaging默认就是jar所以通常不用写。5.2 资源过滤导致配置文件被破坏Maven的资源过滤Resource Filtering功能会在构建过程中替换资源文件如application.properties中的占位符如${project.version}。如果过滤规则配置不当可能会破坏一些对格式敏感的文件甚至影响插件的内部文件。一个隐蔽的坑极端情况下如果过滤配置错误地应用于META-INF/目录下的文件可能会损坏MANIFEST.MF或Spring Boot的特定元数据文件导致插件在后续步骤中出错。排查与解决检查pom.xml中buildresources部分的配置看是否有过于宽泛的过滤设置。通常建议排除META-INF/**目录不被过滤。build resources resource directorysrc/main/resources/directory filteringtrue/filtering excludes excludeMETA-INF/**/exclude /excludes /resource /resources /build6. 系统性排查指南从错误信息出发的实战流程当错误发生时不要盲目尝试。遵循一个系统的排查流程可以极大提升效率。第一步仔细阅读错误信息复制完整的错误堆栈不要只看最后一行。错误信息中往往包含了具体的类名、路径、版本号等关键线索。区分是“找不到主类”还是“解析插件失败”这决定了排查的主要方向。第二步验证基础环境Java版本运行java -version和mvn -v确认Java版本与Spring Boot版本兼容。例如Spring Boot 3.x 需要 Java 17。Maven版本使用较新且稳定的Maven版本如3.6.3老版本可能存在已知的依赖解析bug。IDE缓存如果你在IDE如IntelliJ IDEA中操作尝试执行File - Invalidate Caches and Restart...清除IDE的构建缓存。有时IDE的缓存与命令行Maven状态不一致。第三步执行最小化构建命令在项目根目录打开命令行终端。执行mvn clean清理所有旧的构建产物。执行mvn compile只编译看是否有编译错误。先确保代码本身没问题。执行mvn spring-boot:run尝试直接运行应用。如果这个命令能成功说明应用本身和基础依赖没问题问题很可能出在打包阶段的具体配置上。第四步深入分析POM文件使用Maven帮助插件执行mvn help:effective-pom -Doutputeffective-pom.xml生成“有效POM”。这个文件合并了所有父POM、settings.xml和当前POM的配置是你项目构建的真实配置。用文本编辑器打开它搜索spring-boot-maven-plugin查看其最终生效的配置和版本。检查依赖冲突执行mvn dependency:tree -Dverbose depTree.txt将依赖树输出到文件。搜索是否有多个不同版本的Spring Boot核心库或插件被引入。重点关注verbose模式输出的(version managed from ...)和omitted for conflict with ...信息。第五步分而治之针对多模块项目如果项目是多模块的在根目录执行mvn clean install可能会因为某个子模块失败而整体失败。进入疑似有问题的子模块目录。单独在该模块执行mvn clean package。这样可以精准定位问题模块避免其他模块的干扰。7. 进阶场景与特殊配置的避坑要点除了上述通用问题在一些特定场景下还需要额外的注意。7.1 构建可执行的War文件Spring Boot也支持将应用打包为可执行的War文件部署到外部Servlet容器如Tomcat时它作为一个普通的War工作单独使用java -jar启动时它又作为一个可执行应用工作。配置要点将packaging改为war。需要标记内嵌容器依赖为provided范围避免它们被打包进War导致与外部容器冲突。确保spring-boot-maven-plugin配置正确它会处理可执行War的打包逻辑。packagingwar/packaging dependencies !-- 内嵌Tomcat打包时排除 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId scopeprovided/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build7.2 使用自定义的Classifier或FinalName如果你通过finalName或插件配置修改了输出JAR的名字需要确保spring-boot-maven-plugin能正确找到这个文件进行重打包。配置示例build finalNamemy-application-${project.version}/finalName plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration !-- 如果使用了classifier需要在这里指定 -- !-- classifierexec/classifier -- !-- 插件默认能识别 finalName通常无需额外配置 -- /configuration /plugin /plugins /build7.3 在CI/CD流水线中遇到的特殊问题持续集成环境中由于环境干净、构建隔离一些问题更容易暴露。镜像源速度慢或不可用在Dockerfile或CI脚本中务必配置可靠的Maven镜像源可以使用阿里云、腾讯云等国内镜像加速下载。内存不足构建大型Spring Boot应用特别是包含大量依赖时Maven进程可能内存不足。在CI脚本中设置MAVEN_OPTS-Xmx2048m或更大值。缓存策略合理利用CI系统的缓存机制缓存Maven本地仓库~/.m2/repository可以大幅加速构建。但也要注意缓存过期问题避免使用了错误的依赖版本。8. 总结与个人工具箱经过上面这一轮深度拆解你会发现Failed to execute goal org.springframework.boot:spring-boot-maven-plugin这个错误就像一个信号灯它本身不是问题而是告诉你构建过程的某个环节亮起了红灯。我的习惯是遇到这个问题心里立刻建立一个排查清单第一反应看主类是不是有多个SpringBootApplication插件配置里指定了吗第二反应看版本Spring Boot大版本升级后插件版本跟上了吗依赖树干净吗第三反应看环境mvn -v和java -version对得上吗本地仓库是不是该清理了第四反应看结构这是多模块项目吗插件配在正确的子模块里了吗打包类型对吗最后分享两个我常用的“杀手锏”命令在排查这类问题时特别有用mvn clean spring-boot:run如果直接运行能成功打包却失败那问题九成出在打包插件配置或阶段上可以暂时绕开打包快速验证应用本身。mvn clean package -X加上-X调试参数Maven会打印出极其详细的执行日志包括每一个目标的执行过程、依赖下载的URL、配置项的最终值等。当所有常规手段都失效时仔细分析这份日志几乎总能找到线索。虽然日志很长但你可以搜索spring-boot-maven-plugin或repackage来快速定位相关部分。打包问题虽然烦人但每一次解决都是对项目构建流程的一次深入理解。把上述思路和工具纳入你的知识库下次再见到这个错误你就能从容应对快速定位到那个“亮红灯”的环节了。