Spring Boot与Spring Framework版本对应关系全解析：从BOM到依赖冲突排查

如果是个Java后端开发者日常基本离不开SpringBoot。但有个看起来很小、实际很坑的问题很多人工作三五年也没真正搞清楚Spring Boot版本和Spring Framework版本之间到底是怎么对应的我见过太多因为版本依赖关系没弄明白而引发的线上事故有的是NoSuchMethodError有的是莫名其妙的Bean类型转换异常还有的是项目启动直接失败。排查到最后往往发现就是pom.xml里Spring Framework的版本被手动覆盖了或者某个库传递依赖了一个不兼容的Spring Framework版本。前两天项目组有个同事在升级内部库时顺手把spring-webmvc的版本在pom.xml里手动指定成了6.1.0。他本意是想解决老版本的一个bug结果启动时报了一堆BeanDefinitionStoreException最后根因是项目本身用的Spring Boot 3.1.x对应Spring Framework 6.0.x而他手动引入的spring-webmvc 6.1.0直接拉高了Spring Framework版本导致部分自动配置项内部API签名不匹配。排查这个问题花了整整大半天。这篇文章我就把Spring Boot和Spring Framework的版本依赖关系彻底讲清楚附上从1.x到4.x的完整版本对照表并给出项目中的查看、排查与升级实操方法帮你把这些坑全部填上。1. 版本依赖关系的本质Spring Boot为什么“管着”Spring Framework1.1 两个框架的职能划分先搞明白很多刚接触Spring生态的开发者会对“Spring Boot”和“Spring Framework”的关系感到模糊。简单说Spring Framework是整个Spring生态的地基IoC容器、AOP、事务管理、MVC、WebFlux这些核心能力全都是它在提供。而Spring Boot是这个地基之上搭的一套整装方案——它用自动配置AutoConfiguration、starter依赖管理、内嵌服务器、外部化配置这些手段把Spring Framework的复杂度封装起来让你可以快速起步。当你启动一个Spring Boot项目时底层真正干活的还是Spring Framework。ApplicationContext是Spring Framework的BeanFactory是Spring Framework的Configuration和Bean的处理逻辑也是Spring Framework的。Spring Boot做的是基于这些底层能力自动配置出一堆Bean让你少写样板代码。这就带来一个必然结论Spring Boot和Spring Framework之间存在严格的版本对应关系。Boot的自动配置代码内部依赖了特定版本的Framework API如果Framework版本比Boot预期的旧某些类或方法找不到直接NoClassDefFoundError如果比预期的新又可能遇到方法签名变更或行为变化。1.2 BOM机制版本依赖关系的“总开关”Spring Boot管理Spring Framework版本的关键机制是BOMBill of Materials。Spring Boot项目发布时会同时发布一个名为spring-boot-dependencies的POM里面通过dependencyManagement把所有常用第三方依赖的版本号统一声明了一遍其中就包括Spring Framework的各个模块。Spring Boot的官方spring-boot-starter-parent在内部也引用了spring-boot-dependencies所以你创建项目时如果继承了spring-boot-starter-parent就有了整个依赖版本矩阵的管理能力。这也是为什么你在写Spring MVC项目时只需要引入spring-boot-starter-web这一个starter不需要管spring-webmvc到底是什么版本因为Boot已经通过BOM锁定了。用我习惯的类比来解释Spring Framework是电脑的CPUSpring Boot是整套预装好的主机。CPU型号变了主板的BIOS、内存、显卡驱动都可能要跟着调。BOM就是这张“硬件兼容性清单”——它把所有配件的型号统一列好确保你能开机。1.3 从starter-parent到spring-boot-dependencies的两层结构实际项目中很多团队对这两种方式的使用场景分不太清。spring-boot-starter-parent是继承式的。你需要在pom.xml的parent节点里指定然后你的项目就自动继承了它的dependencyManagement、pluginManagement和一系列默认配置。spring-boot-dependencies是导入式的。如果你的公司内部已经有统一的父POM不能直接继承Boot的parent那就需要在dependencyManagement里用scopeimport/scope的方式把spring-boot-dependencies导入进来。这两种方式在版本管理逻辑上没有本质区别核心目的都是让Spring Framework的版本跟着Boot走。但要注意如果用的是import方式你需要在dependencies里显式声明Spring Framework模块并省略version标签版本号由BOM提供。这里有个细节很多人会在父POM里把spring-boot-dependencies导入后又在子模块中手动指定spring-core或spring-webmvc的版本。这是破坏版本管理最直接的方式因为子模块中的显式版本会覆盖BOM里的版本管理约束。2. 完整版本对照表Spring Boot 1.x到4.x一次看全2.1 历史版本Spring Boot 1.x和2.x的对应关系Spring Boot 1.x和2.x虽然已经逐步退出主流但很多老项目还在运行。了解这些对应关系对维护遗留系统很有帮助。Spring Boot版本Spring Framework版本1.0.x4.0.x1.1.x4.0.x1.2.x4.1.x1.3.x4.2.x1.4.x4.3.x1.5.x4.3.x2.0.x5.0.x2.1.x5.1.x2.2.x5.2.x2.3.x5.2.x2.4.x5.3.x2.5.x5.3.x2.6.x5.3.x2.7.x5.3.x看这个表格会发现一个有意思的规律Spring Boot的主版本号推进不一定代表Spring Framework的主版本号也同步变。比如Spring Boot从2.2升到2.3对应的Spring Framework版本都是5.2.x从2.4升级到2.7则一路停留在5.3.x。原因很简单Spring Boot的小版本会自动跟随Spring Framework的补丁版本更新但不轻易跨大版本因为跨大版本带来的不兼容风险比较大。2.2 当前主流Spring Boot 3.x的对应关系Spring Boot 3.x是当前Java后端项目的主流选择。它基于Spring Framework 6.x构建底层有两大关键变化一个是Java 17成为基线另一个是javax.*命名空间全面迁移到jakarta.*。Spring Boot版本Spring Framework版本3.0.x6.0.x3.1.x6.0.x3.2.x6.1.x3.3.x6.1.x3.4.x6.2.x3.5.x6.2.x可以看出Spring Boot 3.0和3.1都对应Spring Framework 6.0.x3.2和3.3对应Spring Framework 6.1.x3.4和3.5对应Spring Framework 6.2.x。实际开发中如果项目使用的Spring Boot是3.1而你看到有的jar包传递依赖了Spring Framework 6.1.x就要警惕兼容性问题了。2.3 如何确认官方精确的版本对应关系大版本对照只是基础实际开发中更常需要的是精确到补丁版本的对应关系。比如Spring Boot 2.7.18具体依赖Spring Framework 5.3.31而不是笼统的5.3.x。有几种可靠途径可以确认访问Spring官方文档每个版本的release notes里会列出当前版本依赖的Spring Framework版本号。查看Maven中央仓库在Maven Central上找到spring-boot-dependencies对应版本的POM文件搜索spring-framework.version属性这个值就是精确的Spring Framework版本号。本地查看依赖树直接在项目里执行mvn dependency:tree查看实际生效的版本。其中查POM的spring-framework.version属性是最准确的官方信息源因为spring-boot-dependencies里所有Spring Framework模块的版本都由这个属性统一控制。3. 实操一步步查看项目当前的版本依赖3.1 Maven项目dependency:tree的正确用法在Maven项目里查看依赖树是最直接的手段。基础命令是mvn dependency:tree这个命令会输出整个项目的依赖树信息量非常大。想看Spring Framework相关依赖时可以用-Dincludes参数过滤mvn dependency:tree -Dincludesorg.springframework输出结果大致如下[INFO] - org.springframework.boot:spring-boot-starter-web:jar:3.1.5:compile [INFO] | - org.springframework:spring-web:jar:6.0.13:compile [INFO] | - org.springframework:spring-webmvc:jar:6.0.13:compile这里显示的6.0.13就是Spring Framework的实际版本。如果同一个依赖在多个节点出现且版本号不同就说明存在依赖冲突。再看一个更麻烦的场景你的项目里引入了第三方库some-lib这个库内部又依赖了spring-context 5.3.x而项目本身是Spring Boot 3.x对应的Spring Framework 6.x。此时依赖树中会出现两个不同版本的spring-contextMaven默认会选最近的版本但两台包合并后仍可能引发问题。使用mvn dependency:tree -Dverbose可以将依赖的冲突原因、被覆盖前的版本都展示出来排查时很有用。3.2 Gradle项目dependencies任务Gradle项目的查看方式类似命令为./gradlew dependencies --configuration runtimeClasspath如果想过滤Spring Framework部分可以配合grep./gradlew dependencies --configuration runtimeClasspath | grep org.springframeworkGradle的依赖树输出中-符号表示版本被解析/覆盖到了某个特定版本。比如org.springframework:spring-core:5.3.20 - 6.0.13表示项目原本需要5.3.20但最终被解析为6.0.13这就是版本冲突的表现之一。3.3 IDEA图形化查看IDEA是很多Java开发者的主力IDE。查看依赖关系时有几种图形化手段打开Maven工具窗口右侧Maven面板找到项目的Dependencies节点可以看到所有直接依赖和传递依赖。但IDEA默认展示方式粒度较粗建议使用Maven面板工具栏中的Show Dependencies按钮会生成一张可视化的依赖关系图。在Show Dependencies窗口中可以搜索spring-web直接定位它在依赖树中的位置和实际版本号。IDEA还会用不同颜色标识依赖冲突。对于Gradle项目IDEA的Gradle面板中同样有类似功能。展开App - Tasks - dependencies或直接打开build.gradle后右键Gradle - Refresh也能在External Libraries里查看实际解析的版本。3.4 通过spring-boot-dependencies的POM确认版本如果项目用的是spring-boot-starter-parent那么在本地Maven仓库里一定能找到对应版本的spring-boot-dependenciesPOM文件。路径大致为~/.m2/repository/org/springframework/boot/spring-boot-dependencies/3.1.5/spring-boot-dependencies-3.1.5.pom打开这个POM找到properties段里面有一个spring-framework.version属性properties spring-framework.version6.0.13/spring-framework.version /properties这个值就是该Spring Boot版本默认管理下的Spring Framework版本。同理spring-boot-starter-parent的POM中也存在同样的属性。这个方法最权威因为它直接告诉你Spring Boot官方“设计时”的版本匹配关系完全不依赖项目里实际依赖的状态。4. 版本管理常见问题与排查实战4.1 手动覆盖Spring Framework版本是最常见的坑很多开发者不清楚版本管理的原理习惯在pom.xml里顺手加一个spring.version属性来控制Spring Framework版本。这是最典型的错误做法。Spring Boot的spring-boot-dependencies里定义了两层控制一是dependencyManagement中的spring-framework.version属性二是对Spring各模块版本号的统一管理。你手动定义一个属性或显式指定version标签就等于绕过版本管理直接打破了Boot与Framework的匹配关系。我曾经处理过一个案例项目用的是Spring Boot 2.7.6但某次排查问题时开发者手动添加了spring-context 5.3.28的依赖想修复一个CVE。看似合理结果项目里还有一个库依赖spring-tx而spring-tx的版本还是5.2.x。Spring Framework内部模块之间对版本一致性有强要求版本不一致时会出现各种BeanPostProcessor初始化异常、NoSuchMethodError。正确做法如果确实想修复CVE或使用新版Spring Framework特性应该整体升级Spring Boot的补丁版本而不是单独修改某个模块的版本。比如Spring Boot 2.7.6升级到2.7.18同时Spring Framework也会从5.3.26升到5.3.31一切都会自动协调好。4.2 多个库传递依赖冲突的识别“传递依赖冲突”是排查版本问题时最头疼的。常见场景是项目引入了两个库A和BA依赖了Spring Framework 5.3.xB依赖了Spring Framework 6.0.x最终解析结果取决于Maven的“最近优先”策略——谁的依赖路径更短就选谁。这种情况最容易在Spring Boot 2.x升级3.x时出现。第三方库还没适配jarkata命名空间仍然绑定着Spring Framework 5.3.x而项目已经升级到Boot 3.x对应的Spring Framework 6.x。依赖树里会出现两个版本的spring-beans、spring-context最终加载出来的类可能一半是5.x的一半是6.x的运行时报错千奇百怪。排查手段主要是dependency:tree加-Dverbosemvn dependency:tree -Dverbose -Dincludesorg.springframework:spring-beans输出中会看到类似[INFO] - org.springframework:spring-beans:jar:5.3.31:compile [INFO] | \- (org.springframework:spring-beans:jar:6.0.13:compile - omitted for conflict)不同版本中Maven最终选用了5.3.31而6.0.13被忽略但存在。如果项目需要6.0.13的能力就需要排除掉引入5.3.31的那个旧库或者升级那个库到兼容版本。4.3 三种典型报错与解决思路Spring Framework版本不兼容导致的问题通常表现为以下三种报错报错类型常见触发场景处理思路NoClassDefFoundError某个类在新版本中不存在或依赖的jar包缺失检查依赖树确认该类的来源排除冲突依赖NoSuchMethodError编译期存在运行时版本过旧方法签名不匹配升级Spring Framework版本确保与Boot匹配BeanCreationException自动配置加载时内部逻辑出错多为版本属性缺失查看启动日志的Caused by定位到具体自动配置类看到NoSuchMethodError优先想到“版本太低”看到NoClassDefFoundError优先想到“jar包缺失或版本太高”这是基本的排查直觉。启动时出现BeanCreationException要往下翻日志找Caused by:。比如三段式异常中最后一行往往是一个ClassNotFoundException下面又跟着一个IllegalArgumentException说找不到某个BeanDefinition。这时就要看这个Class属于哪个jar然后用mvn dependency:tree -Dincludes定位这个jar从哪条路径引进来。4.4 处理依赖冲突的实用经验先看属性再改依赖排查时先去spring-boot-dependencies的POM确认当前Boot版本对应的Spring Framework版本再决定如何调整依赖。能用exclusions就用exclusions如果一个第三方库传递依赖了不兼容的Spring Framework版本优先在声明这个库时用exclusions排除掉而不是在项目里新增一个高版本的Spring Framework模块来“覆盖”。后者容易引入不可控的冲突。升级第三方库优于排除依赖排除依赖是表面的解法治标不治本。更好的方案是升级到适配新版本Spring Framework的第三方库版本。很多知名库在Spring Boot 3发布后很快就出了适配版本。善用dependencyManagement锁定全局版本在项目根POM的dependencyManagement中显式锁定关键模块如spring-core、spring-web、spring-beans的版本确保所有子模块或子项目解析到一致版本。但版本号要严格与当前Boot版本对应的Framework版本一致。5. 升级Spring Boot版本的正确打开方式5.1 小版本升级优先看release notes很多开发者升级Spring Boot时习惯直接在pom里改版本号然后跑一遍测试就完事。这样也确实能通过但风险在于版本升级过程中发生的“隐藏行为变化”。Spring Boot的release notes中会列出依赖更新、自动配置变化、默认设置调整等细节这些信息对排查升级后出现的诡异问题非常关键。比如Spring Boot 2.4.0开始spring.factories中的自动配置条目被逐步废弃到2.7版本引入了AutoConfiguration.imports文件。如果你的项目里使用了一些低版本的第三方starter没有适配这个机制升级到2.7后自动配置可能悄无声息地失效。小版本升级建议按这个顺序来先读release notes里的“Dependency Upgrades”和“Deprecations”部分再在测试环境里部署重点回归核心链路。升级后第一时间执行mvn dependency:tree查看Spring Framework版本是否同步更新。5.2 跨大版本升级从Spring Boot 2.x到3.x的迁移要点Spring Boot 2.x升级到3.x是很多团队这两年的重点项目。这不仅是版本号的跳动而是一次全栈迁移最大的变化集中在三块。第一是Java版本基线。Spring Boot 3.x要求Java 17而很多2.x项目当时还跑在Java 8或Java 11上。升级Boot 3.x前需要先把运行环境和CI流水线的Java版本拉起来。这一步往往牵一发动全身涉及JDK版本、构建工具、部署脚本、线上服务器环境要提前评估成本。第二是javax.*到jakarta.*的包名迁移。Spring Framework 6.x全面切换到Jakarta EE 9命名空间所有使用javax.servlet、javax.persistence、javax.validation的代码都要改成jakarta前缀。IDE的全局替换可以快速完成但要注意javax.xml.bind、javax.transaction这些涉及API标准变化的包替换后还需要关注行为差异。第三是自动配置注册机制的改变。Spring Boot 2.7中开始应用的AutoConfiguration.imports机制在3.x中已经完全取代spring.factories。如果项目里自定义了一些自动配置类或者依赖了老版本的starter在Spring Boot 3.x中可能不会被自动加载。检查方法是看启动日志中的“AutoConfigurationReport”部分确认自定的配置类是否生效。5.3 面向Spring Boot 4.x的准备建议Spring Boot 4.0在2025年11月正式发布基于Spring Framework 7.0构建。作为一个从长期维护角度的建议如果你的项目还停留在Spring Boot 2.x尽快启动到3.x的升级才是正确策略——因为跨过2.x直接跳到4.x中间要处理的坑会成倍增加。如果已经在3.x则可以等到4.0的第一个补丁版本发布后再评估升级。Spring Boot 4.x目前可以预期的方向是更激进的现代Java特性支持、Spring Framework 7.0带来的架构级更新。但从版本管理的角度看原理没有变始终以Spring Boot的BOM为准让Spring Framework版本跟着Boot走不要手动插入和Boot版本不匹配的Framework模块。5.4 升级后的回归验证清单升级完Spring Boot后不能只跑单测就收工。我的习惯是准备一份简短但有分量的验证清单项目能正常启动Spring容器初始化时没有异常堆栈。核心接口的请求能正常返回预期的响应码与数据。日志中不出现WARN级别的“deprecated method called”或“class not found”提示。数据库连接、Redis、消息队列等中间件都能正常读写。如果用了定时任务、异步线程池、事件监听确认这些机制在升级后依然正常工作。在升级后的前一两周内密切关注线上错误日志和监控告警因为版本升级后的一些“慢变量”问题——比如内存泄漏、线程池行为变化、连接池超时——往往不会在测试环境中暴露只会在生产流量下逐渐显现。写在最后的一点个人建议接触过这么多项目我最大的感受是版本依赖关系不是“要不要懂”的问题而是“什么时候踩坑”的问题。我见过太多同行在处理Spring Framework版本问题时第一反应是搜一个最新版本号贴进pom里而不是去看项目当前Spring Boot版本应该匹配哪个版本。结果就是问题越修越多最后不得不回滚版本。如果你不想成为那种排查一整天还被同事质疑“你是不是改了依赖”的倒霉蛋最简单的习惯就是改任何依赖之前先跑一下mvn dependency:tree确认你将要改的东西在不在BOM管理之下升级Spring Boot时不要只改版本号把release notes翻一遍把spring-boot-dependencies里的spring-framework.version看一眼遇到版本相关报错第一反应是“当前Boot版本和当前Framework版本是否匹配”而不是“要不要排除一下某个依赖”。最后分享一个能救命的排查小技巧遇到版本冲突但查不出源头时在pom.xml里临时把某个模块用mvn dependency:tree -Dverbose单独排查看它最终走了哪条依赖路径。很多时候你以为的“初代版本”其实不是导致冲突的那个版本真正的问题在一条深层的传递依赖里。找到了就直接用exclusions排除它比在项目里手动添加版本覆盖要稳得多。