Spring Boot 4.0 正式发布的消息刚出来的时候，我朋友圈一片哀嚎。倒不是大家不期待新版本，而是这个版本的“硬”变化实在太多：基线直接压在 Java 17+ 上，整个 Jakarta EE 命名空间换血，自动配置机制也做了大范围调整。对于维护过老项目的团队来说，“人已麻”三个字太真实了——这意味着几乎每个模块都要重新过一遍编译、测试、替换依赖，连多年没动过的启动类都可能要改。
但麻归麻，事情还是得干。这篇文章我不打算复读官方 Release Notes，而是从一个普通后端开发者的视角，把 Spring Boot 4.0 里最关键的几个变化、升级前的准备工作、实际操作中的改造点、以及我见过的各种坑整理出来，给你一份可以直接照着做的参考。无论你是打算把老项目从 2.x/3.x 迁过来，还是新项目直接上 4.0，这篇文章都能帮你少走弯路。
1. 先说清楚 4.0 到底动了哪些“地基”
1.1 Java 17 与 Jakarta EE 的版本墙
Spring Boot 4.0 最让人“麻”的第一件事，就是它的运行环境基线变成了 Java 17。注意，这不是说“推荐用 Java 17”，而是说“用低于 17 的 JDK 你连启动都启动不了”。如果你现在还在生产环境跑 Java 8 或者 Java 11，那么这个版本对你来说不是“升级”，而是一次底层运行时的大换血。
与 Java 版本同步提升的还有 Jakarta EE。Spring Boot 3.x 虽然已经切换到 Jakarta 命名空间，但 4.0 更进一步，把整套规范基线推到了 Jakarta EE 11。这意味着javax.*到jakarta.*的迁移不再是“偶尔遇到一个包名需要改”，而是所有涉及 Servlet、Persistence、Validation、Annotation 的代码都必须彻底转向 Jakarta 命名空间。很多老项目里自研的公共组件、工具类、拦截器，只要用的是javax.servlet、javax.persistence这一套，这次全部要重命名。
| 关键项 | Spring Boot 3.x | Spring Boot 4.0 |
|---|---|---|
| 最低 JDK | Java 17 | Java 17+（推荐 21 或 25 LTS） |
| Jakarta EE | 9/10 | 11 |
| 基础框架 | Spring Framework 6.x | Spring Framework 7.x |
| 命名空间 | javax 已基本退出 | jakarta 全面接管 |
| 自动配置 | 条件装配 + 配置属性 | 模块化重组 + 新的装配机制 |
1.2 自动配置机制的重构方向
用过 Spring Boot 的人都知道，自动配置是它的灵魂。以前我们引入一个 Redis、一个 Kafka，只要在pom.xml里加依赖，再写几行application.yml，很多东西就能直接跑起来。这是靠@EnableAutoConfiguration和spring.factories/AutoConfiguration.imports一套机制搞定的。
Spring Boot 4.0 对这套机制做了进一步模块化。最明显的变化是自动配置类的粒度变得更细、条件装配逻辑更严格，官方对“什么时候该加载这个配置”做了更明确的约束。换句话说，以前那种“我加个依赖它就把配置全部帮我弄好”的情况变少了，有些配置项不再无脑默认开启，你必须显式声明意图。
这对老项目的影响非常大。最常见的情况是：升级到 4.0 之后，某个 Bean 突然找不到了，某个配置项不生效了，但日志里又没有报错。这种“静默失效”是最折磨人的，因为它不像编译错误那样直接告诉你哪行写错了。解决这类问题的思路，就是去理解自动配置的触发条件，而不是继续把它当黑盒。
1.3 依赖管理与版本号的跳变动线
Spring Boot 4.0 带来的另一个“麻点”是版本号体系的变动。3.x 时代大家已经习惯了3.0.x、3.1.x、3.2.x这样的小步快跑节奏，但 4.0 直接跳到了一个大的主版本上。这意味着很多第三方依赖的兼容版本也发生了偏移。
举个例子：以前你在 Spring Boot 3.2 里用的某个第三方库版本，到了 4.0 环境下可能不再被官方 BOM 管理。这时候你自己就要手动指定版本号，并确认它跟 Spring Framework 7.x 的 API 是兼容的。尤其是一些跟 Spring 生命周期耦合比较深的库，比如安全框架、服务发现客户端、消息中间件客户端，它们的适配往往要晚于 Spring Boot 主版本发布一段时间。如果你追求“一发布就升级”，你可能会发现自己被卡在某个依赖的兼容性上。
1.4 对现有项目的影响半径评估
在动手升级之前，先要搞清楚“哪些地方一定会改、哪些地方可能改、哪些地方大概率不用动”。根据我多年折腾框架升级的经验，影响半径通常这么划分：
一定会改的地方：
- 启动类上的注解和包名引用（如果用了 Jakarta 相关注解）
- 所有
javax.*开头的 import - 内置服务器、连接池、JSON 序列化等基础组件的版本配置
- 与安全认证相关的配置项（如果用了统一的 Security 配置）
可能会改的地方：
- 自定义的自动配置类和条件注解
- 配置文件里被移除或重命名的配置项
- 第三方组件的 API 调用方式（例如某些客户端库的构建器变化）
大概率不用动的地方：
- 基于 JPA 的实体类写法（只要不涉及包名变化）
- 业务层的 Service / Controller 基础代码
- 纯 DTO、工具类、基础 POJO
我的建议是：升级之前花半天时间，用 IDE 全局搜索javax.和已废弃的spring.配置项，把它们做成一张清单，逐项评估优先级。这一步看起来简单，却能省下后面大量的排查时间。
2. 升级前的全面体检与清单准备
2.1 基线体检：JDK 版本、构建工具、容器运行时
如果你决定要升级到 Spring Boot 4.0，第一步不是改pom.xml，而是先检查你的整个运行环境链。只改代码不换环境，等于给 Plane 换引擎却忘了检查跑道。
先看 JDK。开发机、CI 机器、生产镜像里的 JDK 版本必须统一到 17 以上。如果公司内部还有老项目跑在 Java 8 上，那你还要考虑同一台部署机上多个 JDK 共存的问题。我的习惯是在Dockerfile和 CI 配置里直接把基础镜像的 Java 版本锁死，避免“本地能跑、服务器上跑不起来”的经典悲剧。
再看构建工具。Maven 用户建议升级到 3.9+，Gradle 用户建议升级到 8.x 或更高。Spring Boot 4.0 的插件对老版本构建工具兼容性有限，有时候一个诡异的构建失败，追根到底就是构建工具版本太老。
最后看容器运行时。如果项目是部署在传统 Servlet 容器里的，请把 Tomcat/Jetty 等容器的版本也纳入检查范围。Spring Boot 4.0 默认内嵌的容器版本已经更新，如果你用的是外置容器部署war包，容器版本太低会直接导致 Servlet 规范不匹配。
2.2 依赖树审视和多余模块清理
Spring Boot 升级不像普通依赖升级，它不是“改一个版本号就能完事”的。很多问题的根源在于依赖之间的传递关系发生了变化。这时候，mvn dependency:tree就是你最好的朋友。
我在实际操作中会分成三步来走：
- 升级前先跑一次
mvn dependency:tree，把当前依赖树完整导出来保存一份。 - 升级到 4.0 后再跑一次，对比两棵树的差异。
- 重点看哪些依赖被移除了、哪些被隐式引入了、哪些版本发生了冲突。
这个对比过程能发现很多“莫名其妙”的问题。比如，你从某个依赖里传递引入的旧版 Jackson，可能会覆盖 Spring Boot 4.0 默认管理的 Jackson 版本，导致序列化行为变化。这种情况下你需要在pom.xml里显式声明正确的版本，把传递依赖的版本“压”下去。
另外，Spring Boot 4.0 对一些软件包换了管理方式，比如某些 starter 被拆分或合并。如果你引用了老版本里已经不存在或已合并的 starter，编译时可能不会报错，但运行时某些功能就是起不来。这个时候去看依赖树，通常一眼就能发现问题在哪儿。
2.3 废弃 API 的“滚雪球”清理
长期维护的项目里，废弃 API 是滚雪球一样的存在。你今天用的WebMvcConfigurerAdapter，明天用的RestTemplate，后天用的某个xxTemplate，都是在不同版本里被标记过废弃的。平时用着不碍事，但大版本升级的时候，这些废弃 API 往往会被直接移除，或者行为发生破坏性变化。
Spring Boot 4.0 对废弃 API 的处理比 3.x 更激进。3.x 时代给你留了缓冲期，打出deprecated警告还可以继续跑；4.0 里很多直接就不给你留了。升级时编译报错，你能看到一堆“cannot find symbol”的提示，而这些符号大概率都是你拖了很久没清理的废弃方法。
我的建议是：升级前在项目里全局搜索@Deprecated相关依赖项，把你自己代码里用到的地方先做一轮替换。比如RestTemplate换成RestClient，各种自定义WebMvcConfigurer的旧写法换成新函数式风格。这个工作很琐碎，但它能避免你升级后面对几百个编译错误无从下手。
2.4 测试策略和灰度发布
很多人升级框架时只关注能不能编译、能不能启动，却忽略了一个更重要的环节：测试。Spring Boot 4.0 底层变化太大，编译通过和启动成功只能说明“基础没塌”，不能说明业务逻辑都正常。
我比较推荐的策略是“新旧并行 + 灰度流量验证”。在升级过程中保留一个旧版本的完整部署环境，新版本环境先接入测试流量和灰度流量，跑一段时间的自动化测试和线上镜像流量后，再逐步切真实用户。这比“一个晚上升级完、第二天线上出问题”要稳妥得多。
测试用例本身也要调整。@SpringBootTest这类集成测试在 4.0 里的启动行为可能会有变化，尤其是涉及到嵌入式服务器和测试容器的场景。建议先只跑核心的单元测试和少量冒烟测试，等稳定后再放全量回归。不要指望一把梭。
3. 升级实操：关键改造点与踩坑实录
3.1 依赖与构建配置的改动思路
到了实际操作阶段，最先动手的就是pom.xml。如果你是从 Spring Boot 3.x 升级，改动相对温和一点；如果你还在 2.x，那就不是“升级”，而是“迁移”了。我们先说大多数团队会面对的场景：从 3.x 升级到 4.0。
最核心的改动是替换父 POM 版本。把spring-boot-starter-parent的版本从3.x.x改成4.0.x，然后重新导入依赖。这一步会在 IDEA 或 IDE 里触发大规模的依赖解析变化，第一次跑可能非常慢，而且极大概率会遇到某个依赖下载失败或冲突。别急，这是正常的。
我给一个很笨但很有效的做法：升级时不要一次性把所有依赖都改成最新版，只改必要的。先把 Spring Boot 主版本号升上去，其他第三方依赖先保持不变，直到编译报错时再去逐个调整。这样做的好处是，你能明确知道到底是哪个依赖的问题，而不是一堆问题混在一起无从下手。
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>4.0.x</version> <relativePath/> </parent>注意4.0.x里具体用哪个次版本，要看你们团队的节奏。通常我建议等.1或.2出来之后再升级主版本，因为.0版本多多少少会有一些底层依赖的适配问题。如果你追求稳定，可以参考开源社区里各个框架的兼容矩阵再做决定。
3.2 自动配置迁移的常见形态
升级后最容易出问题的，就是自定义自动配置。很多中大型项目都有自己封装的xxx-starter，内部用AutoConfiguration.imports注册配置类。Spring Boot 4.0 对这批文件的处理逻辑虽然有兼容，但加载顺序和条件判断语义可能发生变化。
我自己遇到最典型的情况是：某个自定义 starter 里的@ConditionalOnMissingBean突然失效了。以前只要容器里没有同类 Bean，就自动装配一个默认实现；升级之后，默认实现竟然和用户显式声明的 Bean 同时存在，导致行为混乱。
排查到最后，发现是自动配置类的加载顺序变了，本来应该先加载用户定义的 Bean，结果现在自动配置类先跑了。解决方案是在自定义 starter 里显式声明@AutoConfigureOrder和@AutoConfigureAfter，把加载顺序固定下来。这个小细节在之前的版本里一般不用管，但 4.0 的语义更严格，你必须把“顺序”当作一等公民来对待。
另外，配置属性的绑定方式也值得注意。4.0 里@ConfigurationProperties对构造方法绑定和校验的默认策略有调整。以前你可能只写了 setter 让它慢慢绑，现在有些场景要求更明确的绑定方式。建议升级后跑一遍所有“配置项加载”相关的测试，确认每个配置组都能正确映射。
3.3 可观测性端点的适配
Spring Boot 3.x 引进了 Micrometer Tracing 等一套可观测体系。4.0 在这块继续做“加法”，默认暴露的端点更多，指标更细，但与此同时，你之前自定义的一些按management.*开头的配置项可能会失效。
这会让运维和开发都很麻，因为监控数据一旦对不上，线上出了问题你根本没法快速定位。我的经验是：升级后先检查/actuator/health、/actuator/metrics这组基础端点是否正常响应，再看自定义的指标是否还能上报到监控系统。如果发现指标不齐，优先查management.endpoints.web.exposure配置是否被新版的默认值覆盖。
还有一点，4.0 对 OpenTelemetry 的支持更深入了。如果你之前是自建了一套 trace 上报逻辑，现在要考虑是不是应该直接切到标准化的 OTel SDK 上。这看起来是额外工作，但长期来看能减少很多重复轮子。
3.4 从 2.x 直接跳跃到 4.0 的特殊风险
如果你还在 2.x，想着“一步到位直接升到 4.0”，我的建议非常明确：不要这么做。2.x 到 4.0 的区别就像是旧的木质帆船直接换成现代驱逐舰，中间隔着 3.x 这个完整的过渡期，跳过的不仅仅是版本号，还有大量的语义变化。
非要硬上的话，你面对的将是：
javax到jakarta的全量包名替换，涉及面极广- Security 配置 DSL 结构完全不同
- 很多配置属性的 key 彻底消失或改名
- 测试体系和 mocking 机制的默认行为变化
- 第三方依赖的兼容版本几乎全部需要重新评估
一次性承受这么多变化，即使是经验丰富的开发者也很难在短时间内稳定交付，更何况大多数团队没有那么多精力专门做这种大迁移。所以如果你在 2.x，规划时一定要分阶段：先升 3.x，跑稳了之后，再考虑 4.0。
4. 常见问题速查与排查技巧
4.1 一启动就报 NoClassDefFoundError
升级后启动应用，最经典的问题就是各种NoClassDefFoundError和ClassNotFoundException。这个错误本身就是一句话：你的运行时 classpath 里缺了某个类。
但为什么明明依赖都加进去了，还是会缺类呢？直接去找依赖树。八成是某个第三方依赖把传递依赖“甩”了，导致你原来靠它传递引入的类现在没有了。另外也要检查是不是有多个版本的 jar 包冲突，类加载器加载的是旧版本，而旧版本里没有新代码里需要的新类。
我的习惯是用 dependency 插件打印冲突项，然后在pom.xml中显式排除不需要的传递依赖。有些时候你还需要用mvn dependency:analyze来分析哪些依赖是声明了但没用、哪些是用了但没声明。这个工具在升级场景下特别好用，能自动帮你找出潜在的问题。
4.2 配置项失效与迁移属性
另一个高频问题是：项目能启动，但某些配置项明显不生效。比如日志级别没变化、连接池参数没变化、缓存策略没变化。出现这种情况，多半是配置项的 key 在 4.0 里被改名了。
Spring Boot 官方文档里有一份配置属性迁移对照表。从 3.x 到 4.0，有几个常见的改动方向：
server.*相关端口和连接配置整体梳理，部分并发参数改名spring.datasource.*里连接池专属参数被拆分到各自的池子配置下management.*下的暴露策略默认值调整spring.redis.*与新的客户端适配器参数整合
遇到配置不生效，我的做法是先用启动日志里的“配置报告”功能，看看哪些属性被实际绑定到了哪些 Bean 上。Spring Boot 4.0 对配置绑定的可观测性做得更好，你可以通过 Actuator 的configprops端点直接查看每个配置属性当前的真实值。这个比翻文档猜 key 要高效得多。
4.3 测试容器与虚拟线程的兼容
Spring Boot 4.0 对虚拟线程的支持进一步完善，很多项目开始用虚拟线程来处理高并发请求。但虚拟线程有一个新的问题：它跟某些测试容器框架的兼容性并不完美。比如一些基于传统线程局部变量设计的测试工具，在虚拟线程环境下会出现不可预期的行为。
我的建议是：如果项目里用了虚拟线程，升级后的集成测试一定要在真实环境下跑一遍，不要只依赖spring.test提供的 mock 功能。重点观察线程相关的隔离性，特别是数据库事务和缓存上下文的传播机制。如果出现“这个测试单独跑能过、全部跑就挂”的现象，大概率跟测试线程模型有关。
4.4 性能回归排查
每次大版本升级，性能和资源占用都是玄学般的领域。Spring Boot 4.0 因为引入了更多模块化和防御性逻辑，在少数场景下启动时间和内存占用会比 3.x 略高。如果你升级后发现生产环境的响应变慢了，先不要慌，按下面几步去排查：
- 先对比启动时间。用
-Xlog:class+load或者 Actuator 里的启动指标看类加载数量。 - 再看 GC 日志。JDK 17+ 的 G1 参数和旧版本可能有差异。
- 确认自动配置是否加载了多余的组件，比如你连 Redis 都不用，结果因为某个 starter 引入了 Redis 自动配置。
- 最后压测对比，看是不是某个默认线程池参数变了。
性能问题有一点很关键：不要凭感觉猜测，一定要有前后对比数据。升级之前就把旧版本的接口响应时间和 CPU 内存指标记录下来，升级后做同场景对比，哪差补哪，否则很可能是白忙一场。
这里也补充一个我实际遇到过的案例：某公司在升级后用 JFR 抓取生产样本，发现大部分耗时都集中在日志框架的异步队列上。查了半天不好定位，最后发现是配置项改名后，原来的日志队列容量设置没有从旧 key 迁移过来，导致默认容量太小、频繁触发丢弃策略。这是那种“不看到配置报告根本想不到”的问题。
4.5 典型案例复盘：一个跨平台系统模拟迁移过程
前面讲了很多零散的点，最后我用一个模拟项目 X（一个典型的跨平台系统）的迁移过程来串一下整体思路。
这个模拟项目的核心技术栈是：Spring Boot 3.2 + Java 17 + MyBatis + Redis + Kafka + Spring Security。升级目标：Spring Boot 4.0。
我们按顺序做了这么几步：
- 全局搜索
javax.，把所有实体、接口、工具类里的老包名全部替换成jakarta.。这一步其实还好，IDE 的全局替换能加速完成。 - 升级
pom.xml中的父版本号，然后跑mvn compile。第一轮报错主要集中在 Security 配置和自定义 starter 的自动配置上。 - Security 配置改动最费时间。4.0 对 Security 过滤器链的行为做了调整，以前通过继承适配器写的一堆方法现在要改成组件式写法，整个过程相当于重写了一遍安全配置。
- 自定义 starter 里的自动配置类加载顺序出了问题，通过加
@AutoConfigureAfter解决。 - 测试阶段发现 Kafka 消费者线程模型和虚拟线程环境有冲突，通过限定部分线程剥离策略解决。
- 灰度验证一周后，全量切换。
这个过程中前后用了大约两周，其中实际编码不超过三天，剩余时间全在测试和灰度验证上。所以，给所有想升级的团队一个忠告：升级 Spring Boot 主版本，主要工作量不在写代码，而在验证。把时间预算留足，不要用一个周末去赌“应该没问题的吧”。
5. 关于 4.0 的一些个人体感
说回标题。“人已麻”这个情绪我很能理解，但作为过来人，我想说句实在话：每次 Spring 大版本升级都会引发一次技术圈的情绪波动，但你回头看历史，Spring Boot 1.x 到 2.x、2.x 到 3.x，哪次不是一开始满屏吐槽，几个月后大家该用还是用？技术演进的方向不会因为“麻”而回头。
Spring Boot 4.0 的核心方向其实非常明确：拥抱新 Java、强化可观测性、推进模块化。对老项目来说，它确实带来迁移成本；对新项目来说，它提供了更清晰的工程基线。所以我的建议是：不要急着在生产环境上 4.0，但也不要完全无视它。先用一个非核心服务做技术验证，跑通以后，把这个版本真正吃透，再逐步推广到全团队。
最后分享一个对所有人都有用的小技巧：升级前先在本地开一个空白的 Spring Boot 4.0 项目，把你们项目里的核心依赖一个一个加进去。每加一个就启动一次，看到底是哪个依赖引发问题。这种方法比直接在老项目上动手“一刀切”要可控得多，尤其是当你的项目里有一堆乱七八糟的历史依赖时，它能帮你快速定位“麻”的源头，把不可控的升级变成一步步可验证的渐进过程。
