若依（RuoYi）框架升级 Tomcat 到最新版本的完整流程，我会从升级前提、核心步骤、版本适配、避坑指南四个维度拆解，覆盖单体版（RuoYi-Vue）和微服务版（RuoYi-Cloud），确保升级后系统稳定运行。
若依最新前后端分离源码下载：
https://gitee.com/ruoyieleadmin/ruoyi-ele-admin
一、升级前提（必看）
- 版本确认：
- 若依单体版：默认使用嵌入式 Tomcat（Spring Boot 内置），升级本质是升级 Spring Boot 依赖中的 Tomcat 版本；
- 若依微服务版：网关 / 业务模块为嵌入式 Tomcat，若部署为外置 Tomcat，需同步升级外置包 + 项目依赖；
- 最新 Tomcat 版本：截至 2026 年，稳定版为 Tomcat 10.1.x（注意：Tomcat 10+ 基于 Jakarta EE 9，与 Java EE 8 不兼容，若依框架（基于 Spring Boot）优先选 Tomcat 9.0.x 最新版（如 9.0.96），兼容性最佳）。
- 兼容性检查：
- JDK 版本：Tomcat 9 需 JDK 8+，Tomcat 10 需 JDK 11+；
- Spring Boot 版本：若依默认 Spring Boot 2.x 适配 Tomcat 9，Spring Boot 3.x 适配 Tomcat 10；
- 核心依赖：确保项目中无硬编码依赖旧版 Tomcat API（如
org.apache.tomcat.util下的类）。
二、核心升级步骤（分场景）
场景 1：若依单体版（嵌入式 Tomcat，最常用）
嵌入式 Tomcat 升级只需修改 pom.xml 中 Tomcat 依赖版本，步骤如下：
1. 排除默认 Tomcat 依赖
在 pom.xml 中找到 Spring Boot Starter Web 依赖，排除内置 Tomcat：
xml
<!-- Spring Boot Web 核心依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <!-- 排除默认 Tomcat 依赖 --> <exclusions> <exclusion> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> </exclusion> </exclusions> </dependency>
2. 引入指定版本 Tomcat 依赖
添加最新版 Tomcat 依赖（以 9.0.96 为例，兼容性最佳）：
xml
<!-- 引入最新版嵌入式 Tomcat --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> <!-- 指定 Tomcat 版本（Spring Boot 2.x 适配 9.x） --> <version>9.0.96</version> </dependency> <!-- 可选：若使用 Tomcat 连接池，同步升级 --> <dependency> <groupId>org.apache.tomcat</groupId> <artifactId>tomcat-jdbc</artifactId> <version>9.0.96</version> </dependency>
3. 验证版本
启动项目，在日志中查看 Tomcat 版本：
plaintext
INFO [main] org.apache.catalina.core.StandardService : Starting service [Tomcat] INFO [main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.96]
场景 2：若依微服务版（Gateway / 业务模块）
微服务版每个模块独立配置，需在网关（gateway）、系统模块（system）等所有 pom.xml 中执行以下操作：
- 排除各模块中 Spring Boot Starter Web/Starter Tomcat 的默认依赖；
- 统一引入最新版 Tomcat 依赖（如 9.0.96）；
- 重启所有微服务，验证日志中的 Tomcat 版本。
场景 3：外置 Tomcat 部署（若依打包为 WAR 包）
若依项目打包为 WAR 包部署到外置 Tomcat，需同步升级：
1. 升级外置 Tomcat 包
- 下载最新版 Tomcat（9.0.96）：Tomcat 官网；
- 替换服务器上的 Tomcat 目录，复制原有配置（如
server.xml、context.xml、端口、数据源配置）； - 确保 Tomcat 目录权限（如
bin目录可执行）。
2. 项目依赖适配
在 pom.xml 中调整打包方式为 WAR，并适配外置 Tomcat：
xml
<!-- 打包方式改为 WAR --> <packaging>war</packaging> <!-- 排除嵌入式 Tomcat（仅运行时排除） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> <scope>provided</scope> <!-- 运行时由外置 Tomcat 提供 --> </dependency> <!-- 引入 Servlet API 依赖（适配外置 Tomcat） --> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <!-- Tomcat 9 适配 4.0.x --> <scope>provided</scope> </dependency>
3. 调整启动类
在启动类中继承 SpringBootServletInitializer，适配外置 Tomcat 启动：
java
运行
import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.builder.SpringApplicationBuilder; import org.springframework.boot.web.servlet.support.SpringBootServletInitializer; @SpringBootApplication public class RuoYiApplication extends SpringBootServletInitializer { @Override protected SpringApplicationBuilder configure(SpringApplicationBuilder application) { return application.sources(RuoYiApplication.class); } public static void main(String[] args) { SpringApplication.run(RuoYiApplication.class, args); } }
三、关键配置适配（升级后必检查）
- 端口 / 连接器配置：若使用外置 Tomcat，检查
conf/server.xml中的连接器配置，确保兼容新版：
xml
<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8" /> <!-- 新版 Tomcat 保留该配置，无需修改 -->
-
- 字符编码配置：新版 Tomcat 默认编码为 UTF-8，若依框架已配置，无需额外调整；若出现乱码，在
conf/web.xml中添加：
xml
<filter> <filter-name>setCharacterEncoding</filter-name> <filter-class>org.apache.catalina.filters.SetCharacterEncodingFilter</filter-class> <init-param> <param-name>encoding</param-name> <param-value>UTF-8</param-value> </init-param> <init-param> <param-name>ignore</param-name> <param-value>true</param-value> </init-param> </filter> <filter-mapping> <filter-name>setCharacterEncoding</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
-
- 数据源 / 连接池适配：若依使用 Druid 连接池，新版 Tomcat 无需调整 Druid 配置；若使用 Tomcat 连接池，同步升级
tomcat-jdbc依赖版本。
四、避坑指南（生产环境必看）
- Tomcat 10 兼容性问题：
- Tomcat 10 将
javax.servlet替换为jakarta.servlet，若依框架（基于 Spring Boot 2.x）直接升级会报错，需：① 升级 Spring Boot 到 3.x（适配 Jakarta EE 9）；② 替换所有javax.servlet依赖为jakarta.servlet； - 建议：生产环境优先使用 Tomcat 9.x 最新版，避免兼容性改造。
- 依赖冲突问题：
- 升级后若出现
ClassNotFoundException（如org.apache.tomcat.util.buf.StringUtils），检查项目中是否有第三方依赖硬编码依赖旧版 Tomcat，需排除冲突依赖： xml
<dependency> <groupId>第三方依赖groupId</groupId> <artifactId>第三方依赖artifactId</artifactId> <exclusions> <exclusion> <groupId>org.apache.tomcat</groupId> <artifactId>tomcat-util</artifactId> </exclusion> </exclusions> </dependency>
- 启动失败问题：
- 若启动报错
Address already in use，检查 Tomcat 端口是否被占用（新版 Tomcat 无端口默认变更，只需确保端口未被占用）； - 若报错
Permission denied，检查 Tomcat 目录 / 日志目录的读写权限。
- 性能适配：
- 新版 Tomcat 优化了 NIO 性能，可调整连接器线程池配置，提升并发： xml
<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="500" minSpareThreads="100" connectionTimeout="20000" redirectPort="8443" />
五、验证升级成功
- 启动验证：项目正常启动，无 Tomcat 相关报错；
- 功能验证：访问若依后台管理系统，测试登录、菜单、接口调用等核心功能；
- 版本验证：
- 嵌入式 Tomcat：查看启动日志中的 Tomcat 版本；
- 外置 Tomcat：访问
http://ip:port/manager/html（需配置 Tomcat 管理账号），查看版本信息。
总结
若依框架升级 Tomcat 的核心逻辑：
- 嵌入式 Tomcat：仅需修改
pom.xml排除默认依赖 + 引入新版依赖，适配成本最低； - 外置 Tomcat：同步升级 Tomcat 包 + 项目 WAR 包依赖 + 启动类适配；
- 避坑重点：优先选 Tomcat 9.x 最新版（兼容 Spring Boot 2.x），避免 Tomcat 10 的兼容性改造；
- 验证关键：启动无报错、核心功能正常、版本日志匹配。
