Spring Boot与Spring Framework版本对应全解析：从1.5到3.5的依赖管理实战

你八成遇到过这种情况项目里 Spring Boot 用的 2.7.18Spring Framework 也按“最新版”习惯性引入了 6.1.x结果一启动就报NoClassDefFoundError或者干脆 Bean 都加载不出来还有人在 pom 里手动把spring-webmvc改成 6.0.x然后整个项目的拦截器、视图解析全部失效排查半天发现是版本依赖关系在作祟。这个标题看起来就是个“官方文档一句话”的事但实际项目里它牵扯出的问题非常多Spring Boot 版本、Spring Framework 版本、JDK 版本、第三方 starter 版本这四层关系只要错一层项目就起不来。这篇我会把 Spring Boot 从 1.5 到 3.5 与 Spring Framework 的版本对应关系完整梳理一遍说清楚为什么不能乱配、怎么查真实生效版本、从 2.x 升级到 3.5.x 到底要改哪些地方最后附上我在真实项目里的排查经验。无论你是新项目选型还是老项目升级这篇都能直接抄作业。1. 一次版本错乱引发的问题现场1.1 你遇到过“找不到 javax.servlet.Filter”吗先讲一个我调试过很多次的现场。某老项目从 Spring Boot 2.3.4 升到 2.7.18基本没动代码但启动时直接报ClassNotFoundException: javax.servlet.Filter。第一反应是没引用 servlet-api于是手动往 pom 里加了javax.servlet-api3.1.0结果更糟项目里所有 Filter、WebMvcConfigurer 相关的类全部加载异常甚至 Spring Security 的链路也断了。实际原因很简单Spring Boot 2.3.4 默认锁定的 Spring Framework 是 5.2.x而 2.7.18 锁定的是 5.3.x。虽然 servlet-api 的主版本变化不大但 Spring 5.3 里对javax.servlet相关类的初始化路径有调整Boot 自己管理的spring-boot-starter-web已经带了匹配版本的 servlet 依赖一但手动覆盖依赖树就乱了。类似的情况在引入非官方 starter 时更容易爆发。这类问题背后本质上就是标题说的那件事Spring Boot 和 Spring Framework 这两个版本号不是独立存在的Boot 在发布时就锁定了 Framework 的版本范围。你手动引入任何 Spring 相关依赖时如果不遵循这个锁定关系项目就会在启动期或运行期莫名其妙地炸掉。1.2 Spring Boot 与 Spring Framework 的版本到底谁说了算很多人会理解为“Spring Boot 是一个工具Spring Framework 是底层框架两者独立升级”。实际不是这样。Spring Boot 的每个版本都会把对应 Spring Framework 的版本写进自身的依赖清单这个清单叫spring-boot-dependencies。你创建项目时引用的spring-boot-starter-parent本质上就是继承了这份 BOM它把spring-core、spring-web、spring-context等所有 Spring Framework 模块的版本全部固定了。这就意味着在标准 Spring Boot 项目里你根本不需要也不应该手动指定任何 Spring Framework 模块的版本号。你只需要在 pom 里声明parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.5.0/version relativePath/ /parent然后引用自己需要的 Spring 模块版本号通通省略。至于每个模块到底用的是哪个 Spring Framework 版本Boot 已经在 BOM 里统一裁决了。如果你在依赖里手动写了 Framework 版本号就相当于越过 BOM 的管理范围直接和 Boot 内部锁定值抢优先级冲突就来了。2. 版本对应关系全景一张表讲清楚所有版本2.1 从 Spring Boot 1.5 到 3.5 的完整对应表下面这张表是目前比较完整的版本对应关系建议收藏。我按 Spring Boot 的各个大版本、常见重要小版本做了整理基本覆盖了官方发布过的对应情况Spring Boot 版本对应 Spring Framework 版本最低 JDK 版本典型场景1.5.x4.3.xJDK 7/8老单体项目基本不推荐新用2.0.x5.0.xJDK 8早期的 WebFlux、响应式支持2.1.x5.1.xJDK 8部分老项目的常见 Baseline2.2.x5.2.xJDK 8老项目中比较常见2.3.x5.2.xJDK 82.x 时代的经典组合2.4.x5.3.xJDK 8开始引入 spring.config.import 等新机制2.5.x5.3.xJDK 8可平滑升级到 2.72.6.x5.3.xJDK 8配置路径匹配策略发生变化2.7.x5.3.xJDK 8/11/172.x 的最终版最推荐停留版本3.0.x6.0.xJDK 17大版本过渡jakarta 迁移元年3.1.x6.0.xJDK 17补充性修复版本3.2.x6.1.xJDK 17稳定性提升明显3.3.x6.1.xJDK 17现在不少新项目的选择3.4.x6.2.xJDK 17支持 REST Client 等新特性3.5.x6.2.xJDK 17当前 3.x 的较新稳定线4.0.x开发中7.0.xJDK 17面向后续 LTS配合新特性演进这张表要纵向看。重点不是每个数字而是三条规则第一Spring Boot 2.x 系列框架版本始终停留在 Spring Framework 5.3.x第二Spring Boot 3.x 系列从 6.0 开始起步后续小版本逐步升到 6.1、6.2第三Spring Boot 3.x 的最低 JDK 是 17这一点直接卡死了一批不想升级 JDK 的老项目。2.2 版本号后面的小版本为何也有讲究只记住“2.7 对应 5.3”还不够。实践中影响项目行为的往往是“小版本细节”。比如 Spring Boot 2.5 和 2.7 都对应 Spring Framework 5.3.x但 Boot 2.5 锁定的可能是 5.3.8Boot 2.7.18 锁定的则是 5.3.31。这两者之间的差异可能就包含了对某些安全漏洞的修复或者某个 MVC 组件的行为修正。这意味着如果你想升级 Spring Framework 来修复某个 CVE最正规的做法不是单独把spring-webmvc修改到最新而是优先把 Spring Boot 升级到包含该修复的补丁版本。手动修改 Framework 版本门牌号往往会让依赖树里出现新老版本并存甚至引发更难排查的BeanDefinitionOverrideException或循环依赖问题。我个人的经验是把 Boot 和 Framework 看作一个整体版本包简化管理的成本远低于手工维护版本号带来的心智负担。3. 搞错版本关系后项目里会发生什么3.1 无法启动NoClassDefFoundError 与 Bean 初始化异常最常见的错误场景就是启动时报类和符号找不到。例如Caused by: java.lang.NoClassDefFoundError: org/springframework/aop/TargetSource at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBean(...)这种报错如果是出现在 Spring Framework 内部类上基本就是依赖树里同时存在多个 Framework 版本。比如你从某个第三方 jar 传递引入了spring-core-5.2.x.jar而 Boot BOM 里默认是 5.3.xClassLoader 加载到旧版本的核心类Spring 内部某些新 API 不存在于是跑着跑着就是各种NoClassDefFoundError。另一种是 Bean 初始化异常比如BeanDefinitionStoreException或BeanCreationException。这类问题多见于 Spring Boot 3.x 项目中某个老版本拦截器或自动配置类还在用javax.annotation包而 Spring Framework 6.0 已经整体切换到jakarta.annotation。代码编译能过但运行时注解找不到对应处理逻辑。碰到这类问题第一件事不是改代码是先查看依赖树确认到底有几个不同版本的 Spring 核心模块在 classpath 里。上面的第 4 节会写具体命令。3.2 行为诡异拦截器失效、事务失效、功能异常比“起不来”更难查的是“能起来但功能不对”。我遇到过一个案例Spring Boot 2.1.6 的项目为了用 Spring 5.3 的新特性手动把spring-webmvc升到了 5.3.20结果项目里自行注册的HandlerInterceptor全部失效登录鉴权形同虚设。后来排查发现WebMvcAutoConfiguration是由 Boot 2.1.6 提供的它内部初始化 MVC 组件的代码是基于 Spring Framework 5.2 的 API 编写的强行走 5.3 的 jar 后部分扩展点初始化顺序变化自定义拦截器就没被注册进去。同理事务失效也经常是版本错配导致。比如Transactional的拦截器 Bean 创建顺序被改变代理模式失效导致数据库操作没有回滚。这种问题你在代码层面怎么查都查不出来因为所有注解、配置都正确。所以版本依赖关系混乱能造成的最大伤害就是隐性故障。系统能跑但行为不再符合预期这是最难排查的一种。3.3 版本升级反复失败springboot从2.x迈向3.5的连锁反应最近因为新项目需要我为一个老项目把 Spring Boot 从 2.7.18 升级到 3.5.x。这个过程中踩的坑基本可以写一本小册子而它本质上还是标题那个问题Boot 版本一变Framework 版本跟着变Framework 一变整个生态里的命名空间、自动配置机制、JDK 要求全都连锁反应。特别是在连接外部中间件时版本对不上的表现会尤其明显。我之前帮人排查过一个项目应用要把数据发给 RocketMQ在 Spring Boot 3.3.x 里直接引了老版rocketmq-spring-boot-starter结果 pom 里出现了一堆javax.jms、javax.validation的旧包项目启动后发现 Producer 可以创建但消息怎么都发不出去。最后统一下掉所有手动指定版本换成兼容 Boot 3.x 的 starter并把 Boot 内部 BOM 管理的依赖全部不加版本号问题才消失。这里我想强调Spring Boot 3 以后几乎所有依赖关系都要重新审视不能直接沿用 2.x 时代的坐标。4. 实操三步理清项目的版本依赖4.1 第一步用 spring-boot-dependencies 作为唯一版本来源新项目最稳妥的做法就是用spring-boot-starter-parent作为 parent。这样你项目的所有 Spring Framework 模块、常用第三方库比如 Jackson、Tomcat、Hibernate Validator版本都交给 BOM 管理。但也有团队不想继承这个 parent比如公司内部已经有统一 parent POM。这种时候不要自己写一堆版本号而是通过 import 方式引入 BOMdependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version3.5.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement这样即便你没有继承 starter-parentSpring 相关依赖依然不加版本号。注意这里spring-boot-dependencies的版本号必须和项目的 Boot 主版本匹配。比如你用 Boot 3.5.0这里就是 3.5.0。如果你用的是 Gradle对应写法是plugins { id org.springframework.boot version 3.5.0 id io.spring.dependency-management version 1.1.7 }然后同样不需要给 Spring 相关依赖写版本号io.spring.dependency-management插件会从 Boot 的 BOM 里读取。4.2 第二步用 mvn dependency:tree 看清真实生效版本配置做得再规范也防不住某些第三方 jar 私下传递依赖。所以排查问题的第二步永远是看真实的依赖树。mvn dependency:tree -Dincludesorg.springframework:*这条命令会列出所有org.springframework组的依赖及其版本号。如果发现同一模块出现了两次且版本不同恭喜你基本锁定问题了。比如[INFO] - org.springframework.boot:spring-boot-starter-web:jar:3.5.0:compile [INFO] | \- org.springframework:spring-webmvc:jar:6.2.0:compile [INFO] \- com.example:custom-lib:jar:1.0.0:compile [INFO] \- org.springframework:spring-webmvc:jar:5.3.31:compile另一个spring-webmvc:5.3.31是被 custom-lib 传递进来的Maven 仲裁默认会采用最近依赖路径优先的规则。如果它离应用更近就会覆盖 Boot 管理的 6.2.0问题随之而来。解决方式是在spring-boot-starter-web或全局 dependencyManagement 里排除掉传递依赖只保留 BOM 里的版本。Gradle 可以用./gradlew dependencyInsight --dependency spring-webmvc能看到具体的依赖来源和版本冲突决策。4.3 第三步第三方组件与 JDK 版本一起纳入管控版本对应关系不止 Boot 与 Framework还包括 JDK 和所有生态组件。Spring Boot 3.x 要求 JDK 17这不算新闻但很多人忽视了“数据库驱动、消息中间件客户端、分布式注册中心客户端”等组件同样有版本对应。以注册 Nacos 为例老版本 Nacos Client 2.2.0 可能只兼容 Spring Cloud Alibaba 2.x 和 Boot 2.7。如果直接放到 Boot 3.5 项目里启动时会报javax.*缺失解决方法是使用对应新版本 Spring Cloud Alibaba 和 Nacos Client因为这些新版本已经整体迁移到jakarta体系。再比如你想在 Boot 3.x 里集成 Activiti/Flowable 这类工作流引擎它们的 starter 也要选兼容 Jakarta 的新版本否则底层数据库操作会频繁报错。我的建议是画一张四列清单项目技术栈、组件名、组件版本、兼容的 Boot 版本。升级前先把这张表过一遍比启动报错后茫然查学校得多。5. Spring Boot 3 迁移实战从 2.7 到 3.5 的关键改动清单5.1 javax 到 jakarta 的命名空间切换如果你正处在“Spring Boot 2.7 升 3.5”的阶段首当其冲的就是命名空间迁移。Spring Framework 6.0 开始Java EE 的各个 API 从javax.*迁移到了jakarta.*。最直观的改变是所有 Servlet、Validation、Persistence、Annotation 相关的包名都要改原 javax 包迁移后的 jakarta 包对应日志内容javax.servlet.*jakarta.servlet.*Filter、Servlet、WebServlet 等javax.validation.*jakarta.validation.*Validator、Valid、Constraint 等javax.persistence.*jakarta.persistence.*Entity、Table、Column 等javax.annotation.*jakarta.annotation.*PostConstruct、PreDestroy、Resource 等你可以全局搜索替换但要注意有些第三方 jar 内部还在用javax.annotation这时候它们的版本必须升级。我之前升级时用过一条辅助命令把编译期报错集中收集起来mvn compile 21 | grep package javax | sort -u这样可以一次性看到所有仍然依赖旧命名空间的代码位置再逐个处理。5.2 spring.factories 失效与自动配置加载机制Spring Boot 3 还有一个大改动自动配置类的注册不再读取META-INF/spring.factories而是改成读取META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。这意味着如果你项目里自己写了 starter 或者依赖了某个没有适配 Boot 3 的第三方 starterConfiguration自动配置类可能不会被加载表现为“明明引入了依赖但功能就是没生效”。排查起来很隐蔽因为编译期不报错运行时也没有明显异常。对于自研 starter要创建这个 imports 文件并在里面写入自动配置类的全限定名。我见过不少项目在 Boot 3 下功能神秘消失最后发现只是少了这个文件。5.3 拦截器、过滤器、序列化等代码层改动要点代码层面Boot 3 和 Framework 6 还改了一些行为WebMvcConfigurer接口自身没有大变但是PathMatchConfigurer的路径匹配策略、ContentNegotiationConfigurer的参数解析有调整。RestTemplate底层默认使用JdkClientHttpRequestFactory还是SimpleClientHttpRequestFactory不同版本行为不一致导致有些请求方法不再允许读取响应体。Jackson 的 Java 8 时间模块在 Boot 3 中默认启用但某些全局序列化配置可能被新版本覆盖LocalDateTime格式化容易失效。CrossOrigin的默认 allowCredentials 策略有变化跨域请求的预检响应头可能不再带上某些自定义头。我升级时遇到最典型的是自定义HandlerInterceptor里拿不到HttpServletResponse的getWriter()因为在 Framework 6 中DispatcherServlet内部对响应的包装顺序更早代码需要在preHandle阶段使用response.getOutputStream()代替。这种细节只有对着版本差异去验证没有捷径。5.4 中间件整合时的版本验证清单进入 Spring Boot 3.x 之后任何第三方中间件的接入我都建议先过一遍这条验证清单组件是否提供官方 Boot 3 版本或者社区公认兼容版本组件 jar 里是否出现spring.factories如果出现确认是否同时存在AutoConfiguration.imports。组件是否依赖javax.*包如果有很可能需要换新版本。组件依赖的 Spring 模块版本和 Boot BOM 是否冲突用dependency:tree验证。组件需要的最低 JDK 版本是否满足项目的运行环境以上清单也适用于消息队列、报表插件、定时任务框架等场景。我当年整合一个报表服务器时就是因为在 Boot 2.7 下一切正常直接平移到 Boot 3.5 后报表导出空白最终定位到是老版本报表插件的动态注册逻辑依赖javax.servlet换用兼容 Jakarta 的新版插件后恢复。6. 常见问题速查与选型建议6.1 常见问题速查表现象常见原因处理方向启动报NoClassDefFoundError: org/springframework/...依赖树中 Spring Framework 多版本并存mvn dependency:tree排查排除旧版本ClassNotFoundException: javax.servlet.FilterBoot 3 项目仍有旧代码依赖 javax全局迁移到 jakarta.servlet自定义拦截器不执行Framework 版本与 Boot 内置 MVC 机制不匹配回归 BOM 统一版本不手动指定自动配置类不生效缺少AutoConfiguration.imports文件创建文件并注册配置类Transactional不回滚事务拦截器加载顺序异常检查 Spring AOP 依赖版本是否与 Boot 匹配序列化格式异常Jackson 模块版本与 Framework 版本不匹配使用 Boot BOM 管理的 Jackson 版本第三组件库报java.lang.UnsupportedClassVersionErrorJDK 版本低于组件要求参考组件官方要求升级 JDK 或换组件版本6.2 版本选型的个人经验在几个升级项目之后我的选型经验可以浓缩成三条第一新项目直接选 Spring Boot 3.3 或 3.5对应 Framework 6.1 或 6.2JDK 直接上 17。低于 3.2 的 Boot 3 版本不建议再用补丁更新少部分安全问题的修复不及时。如果团队不着急追新3.3.x 是目前最稳的折中。第二老项目如果只能留在 2.x那就停在 2.7.18这是官方维护时间最长的 2.x 分支。别再手动升级 Framework 小版本否则很可能从“可控的老项目”变成“不可控的混合版本项目”。第三无论项目处于哪个阶段都要把版本管理写进规范Spring 相关依赖一律不写版本号交给 Boot BOM第三方中间件集成前必须验证兼容性清单升级前先跑一遍依赖树对比。日常维护中我习惯在 CI 脚本里加一个mvn dependency:tree的输出归档每次构建后核对差异比出问题再解决省事得多。这个内容后续还可以扩展的方向是结合 Spring Boot 4.0 和 Spring Framework 7.0 的演进来看模块化与 Native Image 适配不过那又是另一个故事了。先把当前项目的版本关系理清才是解决 90% 启动异常和隐性故障的关键一步。