一步到位！若依框架升级 Tomcat 最新版完整教程

zihan0321

589人浏览 · 2026-02-27 12:42:28

zihan0321 · 2026-02-27 12:42:28 发布

若依（RuoYi）框架升级 Tomcat 到最新版本的完整流程，我会从升级前提、核心步骤、版本适配、避坑指南四个维度拆解，覆盖单体版（RuoYi-Vue）和微服务版（RuoYi-Cloud），确保升级后系统稳定运行。

一、升级前提（必看）

版本确认：
- 若依单体版：默认使用嵌入式 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 管理账号），查看版本信息。