前言
Spring Boot 3.x 是 Spring 生态的重大版本迭代，最低要求 JDK 17，全面拥抱 Jakarta EE 9+（替换原 Java EE）、支持原生镜像、性能大幅优化，且 Spring Boot 2.7 已停止官方维护。本指南从环境准备、依赖升级、代码适配、测试验证、问题排查全流程，手把手完成升级，零门槛落地。
升级核心目标：
- JDK 8 → OpenJDK 17（LTS 长期支持版）
- Spring Boot 2.7.x → Spring Boot 3.4.13（最新稳定版）
- 适配 Jakarta EE、移除废弃 API、兼容新特性
一、升级前核心前置知识
- 版本强制要求
- Spring Boot 3.0+ 最低 JDK 17，不支持 JDK 8/11
- Spring Framework 6.x 配套 Spring Boot 3.x，替换
javax.包为jakarta.包
- 兼容性风险点
- 第三方依赖（MyBatis、Druid、Swagger、FastJSON 等）需升级适配 3.x
- 代码中
javax.servlet/javax.persistence等包全量替换 - JDK 9+ 模块化特性、内部 API 封闭可能导致兼容性问题
- 升级顺序
环境准备 → 项目配置升级 → 包名替换 → 代码/依赖适配 → 测试验证 → 上线
二、OpenJDK 17 下载与安装（官方推荐）
2.1 为什么选择 OpenJDK 17？
- JDK 17 是 LTS 长期支持版，稳定且免费商用
- Spring Boot 3.4.13 官方推荐 JDK 17+
- 相比 Oracle JDK，OpenJDK 无版权风险
2.2 各系统 OpenJDK 17 下载地址
| 操作系统 | 下载链接 | 说明 |
|---|---|---|
| Windows | OpenJDK 17 Windows 安装版 | 推荐 MSI 一键安装 |
| macOS | OpenJDK 17 macOS 版 | 支持 Intel/M 芯片 |
| Linux | OpenJDK 17 Linux 版 | 通用 tar.gz 包 |
2.3 安装与环境配置
Windows 系统
- 下载 MSI 安装包，双击运行，默认路径安装即可
- 配置环境变量：
- 新建
JAVA_HOME：C:\Program Files\Java\jdk-17.x.x - 编辑
Path：添加%JAVA_HOME%\bin
- 新建
- 验证安装：打开 CMD 输入
输出java -version javac -versionopenjdk version "17.x.x"即成功
macOS 系统
- 下载 DMG 包，拖拽安装到
/Library/Java/JavaVirtualMachines/ - 终端配置环境变量：
# 编辑配置文件 vim ~/.zshrc # 添加配置 export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home export PATH=$JAVA_HOME/bin:$PATH # 生效配置 source ~/.zshrc - 验证：
java -version
Linux 系统
- 下载 tar.gz 包，解压到
/usr/local/tar -zxvf openjdk-17_linux-x64_bin.tar.gz -C /usr/local/ - 配置环境变量：
vim /etc/profile # 末尾添加 export JAVA_HOME=/usr/local/jdk-17 export PATH=$JAVA_HOME/bin:$PATH # 生效 source /etc/profile - 验证：
java -version
三、Maven/Gradle 升级（必须）
- Maven：最低 3.8.6+，推荐 3.9.6
下载：Maven 3.9.6 - Gradle：最低 7.5+，推荐 8.x
- 验证版本：
mvn -v gradle -v
四、Spring Boot 项目核心配置升级
4.1 父工程版本修改（Maven）
打开项目 pom.xml，核心修改 1：
<!-- 原 2.7.x -->
<!-- <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.7.18</version><relativePath/>
</parent> --><!-- 新 3.4.13 -->
<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.4.13</version><relativePath/>
</parent>
核心修改 2：指定 JDK 17 编译
<properties><java.version>17</java.version><!-- 兼容 Maven 编译 --><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target>
</properties>
4.2 Gradle 配置修改
// 原 2.7.x
// id 'org.springframework.boot' version '2.7.18'// 新 3.4.13
id 'org.springframework.boot' version '3.4.13'
sourceCompatibility = '17'
targetCompatibility = '17'
五、全量依赖升级（关键步骤）
Spring Boot 3.x 已内置依赖管理，大部分依赖无需指定版本，仅需升级不兼容的第三方包。
5.1 必改依赖（ Jakarta 适配）
- Servlet API（自动替换，无需手动引入）
- MyBatis/MyBatis-Plus
<!-- MyBatis --> <dependency><groupId>org.mybatis.spring.boot</groupId><artifactId>mybatis-spring-boot-starter</artifactId><version>3.0.3</version> </dependency> <!-- MyBatis-Plus --> <dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-boot-starter</artifactId><version>3.5.10</version> </dependency> - 数据库驱动（MySQL 8+ 推荐）
<dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope> </dependency> - Swagger/Knife4j（替换为 SpringDoc）
Spring Boot 3.x 不支持原 Swagger2，使用 SpringDoc OpenAPI：<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.6.0</version> </dependency>
5.2 移除废弃依赖
- 移除
javax.servlet-api - 移除
javax.persistence-api - 移除旧版
spring-boot-configuration-processor（新版已内置）
六、代码全量适配（最核心改造）
6.1 包名全局替换（javax → jakarta）
这是 Spring Boot 3 最大的变更，所有 javax. 开头的 EE 包替换为 jakarta.
| 旧包名（javax） | 新包名（jakarta） |
|---|---|
| javax.servlet.* | jakarta.servlet.* |
| javax.persistence.* | jakarta.persistence.* |
| javax.validation.* | jakarta.validation.* |
| javax.transaction.* | jakarta.transaction.* |
批量替换方法：
- IDEA 快捷键：
Ctrl+Shift+R，全局替换import javax.→import jakarta. - 实体类、Controller、过滤器、拦截器全量修改
6.2 JDK 17 模块化适配
JDK 17 封闭了内部 API，若出现以下错误：
module java.base does not "opens java.lang" to unnamed module
解决方案：
- 升级第三方依赖到最新版
- 启动参数添加（临时方案，优先升级依赖）
<plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><jvmArguments>--add-opens java.base/java.lang=ALL-UNNAMED</jvmArguments></configuration> </plugin>
6.3 Spring Boot 3.x 废弃 API 适配
- 配置文件：
server.tomcat.max-threads等配置无变更，兼容原有写法 - WebMvcConfigurer：无破坏性变更
- RedisTemplate：配置不变，依赖自动适配
- 定时任务：
@Scheduled用法完全兼容
6.4 日志框架适配
Spring Boot 3.x 默认使用 Logback，无需额外配置，移除旧版 log4j 依赖。
七、配置文件与启动类适配
- 启动类无修改：
@SpringBootApplication用法不变 - application.yml/application.properties：
- 数据库、Redis、端口等配置完全兼容
- Swagger 替换为 SpringDoc 后，新增配置：
springdoc:api-docs:enabled: trueswagger-ui:path: /swagger-ui.html
八、测试验证
8.1 单元测试升级
依赖替换：
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope>
</dependency>
测试注解：@SpringBootTest 用法不变，Junit 5 自动适配。
8.2 启动验证
- 清理 Maven 缓存：
mvn clean - 编译项目：
mvn compile - 启动项目，无报错即基础适配成功
- 访问接口、Swagger、数据库操作，验证功能正常
九、常见问题与解决方案
问题 1：包冲突 jakarta.servlet 不存在
原因：旧依赖未移除，或第三方包未升级
解决：执行 mvn dependency:tree 排查冲突依赖，升级至 3.x 适配版
问题 2：JDK 版本错误：“错误: 发行版 17 不支持”
解决：
- IDEA 设置：
File → Project Structure → SDK 选择 17 - Maven/Gradle 配置
java.version=17
问题 3：MyBatis 绑定异常
解决：升级 MyBatis 版本，检查 mapper.xml 命名空间
问题 4：FastJSON 序列化异常
解决：升级至 FastJSON 2.x：
<dependency><groupId>com.alibaba.fastjson2</groupId><artifactId>fastjson2</artifactId><version>2.0.32</version>
</dependency>
十、升级后优化建议
- 启用虚拟线程（Spring Boot 3.4+ 支持，性能提升）
spring:threads:virtual:enabled: true - 使用 Spring Boot 3.x 新特性：AOT 编译、原生镜像
- 全面替换过时 API，贴合官方最佳实践
总结
本指南覆盖 OpenJDK 17 下载安装、Spring Boot 3.4.13 配置升级、代码包名替换、依赖适配、问题排查 全流程，按照步骤操作即可完成 Spring Boot 2.7 + JDK 8 到最新版本的平滑升级。
升级核心三步：
- 安装 OpenJDK 17，配置开发环境
- 修改 pom.xml 版本，升级第三方依赖
- 全局替换
javax→jakarta，修复废弃 API
升级后项目将获得更强性能、更长官方支持、更安全的生态环境，为后续功能迭代奠定基础。