前段时间接手一个 Spring Boot 项目新环境上签出代码IDEA 里 Maven 一刷新pom 直接一行红字Plugin org.springframework.boot:spring-boot-maven-plugin not found。紧接着命令行执行mvn clean package也报同样的错。这不是什么罕见的报错几乎每天在技术社区里都能看到它的身影。但这行红字背后的原因其实不是一个而是好几个网络、配置、缓存、仓库都可能踩中。这篇就把我这次排查的过程、尝试过的方案和最后定位到的根因完整记录下来顺便把各种not found类问题的通用排查思路也捋一遍给后面再遇到的人省点时间。1. 这个报错到底在说什么1.1 报错长什么样什么时候出现先明确一下报错的完整形态。在 IDEA 的 Maven 工具窗里pom 文件中的plugin节点下方会有红色波浪线鼠标悬停提示Plugin org.springframework.boot:spring-boot-maven-plugin not found。在命令行执行 Maven 生命周期命令时则有类似这样的输出[ERROR] Plugin org.springframework.boot:spring-boot-maven-plugin not found: https://repo.maven.apache.org/maven2 [ERROR] plugin org.springframework.boot:spring-boot-maven-plugin not found in any source repository这个报错最常出现的几类场景是新建一个 Spring Boot 项目什么都没改第一个mvn clean package就失败从 Git 上拉下来的老项目别人能正常打包自己本地却报找不到插件项目从 Spring Boot 2.x 升级到 3.x或者从旧电脑迁移到新电脑后突然开始报错多模块项目里父模块能正常构建某个子模块单独构建却报插件找不到IDEA 里 Maven 面板正常命令行却失败或者反过来。这些场景虽然表象都一样但根因可能完全不同。所以上来就搜“spirng-boot-maven-plugin not found 怎么解决”然后抄一段镜像配置改 settings.xml不一定能解决你的问题。得先理解 Maven 是怎么找插件的才能对症下药。1.2 明明代码没问题为什么插件会“找不到”很多人第一反应是“我这个项目代码没写错啊为什么插件找不到”。关键点在于Maven 本身并不自带spring-boot-maven-plugin这个插件。Maven 内置的插件是maven-compiler-plugin、maven-surefire-plugin、maven-jar-plugin这类编译、测试、打包的基础插件。而spring-boot-maven-plugin是 Spring Boot 官方提供的第三方插件它的作用是生成可执行 fat jar、启动 Spring Boot 应用、生成 build-info 等。也就是说它需要从远程仓库下载到本地仓库后才能被 Maven 找到并使用。整个查找流程可以类比成网购pom 里写了插件坐标相当于下了个订单指名要org.springframework.boot:spring-boot-maven-plugin这个商品如果 pom 里没写版本号Maven 会去继承过来的父工程parent或自身的pluginManagement里找版本定义拿到坐标和版本后Maven 先去本地仓库默认在~/.m2/repository找 jar 和 pom本地没有就去配置的远程仓库下载远程仓库下载失败就会在本地仓库生成一个.lastUpdated的失败标记文件并抛出错题。所以“plugin not found”翻译成人话是要么版本定义缺失Maven 不知道要下载哪个版本要么版本定义了但仓库里拉不下来这个 jar。这里还有一个容易忽略的细节Spring Boot 官方通过spring-boot-starter-parent在自己的pluginManagement里声明了spring-boot-maven-plugin的版本。所以如果你在 pom 里继承了 starter-parent插件节点是可以不写version的Maven 会从 parent 的pluginManagement里继承版本号。如果项目没继承 parent又没手动声明版本那 Maven 在解析插件时就会直接报找不到版本进而出现这个 not found。这个区别是后面排查的关键分水岭。2. 快速定位三步看出问题根因2.1 第一步确认 parent 与插件版本声明排查这个报错我建议不要一上来就动 settings.xml先看自己工程的 pom 配得对不对。先看两处第一项目有没有继承spring-boot-starter-parentparent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent第二如果没继承那build里的插件节点有没有写版本号build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId version2.7.18/version /plugin /plugins /build注意一点Spring Boot 3.x 要求 JDK 17 及以上Maven 版本也建议 3.6.3 以上。如果机器上 JDK 或 Maven 版本太老即使插件坐标没问题下载和解析插件时也可能出现各种奇怪错误包括 not found。如果你不确定当前工程实际生效的 parent 和插件版本是什么直接执行mvn help:effective-pom这个命令会把所有继承关系合并后的最终 pom 打出来。在输出的plugins里如果能找到spring-boot-maven-plugin且带版本号说明 pom 层是没问题的如果插件版本缺失问题就出在这一步先补版本或继承 parent 再往下走。2.2 第二步确认远程仓库与镜像能不能连通pom 配置没问题基本就是仓库下载环节了。这时候看一下 Maven 的全局配置settings.xml。Mac/Linux 下默认路径是~/.m2/settings.xmlWindows 下是C:\Users\你的用户名\.m2\settings.xml。重点检查两块一是localRepository确认本地仓库实际路径以及磁盘是否还有空间。某些情况下降级或空间不足会下到一半失败Maven 就直接标记 not found。二是mirrors镜像配置。常见的问题是 mirrorOf 配了*把所有的仓库请求包括中央仓库和公司私有仓库都拦截到某个镜像。而这个镜像如果不可用那所有插件下载统统失败报错结果就是 not found。一个最直接的验证方式用 curl 或浏览器访问插件所在的仓库路径。比如访问中央仓库https://repo.maven.apache.org/maven2/org/springframework/boot/spring-boot-maven-plugin/看目录列表能否正常打开、能看到当前有哪些版本。如果不能访问或者极慢基本可以确认是网络层的问题。国内开发环境下把仓库指向国内镜像往往立竿见影。这个在第三部分的方案 B 里详细展开。2.3 第三步检查本地仓库有没有被缓存的错误记录如果 pom 没问题网络也通那大概率是本地仓库缓存了失败状态。Maven 下载插件失败时会在本地仓库对应目录下生成.lastUpdated后缀的文件比如spring-boot-maven-plugin-2.7.18.pom.lastUpdated spring-boot-maven-plugin-2.7.18.jar.lastUpdated这个文件是下载失败的标记。Maven 默认在一段时间内看到这个标记会认为“这个仓库源已经拉取失败过”不再反复请求直接沿用失败结果导致你每次构建都秒报 not found完全不去远程仓库重新下载。排查方式很简单看本地仓库路径下有没有这个插件目录ls ~/.m2/repository/org/springframework/boot/spring-boot-maven-plugin/如果里面除了一堆.lastUpdated文件之外什么都没有基本就是它了。解决方式是删掉这些失败标记然后强制重新更新。这个我在第三部分的修复步骤里会一并说。3. 完整修复实操从报错到打包成功3.1 修前准备统一环境信息动手改配置之前先把环境信息摸清楚。很多问题的出现本质上是因为 IDE 内置的 Maven 和命令行用的 Maven 不是同一个settings.xml 也不是同一个。先看这几项java -version mvn -versionmvn -version输出里能看到 Maven 版本、Java 版本、以及默认的 settings 文件路径。如果这条命令直接报mvn: command not found那就是 Maven 环境变量没配好它和我们要排查的插件 not found 是两码事先处理环境变量再说。然后检查 IDE 里的 Maven 配置。以 IDEA 为例位置在Settings - Build, Execution, Deployment - Build Tools - Maven三项关键配置Maven home path用的是哪个 Maven默认是 IDEA 自带的 Bundled MavenUser settings file用的是哪个 settings.xml默认是~/.m2/settings.xmlLocal repository本地仓库路径默认是~/.m2/repository。我遇到的第一个坑就是命令行用的 Maven 和 settings 是配置好的但 IDEA 用的是内置 Maven 和默认 settings两边环境完全对不上。所以修好命令行之后IDEA 依旧红字。这时候把 IDEA 里的 Maven home path 指向命令行那个 Mavensettings file 指向同一个文件再刷新红字才消失。3.2 方案A继承 parent 或显式声明版本最常见如果你的 pom 里压根没有继承spring-boot-starter-parent也没有给spring-boot-maven-plugin写版本号那下面的操作直接解决 80% 的问题。手动创建 Maven 工程后自己加 Spring Boot 依赖最容易出现这个情况。pom 可能是这样dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies这里依赖都能拉下来但插件报 not found就是因为 Spring Boot 依赖和插件都需要版本管理。如果你不想继承 starter-parent可以改用spring-boot-dependencies作为 BOM 导入依赖版本插件独立声明版本dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version2.7.18/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId version2.7.18/version /plugin /plugins /build如果你无所谓继承直接用最省事的方式加上 starter-parent 即可parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent用 parent 之后插件节点可以不写版本因为 parent 的pluginManagement已经锁定了版本。但有一个细节需要注意如果项目有多模块父 pom 里已经用了 spring-boot-starter-parent子模块的 pom 通常会继承但如果子模块单独指定了一个 parent就可能在子模块的 pom 里丢了插件版本管理这时单独构建子模块会报 not found需要在子模块里补上插件版本或确认父 pom 的继承关系。我个人建议插件版本尽量显式写出来哪怕继承了 parent。这不仅仅是为了解决 not found更重要的是可读性和可维护性。半年后回来看项目一眼就知道用的哪个 Spring Boot 版本对应的插件升级排查时也省力气。3.3 方案B配置国内镜像并强制刷新依赖pom 没问题的前提下网络是最大嫌疑。由于公共仓库服务器在海外的部分网络环境下直接访问会超时或连接不稳定Maven 下载插件失败就报 not found。国内开发最常用的办法是配置阿里云镜像。编辑settings.xml在mirrors节点下新增mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors关于mirrorOf的取值要特别注意配central表示只拦截中央仓库的请求阿里云镜像会代理中央仓库内容配*表示拦截所有远程仓库请求包括公司私服 Nexus、其他第三方仓库一律走阿里云。如果你公司有自己的私有仓库*很危险等于完全绕过了私服。更稳妥的做法是配成external:*意思是只镜像非本地的外部仓库请求本地内网地址不拦截。如果项目里同时存在多个远程仓库但希望全部走镜像才考虑*。配置完镜像后删除本地仓库里的失败标记并强制更新find ~/.m2/repository/org/springframework/boot/spring-boot-maven-plugin -name *.lastUpdated -delete mvn clean package -U这里-U参数的作用是强制 Maven 检查远程仓库的最新版本和元数据忽略本地缓存对.lastUpdated标记也会重新尝试。实测下来这个组合拳能处理绝大多数因网络导致的插件 not found。还要提一个埋得比较深的坑如果你的 Maven 版本是 3.8.1 及以上默认只允许 HTTPS 访问远程仓库对于 HTTP 地址的仓库会被直接 block。有些老项目或者公司私服地址还是 HTTP镜像配置里如果用http://的地址Maven 会报 blocked 或下载不了表现和 not found 非常接近。阿里云的镜像地址是 HTTPS所以没问题但自建 Nexus 或老镜像源要注意。3.4 方案C私有仓库与离线环境处理如果你在一个公司的内网环境访问不了外网或者公司通过自建 Nexus 代理依赖情况又有不同。先确认是不是走了私服。看一下settings.xml里有没有mirrorOf*/mirrorOf指向 Nexus 的镜像以及mvn help:effective-settings里生效的activeProfiles里有没有配置repositories。如果私服从来没有代理过org.springframework.boot:spring-boot-maven-plugin这个插件就会报 not found虽然你公司别的插件都能正常下载。排查方式是在 Nexus 管理后台看仓库的 proxy 配置确认是否代理了 Maven Central 或阿里云仓库并且检查该组件在私服上能否访问到。更快的验证方式是直接在浏览器访问 Nexus 的仓库 URL 拼接插件路径看能否列出目录http://你的nexus地址/repository/maven-public/org/springframework/boot/spring-boot-maven-plugin/如果这里能访问而 Maven 报 not found那大概率是本地_remote.repositories元数据导致识别问题如果这里都访问不到就是 Nexus 仓库代理没有包含中央仓库或者该组件没有被私服缓存。在 Nexus 侧配置好代理后Maven 重新拉取即可。完全离线的环境则只能手动安装插件到本地仓库。从一台能联网的机器上下载对应版本的spring-boot-maven-plugin的 jar、pom 文件复制到离线机器的本地仓库对应目录下或者使用mvn install:install-file -Dfilespring-boot-maven-plugin-2.7.18.jar \ -DpomFilespring-boot-maven-plugin-2.7.18.pom离线环境下手动安装 jar 和 pom 文件注意版本号和 pom 中的依赖声明要一致否则 Maven 解析插件依赖时还会继续报错。3.5 验证结果命令行和 IDE 都要确认修复之后不要只在 IDEA 里点一下刷新就说好了。先命令行跑一遍mvn clean compile mvn clean package -DskipTests如果这两条命令能正常完成命令行这条路就算通了。然后回到 IDEA在 Maven 工具窗里点刷新按钮Reimport All Maven Projects让 IDE 重新解析。如果 IDEA 还报红检查 3.1 节里说的那三项 Maven 配置把 IDE 和命令行统一到同一套环境基本能解决。这里有一个很实用的确认方式看~/.m2/repository/org/springframework/boot/spring-boot-maven-plugin/目录下是否真的下载到了对应版本的 jar。命令行执行成功之后这个目录下应该有类似spring-boot-maven-plugin-2.7.18.jar spring-boot-maven-plugin-2.7.18.pom文件在、时间戳是新的才说明这次不是“假成功”。4. 常见问题与排查技巧实录4.1 高频问题速查表这个报错我在不同环境、不同项目里踩过很多次把典型的症状和对应的解法整理成了一张速查表方便后面直接对照现象可能原因解决思路刚创建的项目就报 not found网络无法访问远程仓库或未继承 parent 导致缺少版本配镜像 继承 parent / 显式写版本命令行正常IDEA 报红IDEA 用了内置 Maven 和不同的 settings.xml统一 IDEA 与命令行的 Maven home、settings、localRepositoryIDEA 正常命令行报 not found命令行环境的 Maven 配置和 IDEA 不一致比如没有走镜像检查命令行mvn -version的 settings 路径补配置父模块能构建子模块报错子模块没有继承父模块的插件版本管理在子模块 pom 补版本号或修正 parent 关系报错信息提示某个具体版本不存在插件版本号错误或该版本尚未发布到中央仓库核对 Spring Boot 版本和插件的对应关系换一个稳定版本本地仓库目录下只有 .lastUpdated之前下载失败失败标记导致不再尝试删除 .lastUpdated执行mvn -U clean package配了镜像还是拉不下来mirrorOf 配置把仓库拦截到不可用镜像检查 mirrorOf 作用范围改central或external:*私有仓库环境全部公共插件都能下唯独这个不行Nexus 没有代理 Maven Central/阿里云或 proxy 仓库配置有缺失在 Nexus 侧检查代理仓库配置重新拉取打包成功但java -jar提示 no main manifest attributespring-boot-maven-plugin 存在但未绑定 repackage goal在插件节点下配置 executions 添加 repackage goal最后一行提到的 repackage 问题是插件 not found 修复后最常见的“后遗症”。很多人以为插件在 pom 里声明了就算完事但 Spring Boot 可执行 jar 需要repackage这个 goal 在package阶段执行否则生成的是普通 jar启动时会因为没有主清单属性报错。完整的插件配置应该是plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId version2.7.18/version executions execution goals goalrepackage/goal /goals /execution /executions /plugin如果你继承了 starter-parent这个配置也会从 parent 的 pluginManagement 继承并默认执行不需要再写一遍。但显式写出来的好处是当 Classifier、mainClass 等自定义参数出现问题时排查位置更清晰。4.2 修复插件后还要注意什么还有一个容易踩的坑Spring Boot 版本和 Maven 版本的适配。Spring Boot 3.x 系列要求 Maven 3.6.3 以上如果你还在用很老的 Maven 3.2.x插件解析阶段可能直接跳过或者报其他底层错误但表现形式也是 not found。先升级 Maven 到 3.9.x再去排查插件问题能省很多莫名其妙的时间。翻看历史版本时也顺手提醒一句不要盲目把插件版本升到最新。spring-boot-maven-plugin的版本应该和spring-boot-starter-parent、spring-boot-dependencies的版本保持一致。版本错配最典型的问题就是插件下载成功了但在打包时出现各种奇怪的反射错误或链接错误。我在升级 Spring Boot 时曾经把插件留成旧版本结果打出来的 jar 启动时就报类找不到之后才意识到插件和框架版本不一致的问题。关于本地仓库的维护我个人的习惯是遇到依赖相关报错先从报错前最后写入.m2的时间点去想如果是因为某次中断导致优先在对应插件目录下清理.lastUpdated而不是整个仓库rm -rf。整个删掉仓库听起来一了百了但在网络不稳定的环境下重新下载海量依赖反而更容易触发新的问题。精准清理、强制刷新是更高效的方式。5. 写在最后的一点体会回顾这次排查最花时间的不是配置本身而是“到底哪一层出了问题”的判断。pom 配置、远程仓库、本地缓存、IDE 和命令行环境差异每一层都可能把同一个 not found 演出来。我的建议很简单先看 pom 的 effective-pom 确认版本在不在再看本地仓库有没有下载下来的 jar最后才动 settings.xml。顺序反了很容易越改越乱。还有一点是环境统一的问题很多人单独看 IDEA 没问题单独看命令行没问题结果两边各自用的 Maven 和 settings 都不一样一通操作后问题依旧。处理任何构建相关的问题第一步永远是把 IDEA、命令行、本地仓库这三者的配置拉齐先解决“环境分叉”再去追报错本身。这个习惯帮我省下了大量定位时间也希望后面遇到这个问题的人能少走点弯路。
