Spring Boot 4.0 迁移避坑地图：官方 Migration Guide + Jackson 3 踩坑实战全记录-育师

Spring Boot 4.0 迁移避坑地图：官方 Migration Guide + Jackson 3 踩坑实战全记录

Spring Boot 4.0 对国内多数 Java 后端团队来说，最难的不是“要不要升”，而是“升到一半卡住了怎么办”。3.x 到 4.0 并不是把<version>改成4.0.x就能跑起来的小版本升级：官方在 Migration Guide 中把依赖体系重新分层（Production-Ready Modules / IO Modules / Classic Starter POMs）[1][4][5][6]，Jackson 从 2.x 跨到 3.x 带来包名、API 与配置属性的连锁变化 [8][9]，内嵌容器层面 Undertow 的支持状态发生变化 [11]，配置属性还有一份完整的 Configuration Changelog 需要逐条消化 [2]。与此同时，官方版本已推进到 v4.0.6 [7]，国内脚手架芋道 yudao 发布 v2026.06 声明支持 Spring Boot 4.X [13]，RuoYi 生态出现了 ruoyi-boot4 这样的升级分支 [15]——这说明迁移已经从“新闻期”进入“工程落地期”。

本文不讲 4.0 的新特性全景，只解决一件事：升级当天会卡住你的问题。全文按“依赖 → 包名 → 配置 → 容器 → 验证 → 补丁策略”的顺序展开，最后收束成一张可分工、可验收的 Checklist。

需要先说明引用纪律：本文的事实骨架来自 Spring Boot 官方 Wiki 与 Release 页面 [1][2][3][4][5][6][7]，掘金等二手文章 [8][9][10][11][12] 仅作为踩坑线索与排查启发，凡是二手说法与官方文档可能不一致的地方，文中会明确标注“需回官方原文核对”。官方 Wiki 的迁移章节存在多个修订版本页面，落地前请以当前主版本页面为准。

一、这不是新特性盘点，是一张迁移地图

一次典型的升级失败现场通常是这样的：构建能过，启动时报ClassNotFoundException或NoSuchMethodError；或者启动正常，但接口 JSON 的 null 字段、时间格式、枚举序列化结果悄悄变了；又或者application.yml里写了多年的配置项突然不再生效，容器线程池参数没被应用却没有任何报错。这三类现象分别对应三类根因：依赖/包名断裂、配置属性改名、自动配置行为变化。它们的共同点是“编译期看不见”，因此迁移必须按固定顺序做，而不是边改边试。

全文路线如下：

基线确认与风险分级（先判断值不值得现在升、风险在哪）；
依赖地图（Production-Ready Modules / IO Modules / Classic Starter POMs）[4][5][6]；
Jackson 2.x → 3.x 深水区（包名、API、配置属性）[8][9]；
Undertow 弃用后的内嵌容器选型 [11]；
Configuration Changelog 的批量消化方法 [2]；
国内脚手架升级案例观察（yudao v2026.06、ruoyi-boot4）[13][15]；
4.0.5 / 4.0.6 补丁期的升级决策 [7][12]；
可执行 Checklist 收束。

如果你的项目是纯 CRUD 单体、没有自定义 Starter、没有手写ObjectMapper，可以重点读第二、四、八节，第三节快速浏览即可；如果你有自定义序列化、多协议网关或自研 Starter，第三节必须逐句读。

二、升级前置：基线确认与风险分级

2.1 运行基线：JDK、构建工具与兼容边界

Spring Boot 4.0 与 Spring Framework 7 同步演进，JDK 基线与构建工具版本要求都比 3.x 更高。具体最低版本请以官方 Spring Boot 4.0 Release Notes 为准 [3]，不要凭 3.x 的经验推断。从国内实践看，芋道 yudao-cloud 的 v2026.06 发行版标签明确标注jdk17/21[13]，说明主流脚手架把 JDK 17 与 21 作为实际验证组合；如果你的生产环境仍停留在 JDK 8 或 11，需要先把 JDK 升级单独作为一个项目排期，不要和 Spring Boot 4.0 迁移捆在同一个变更窗口里，否则一旦出问题无法判断是 JDK 兼容性还是框架迁移引起的。

构建工具侧同样要先升级：Maven 需确认maven-compiler-plugin、spring-boot-maven-plugin、BOM 导入方式（spring-boot-dependencies）与 4.0 兼容；Gradle 需确认 Gradle 版本与org.springframework.boot插件版本匹配，Wrapper 一并提交，避免“我本地能构建、CI 构建失败”。

2.2 三类项目的风险分级

项目类型	典型特征	最大风险点	建议策略
纯 CRUD 单体	依赖 starter 齐全、无自定义序列化、单数据源	配置属性改名导致静默失效	直接升，配一轮接口契约回归即可
深度定制型	自定义 Starter、手写`ObjectMapper`、Actuator 扩展、多序列化协议	Jackson 3 包名与扩展点变更、自动配置条件变化	先做依赖树 diff 与序列化契约测试，分批迁移
脚手架二开型	基于 yudao / RuoYi 大量二次开发	脚手架升级 diff 与本地定制冲突	先跟进脚手架官方升级分支，再把定制层重放

这张表的意义在于：三类项目的工作量差异不在“改多少行代码”，而在“需要多少验证证据”。纯 CRUD 项目可以用接口 diff 兜底，深度定制项目必须补序列化契约测试，脚手架二开项目则必须先解决“升级分支怎么合”的流程问题。

2.3 迁移前的“安全网”

动手之前先留下可比对的基线：

# Maven：保存依赖树快照，迁移后做 diffmvn-Bdependency:tree-Dverbose>deps-before.txt# Gradle：等价操作gradle dependencies--configurationruntimeClasspath>deps-before.txt# 锁定当前可运行版本，便于回滚gitswitch-cmigration/spring-boot-4gittag pre-sb4-baseline

同时确认三件事：CI 全量回归在当前版本是绿的（否则迁移后无法归因）；数据库迁移脚本与框架升级解耦；回滚路径经过一次真实演练（不是理论上“改回版本号就行”）。依赖树快照是最容易被忽略但回报最高的动作——Jackson、Tomcat、Spring Security 的传递依赖冲突，九成以上能在依赖树 diff 里提前看到。

三、依赖地图：Production-Ready Modules / IO Modules / Classic Starter POMs

3.1 为什么 4.0 要重组模块

官方 Migration Guide 把依赖变化拆成几个专题页面：Production-Ready Modules、IO Modules、Classic Starter POMs [4][5][6]。这种拆分的工程含义是：4.0 不再把“能启动”和“生产可用”混在同一个依赖层次里，团队需要明确自己引入的是哪一层能力。对迁移者来说，最重要的不是记住每一个坐标，而是建立一个判断顺序：我的应用当前依赖了哪些能力 → 这些能力在 4.0 属于哪一层 → 我该换成新坐标、换 Classic Starter，还是拆掉不用。

3.2 Classic Starter POMs 的定位

Classic Starter POMs 的官方描述包含 “If you’re upgrading an existing application and just want to get running quickly, you can use Classic Starter POMs” 的表述 [5]。这句话的语境是明确的：它面向“存量应用想快速跑起来”的过渡场景。落地建议是两阶段走——第一阶段用 Classic Starter 让应用先跑起来、拿到可对比的行为基线；第二阶段再逐个换成 4.0 推荐的模块坐标，完成依赖瘦身。长期停留在 Classic Starter 上，等于把迁移债留到下一次升级。Classic Starter 的完整清单以官方页面为准 [5]，本文不复述可能过期的条目。

3.3 GAV 坐标变更：做一张自己的对照表

由于模块重组，pom.xml/build.gradle里的坐标变化是迁移第一步。正确做法不是照抄别人的清单，而是用依赖树 diff 自动生成：

# 迁移后再次保存依赖树mvn-Bdependency:tree-Dverbose>deps-after.txt# 对比差异，重点看 groupId/artifactId 变化与版本冲突标记diff-udeps-before.txt deps-after.txt>deps.diffgrep-E'^\+|^\-'deps.diff|grep-E'jackson|spring-boot-starter|undertow|tomcat|jetty'

把输出整理成一张工作表，字段建议为：旧坐标、新坐标、所属模块层（Production-Ready / IO / Classic）、是否传递引入、迁移动作（替换/删除/保留/待核对）、验证方式。社区对 4.0 与 3.5.x 的包依赖变化已有专门梳理 [10]，可作为对照参考，但最终以依赖树实测和官方页面为准。

3.4 传递依赖的连锁反应

Spring Boot 4.0 会带动 Spring Framework、Spring Security 以及 Jackson、Hibernate Validator、Micrometer 等三方库的版本联动。迁移中最典型的三类连锁反应：

传递引入的老版本库被新模块排除后暴露：例如某些库仍然传递依赖 Jackson 2.x，与 3.x 并存导致运行期类冲突；
API 删除导致编译失败：3.x 中标记@Deprecated的 API 在 4.0 被移除，常见于 Actuator 扩展、自定义 Starter 的自动配置类；
版本仲裁结果变化：BOM 管理的版本号变了，原本“碰巧能跑”的三方库组合失效。

排查命令组合建议固化到 CI：

mvn-Bdependency:tree-Dincludes=com.fasterxml.jackson.core,tools.jackson* mvn-Bdependency:tree-Dincludes=io.undertow,org.apache.tomcat,org.eclipse.jetty

只要第一条命令同时出现 Jackson 2.x 与 3.x 坐标，就先解决依赖冲突再谈代码迁移；只要第二条命令同时出现两种容器实现，就要确认到底是哪一种真正生效。

四、Jackson 2.x → 3.x：不止换包名

Jackson 3 是本次迁移最容易“编译过了运行还炸”的部分。社区两篇实战记录分别从自动配置源码与踩坑角度做了拆解 [8][9]，综合来看，变化集中在三层。

4.1 三层变化模型

层次	典型表现	典型故障
包名与模块坐标	`com.fasterxml.jackson.*`系列包名与 Maven 坐标整体迁移到 Jackson 3 的新命名空间（以 Jackson 官方 3.x 文档与 Spring Boot Migration Guide 为准 [1]）	`ClassNotFoundException`、`NoClassDefFoundError`
API 与扩展点	核心入口类、Builder 风格与自动配置的扩展接口发生变化（社区文章记录到`JsonMapper`相关调用顺序变化 [8]）	`NoSuchMethodError`、自定义配置不生效
配置属性	`spring.jackson.*`属性按 Configuration Changelog 逐条调整 [2]	静默失效：字段命名、null 处理、时间格式悄悄变化

这里必须强调一个纪律：Jackson 3 的精确包名前缀、模块 artifactId、注解包归属，以及spring.jackson.*的具体改名条目，请在迁移时打开官方文档逐条核对[1][2]。二手文章 [8][9] 可以告诉你“哪里容易炸”，但不能作为坐标表的唯一依据。实际操作中，用下面的方法自己生成清单最可靠。

4.2 全局替换与隐蔽点排查

先做显性引用扫描：

# 1. 找出所有直接 import Jackson 2.x 的源文件grep-RIn--include='*.java''com\.fasterxml\.jackson'src/>jackson-imports.txt# 2. 找出以字符串形式硬编码的类名（反射、SPI、注解属性）grep-RIn--include='*.java'--include='*.yml'--include='*.properties'\'"com\.fasterxml\.jackson'src/ main/ config/2>/dev/null# 3. 找出手工构造 Mapper / 注册 Module 的位置grep-RIn--include='*.java'-E'new ObjectMapper|ObjectMapper\(|registerModule|Jackson2ObjectMapperBuilder'src/

显性 import 可以靠 IDE 批量重构，隐蔽点才是真正的坑：

@JsonTypeInfo(use = ..., property = ...)中引用的类型别名或类名字符串；
SPI 注册文件META-INF/services/...中的实现类全限定名；
Redis、消息队列、RPC 框架中手写的序列化工具类（它们往往绕过 Spring 自动配置，直接 new Mapper）；
测试代码里的 JSON 断言工具与TypeReference泛型解析处；
前后端共享的 JSON 契约文档生成插件。

“编译过了运行还炸”的根源通常就在这里：显性引用改完了，但 SPI 文件、字符串类名、三方框架内部的 Jackson 2 依赖还在，运行期类加载器把两个命名空间的类混在一起。

4.3 配置属性迁移

spring.jackson.*是配置改名的重灾区。执行顺序建议：

打开 Spring Boot 4.0 Configuration Changelog [2]，筛出spring.jackson前缀的条目，按“新增 / 重命名 / 废弃 / 移除”分类；
在项目中反向检索旧属性名（含.yml、.properties、环境变量形式SPRING_JACKSON_...、JVM 参数形式）；
每改一条，立刻用一个最小 JSON 序列化测试验证行为是否等价——重命名不等于语义不变，部分属性可能伴随默认值或行为调整，Changelog 条目的备注需要逐条读。

检索示例：

# yml / properties 中的显式配置grep-RIn--include='*.yml'--include='*.yaml'--include='*.properties'\-E'spring\.jackson|SPRING_JACKSON|jackson:'.# 常见以环境变量注入的形态grep-RIn-E'SPRING_JACKSON_[A-Z_]+'.--exclude-dir=.git

自定义扩展点同样要复查：3.x 中常见的Jackson2ObjectMapperBuilderCustomizer一类扩展接口，在 4.0 / Jackson 3 体系下是否有对应替代、注册顺序是否变化，需对照 Migration Guide 与自动配置源码确认 [1][8]。如果你的项目把自定义序列化逻辑写在多个模块里，建议先做一个“序列化行为基线包”：对 20～50 个代表性 DTO 在旧版本下生成 JSON 快照，迁移后逐个比对，字段名、null、时间格式、枚举形态、多态类型标识全部纳入断言。这是唯一能兜住“静默变化”的手段。

4.4 故障排查树

启动/运行报错 ├── ClassNotFoundException / NoClassDefFoundError │ ├── 类名属于 Jackson 2.x 包前缀 → 依赖里还有老库或源码未替换 │ └── 类名属于三方框架内部引用 → 该框架版本不兼容 Jackson 3，查其官方文档或升级版本 ├── NoSuchMethodError / AbstractMethodError │ ├── 出现在自定义序列化代码 → 扩展点 API 变化，对照 Migration Guide 重写 │ └── 出现在三方框架 → 2.x/3.x 类混载，用 dependency:tree 定位冲突源 └── 接口 JSON 静默变化 ├── 字段命名变化 → property naming 配置项改名/默认值变化 [2] ├── null 消失或出现 → 序列化包含策略配置变化 [2] └── 时间格式变化 → 时间模块与格式化配置变化 [2]

五、Undertow 弃用之后：内嵌容器怎么选

5.1 先把“弃用”说准确

中文社区出现了“Spring Boot 4.0 官宣弃用 Undertow”的报道 [11]，但迁移决策必须建立在精确措辞上：需要回到官方 Migration Guide 与 Release Notes 确认弃用的确切范围[1][3]——是 Undertow 相关 Starter 被弃用、自动配置被弃用，还是内嵌场景的整条支持链路被弃用？外置容器部署（WAR 到独立安装的 Undertow）是否受影响？官方是否给出移除时间表与推荐替代品？这几个问题的答案决定了你的迁移是“改依赖”还是“改架构”。

可以确定的工程结论是：不要在未核实范围的情况下假设“Undertow 项目本身已死”或“4.0 立即不能用”。弃用（deprecation）与移除（removal）之间通常存在过渡期，但过渡期长度必须以官方说明为准。

5.2 三个候选的实际取舍

方案	适用场景	主要收益	主要代价
Tomcat（默认）	大多数单体 Web 应用、运维体系围绕 Tomcat	默认支持最完整、资料与监控探针最成熟	需迁移 Undertow 专属配置
Jetty	团队已有 Jetty 运维经验、特定协议或嵌入式场景	生态成熟、可作为中性替代	部分自动配置行为需单独验证
外置容器 / WAR	受合规约束必须统一管理容器版本	容器与应用解耦、便于统一安全补丁	失去内嵌容器的部署简洁性，构建方式要改

选型判断依据建议按这个顺序：现有运维体系（谁打安全补丁、谁监控线程池）→ 协议与代理需求（HTTP/2、WebSocket、AJP）→ 团队熟悉度 → 最后才是性能对比。本文不给出性能结论：没有在你自己的流量模型、JDK 版本、容器版本下压测过的数字，都不构成选型依据。

5.3 迁移动作与复查点

依赖侧的切换（示意，具体坐标以官方文档为准 [1][4]）：

<!-- 迁移前：显式使用 Undertow --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-undertow</artifactId></dependency><!-- 迁移后：回归默认 Tomcat 或显式 Jetty --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>

配置侧复查清单（逐项对照 Configuration Changelog [2]）：

线程池相关：worker 线程数、最大连接数、请求队列长度；
连接器相关：超时、最大 HTTP 头大小、压缩、SSL/HTTP2 开关；
WebSocket 相关：握手超时、消息缓冲、代理转发头处理；
部署相关：context path、访问日志、优雅停机（graceful shutdown）；
可观测性：健康检查探针、线程池指标名是否会因容器更换而变化，监控告警规则同步调整。

5.4 留在 Undertow 的过渡方案

如果短期无法切换，做法是：把“Undertow 替换”登记为显式技术债，写清楚触发条件（官方公布移除版本、出现必须依赖的容器级修复、或补丁版本停止覆盖）；同时冻结 Undertow 专属配置的新增使用，避免技术债继续扩大。这样即使未来需要一次性切换，配置面也是收敛的。过渡期的长短以官方路线为准 [1][3]，不要按传闻排期。

六、把 Configuration Changelog 变成自动化检查

6.1 怎么读 Changelog

Spring Boot 4.0 Configuration Changelog [2] 的条目可以按四类处理，优先级从高到低：

移除（Removed）：必须改，通常是启动报错或静默失效；
重命名（Renamed）：必须改，且要验证行为等价；
废弃（Deprecated）：本次不改也要记账，下个版本会变成“移除”；
新增（New）：通常不阻塞迁移，但可能提供更合适的默认行为。

建议把 Changelog 导出成一张工作表：条目原文、旧属性、新属性、是否影响我的项目、扫描正则、验证方式、负责人。迁移验收的依据就是这张表的“全部关闭”。

6.2 自动化扫描

# 通用扫描：按 Changelog 中确认的旧属性名批量检索grep-RIn--include='*.yml'--include='*.yaml'--include='*.properties'\-E'旧属性名A|旧属性名B|旧属性名C'.# 启动期发现未绑定/不再生效的配置（4.0 的具体告警机制与开关名称# 请以官方文档核实 [2][3]，不要照抄旧版本参数）java-jarapp.jar--debug

更稳妥的做法是在集成测试里启动一个最小上下文，用ApplicationContext的环境断言关键属性是否真正绑定到期望的配置类上，而不是仅检查 YAML 语法正确。配置“写对了但没生效”是迁移中最隐蔽的一类问题。

工作表模板如下，可直接复制到团队 Wiki：

Changelog 条目	旧写法	新写法	扫描正则	是否命中	验证方式	状态
示例行（需替换为 [2] 中的实际条目）	—	—	`spring\.xxx\.yyy`	否	启动断言 + 接口快照	待办

七、国内脚手架升级案例观察

7.1 yudao v2026.06

芋道源码 yudao-cloud 的 v2026.06 发行版说明中，可直接验证的信息包括：版本标签标注jdk17/21，发行说明声明正式发布 Spring Boot 4.X 支持，并同时覆盖单体与微服务两种形态 [13]；配套的 yudao-ui-admin-vue3 也发布了 v2026.06 [14]。这些信息足以给出两个判断：一是国内主流脚手架已经把 Spring Boot 4.X 视为可发布状态，二是其验证基线以 JDK 17/21 组合为主，与前文的 JDK 升级建议一致。

至于它内部改了哪些依赖、踩了哪些坑，在没有公开说明的情况下本文不做推断。对二开团队真正有用的，是拿到它的升级提交 diff：git log --oneline v旧版..v2026.06 -- pom.xml能看到依赖变更的集中提交，git diff v旧版..v2026.06 -- '**/pom.xml'能直接生成你的 GAV 对照表素材。

7.2 ruoyi-boot4

ruoyi-boot4 的仓库定位是基于 RuoYi 前后端不分离版本升级到 Spring Boot 4 [15]。它对二开团队的价值在于提供了一个“最小改造面”的样本：一个经典的前后端不分离项目要升到 4.0，需要动多少地方。评估这类升级分支时，重点看三件事：基于哪个 RuoYi 版本（决定 diff 范围）、README 中的完成度声明与已知未完成项、升级提交是否把“依赖升级”与“业务改动”分开（混在一起的提交无法安全复用）。

7.3 可复用的两类动作

脚手架维护者视角：先依赖后代码，先单模块后全家桶。推荐顺序是先让framework/common这类基础模块编译通过，再逐个打通system、infra、业务模块；Jackson 与容器切换放在依赖稳定之后，避免多类问题纠缠。

二开团队视角：用分支 diff 法跟升级——

拉取脚手架官方升级分支，与自己二次开发的基线做三方对比；
把脚手架的升级提交按“依赖 / 配置 / 代码 / 资源”分类；
依赖与配置类改动直接采纳，代码类改动逐个人工合并，避免覆盖本地定制；
合并后重放本地定制层的自动化测试；
把本次无法合并的差异登记为清单，而不是留在分支里。

八、4.0.5 / 4.0.6 补丁期升级建议

官方已发布 v4.0.6 [7]，中文社区也对 4.0.5 的修复内容做了报道，并提示 WebSocket 用户需关注 [12]。这里同样遵循核实纪律：具体修复条目请以官方 release notes 原文为准[7]，二手报道中的“9 个 Bug 修复”等表述不应直接写入升级工单。本文给出的是决策框架，不是修复项清单。

8.1 三类团队的时机建议

团队状态	建议	理由
还没升 4.0	不追首发，直接以 4.0.x 最新补丁版本为目标基线	4.0.0–4.0.5 期间的修复已被吸收，减少踩已修问题的概率 [7]
已在 4.0.0–4.0.4	尽快滚动到 4.0.6，并优先回归补丁涉及的组件	补丁版本回归面小、收益确定
使用 WebSocket 或其他高风险组件	优先升级并专项回归握手、消息、代理链路	二手报道提示 WebSocket 相关修复值得关注 [12]，需以官方条目核实影响面

8.2 补丁升级的标准动作

版本管理建议写死补丁版本，而不是开放区间：

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><!-- 固定版本，避免区间解析导致 CI 与生产不一致 --><version>4.0.6</version></parent>

不建议使用[4.0.6,)这类版本区间：区间会让不同时间构建出的产物不一致，破坏可复现构建，也让你无法明确回答“生产上跑的到底是哪个版本”。补丁跟进应通过定期升级工单完成，而不是让解析器自动漂移。

升级动作清单：发布说明逐条比对与自身组件的交集 → 回归受影响链路 → 灰度范围至少覆盖一个真实流量实例 → 监控核心指标（错误率、P99、线程池、GC）→ 保留上一版本镜像与回滚脚本，并演练一次回滚。

九、可执行迁移 Checklist

阶段 0：基线与安全网

确认 JDK、Maven/Gradle、构建插件版本满足 4.0 要求（核对 [3]）；
保存dependency:tree/gradle dependencies快照并入库；
确认当前版本 CI 全量回归为绿，回滚分支与镜像已演练。

阶段 1：依赖与 GAV

通读 Migration Guide 三个子章节 [4][5][6]，确定 Classic Starter 是否仅作过渡；
生成迁移前后依赖树 diff，标注坐标变化与冲突；
清除 Jackson 2.x 与 3.x 并存、双容器并存问题。

阶段 2：Jackson 3

全局替换显式 import 与手工构造 Mapper 的代码；
排查 SPI 文件、字符串类名、注解属性等隐蔽引用；
逐条迁移spring.jackson.*配置并验证行为等价 [2]；
用 JSON 快照/契约测试覆盖代表性 DTO（字段名、null、时间、枚举、多态）。

阶段 3：容器选型与配置复查

确认官方弃用的确切范围与时间表 [1][3]；
选定 Tomcat / Jetty / 外置容器，替换依赖；
迁移线程池、连接器、WebSocket、优雅停机配置；
同步监控指标名与告警规则。

阶段 4：Configuration Changelog 全量扫描

按移除/重命名/废弃/新增分类建立工作表 [2]；
用 grep/IDE 全局检索清理旧属性名（含环境变量形态）；
用最小上下文断言关键属性确实绑定生效。

阶段 5：验证

启动无异常、无未绑定配置告警；
核心链路回归通过，接口 JSON diff 通过；
序列化契约测试通过；
监控、健康检查、日志探针正常。

阶段 6：补丁跟进

固定到 4.0.x 具体补丁版本（如 4.0.6 [7]）；
订阅官方 release notes，按组件交集排期；
补丁升级执行灰度 + 回滚演练。

结语

Spring Boot 4.0 迁移的确定性来自官方文档：模块怎么拆看 Migration Guide [1][4][5][6]，配置怎么改看 Configuration Changelog [2]，补丁修了什么看 release notes [7]。二手踩坑文章 [8][9][10][11][12] 的价值是帮你预判“哪里会炸”，而不是替你决定“改成什么”。迁移的稳定性则来自你自己的回归证据——依赖树 diff、JSON 契约测试、灰度与回滚演练，这四样东西凑齐，4.0 就是一次可控的常规升级，而不是一次赌博。

参考资料

Spring Boot 4.0 Migration Guide，Spring Projects Wiki，GitHub：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
Spring Boot 4.0 Configuration Changelog，Spring Projects Wiki，GitHub：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Configuration-Changelog
Spring Boot 4.0 Release Notes，Spring Projects Wiki，GitHub：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes
Spring Boot 4.0 Migration Guide - Production-Ready Modules，Spring Projects Wiki，GitHub：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide/cecfa6ae99b823a42f2cc295a9c906d0a8ce5f5b
Spring Boot 4.0 Migration Guide - Classic Starter POMs，Spring Projects Wiki，GitHub：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide/024089cc7424e49ad4960099e9971162dd12e181
Spring Boot 4.0 Migration Guide - IO Modules，Spring Projects Wiki，GitHub：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide/025b06d78c82ee7f98850cfb1c4fd3d11c78deac
Release v4.0.6 · spring-projects/spring-boot，GitHub：https://github.com/spring-projects/spring-boot/releases/tag/v4.0.6
Spring Boot 4 拥抱 Jackson 3：包名迁移、配置改名与自动配置源码剖析，掘金：https://juejin.cn/post/7671812766157914152
Spring Boot 4 实战：Jackson 2.x 升级到 3.x 踩坑全记录，掘金：https://juejin.cn/post/7633826322738511898
spring-boot 4 相比 3.5.x 的包依赖变化，掘金：https://juejin.cn/post/7579190764766036008
Spring Boot 4.0 官宣：弃用 Undertow，掘金：https://juejin.cn/post/7568755613875322880
Spring Boot 4.0.5 发布：9 个 Bug 修复，WebSocket 用户需关注，掘金：https://juejin.cn/post/7621405268673871914
yudao-cloud v2026.06(jdk17/21)：正式发布 Spring Boot 4.X 支持单体、微服务，Gitee 发行版：https://gitee.com/zhijiantianya/yudao-cloud/releases/tag/v2026.06(jdk17/21)
yudao-ui-admin-vue3 v2026.06 发行版，Gitee：https://gitee.com/yudaocode/yudao-ui-admin-vue3/releases/tag/v2026.06
Jay/ruoyi-boot4：基于 RuoYi 前后端不分离版本升级到 Spring Boot 4，Gitee：https://gitee.com/Jay_JN/ruoyi-boot4
Migrate to Spring Boot 4.0 · Issue #947 · ktenman/portfolio，GitHub：https://github.com/ktenman/portfolio/issues/947

说明：以上二手来源（第 8–12 条）未提供可核验的发布日期与阅读数据，文中仅将其作为踩坑线索与社区观察使用；涉及 Jackson 3 精确包名/坐标、spring.jackson.*具体改名条目、Undertow 弃用范围、4.0.5/4.0.6 修复项逐条内容的最终判断，请以官方文档页面（第 1–7 条）当前版本原文为准。