IntelliJ IDEA 2024.1 + Tomcat 10 配置 Java Web 开发环境：5步解决 404 与乱码问题

刚接触 Java Web 开发的新手在使用 IntelliJ IDEA 和 Tomcat 10 搭建环境时，经常会遇到两个令人头疼的问题：404 页面未找到错误和中文乱码。本文将提供一个完整的、可复现的环境配置清单，包含 5 个关键配置步骤的详细说明，并重点讲解 Tomcat 10 的部署路径映射和 UTF-8 编码设置的 3 个关键参数。

1. 环境准备与项目创建

在开始配置之前，我们需要确保所有必要的工具和环境已经准备就绪。以下是所需软件及其版本要求：

• IntelliJ IDEA 2024.1（Ultimate 或 Community 版）
• JDK 17（LTS 长期支持版本）
• Tomcat 10.1.x（与 Java EE 8 兼容）

注意：Tomcat 10 与早期版本有显著差异，它实现了 Jakarta EE 9+ 规范，包名已从javax.*改为jakarta.*，这是导致许多兼容性问题的根源。

创建新项目的步骤如下：

1. 打开 IntelliJ IDEA，选择 "New Project"
2. 在左侧菜单中选择 "Java Enterprise"
3. 确保已选择正确的 JDK（17 或更高版本）
4. 在 "Additional Libraries and Frameworks" 中勾选 "Web Application"
5. 点击 "Create" 完成项目创建

<!-- 检查 pom.xml 中的 Jakarta EE 依赖 --> <dependency> <groupId>jakarta.servlet</groupId> <artifactId>jakarta.servlet-api</artifactId> <version>5.0.0</version> <scope>provided</scope> </dependency>

2. Tomcat 10 服务器配置

正确配置 Tomcat 服务器是避免 404 错误的关键第一步。以下是详细配置流程：

2.1 添加本地 Tomcat 服务器

1. 点击 IntelliJ IDEA 右上角的 "Add Configuration"
2. 点击 "+" 号，选择 "Tomcat Server" → "Local"
3. 在 "Application Server" 部分点击 "Configure"，指定 Tomcat 10 的安装目录
4. 确保 "HTTP port" 设置为 8080（默认值）

2.2 部署路径配置

404 错误通常源于部署路径配置不当。在 "Deployment" 标签页中：

1. 点击 "+" 添加 Artifact（通常选择 war exploded 格式）
2. 在 "Application context" 中设置正确的上下文路径（如/demo）
3. 确保 "Deploy applications configured in Tomcat instance" 已勾选

常见问题排查表：

3. 项目结构配置

正确的项目结构对于避免资源找不到和乱码问题至关重要。以下是必须检查的配置项：

3.1 web.xml 与 Jakarta EE 兼容性

Tomcat 10 使用 Jakarta EE 9+ 规范，因此需要确保 web.xml 头文件使用正确版本：

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd" version="5.0"> </web-app>

3.2 资源目录结构

确保项目有以下标准目录结构：

src ├── main │ ├── java # Java 源代码 │ ├── resources # 资源文件 │ └── webapp # Web 资源 │ ├── WEB-INF │ │ └── web.xml │ └── index.jsp

提示：在 IntelliJ IDEA 中，可以通过右键点击目录 → Mark Directory as → Sources Root/Resources Root 来正确标记目录类型。

4. 解决中文乱码问题

中文乱码通常由三个环节的编码不一致引起：请求编码、响应编码和服务器默认编码。以下是全面的解决方案：

4.1 全局编码设置

在WEB-INF/web.xml中添加全局过滤器配置：

<filter> <filter-name>encodingFilter</filter-name> <filter-class>org.apache.tomcat.util.http.fileupload.FileUploadFilter</filter-class> <init-param> <param-name>encoding</param-name> <param-value>UTF-8</param-value> </init-param> </filter> <filter-mapping> <filter-name>encodingFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>

4.2 JSP 页面编码设置

在每个 JSP 页面顶部添加以下指令：

<%@ page contentType="text/html;charset=UTF-8" language="java" %> <%@ page pageEncoding="UTF-8" %>

4.3 Tomcat 服务器编码配置

修改 Tomcat 的conf/server.xml文件，在 Connector 配置中添加 URI 编码：

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8"/>

编码问题全面检查清单：

1. 检查所有 JSP 页面的 pageEncoding 和 contentType
2. 确保 HTML 表单提交使用 POST 方法（GET 方法更容易出现乱码）
3. 验证数据库连接字符串是否指定了字符集（如useUnicode=true&characterEncoding=UTF-8）
4. 确认 IDE 的文件编码设置为 UTF-8（File → Settings → Editor → File Encodings）

5. 常见问题排查与调试技巧

即使按照上述步骤配置，仍可能遇到各种问题。以下是针对常见问题的专业调试方法：

5.1 404 错误深度排查

当遇到 404 错误时，按照以下步骤排查：

1. 检查 URL 路径：确保访问的 URL 与部署的上下文路径匹配
2. 查看 Tomcat 日志：logs/catalina.out文件包含详细的部署信息
3. 验证类加载：在 Servlet 的 init() 方法中添加日志输出，确认类是否被加载
4. 检查 war 包结构：使用jar -tf yourproject.war命令验证 war 包内容

5.2 乱码问题高级解决方案

对于顽固的乱码问题，可以尝试以下方法：

// 在 Servlet 中强制设置请求和响应编码 request.setCharacterEncoding("UTF-8"); response.setCharacterEncoding("UTF-8"); response.setContentType("text/html;charset=UTF-8"); // 对于文件下载时的中文文件名乱码 String userAgent = request.getHeader("User-Agent"); String fileName = "中文文件.txt"; if (userAgent.contains("MSIE") || userAgent.contains("Trident")) { // IE 浏览器 fileName = URLEncoder.encode(fileName, "UTF-8"); } else { // 其他浏览器 fileName = new String(fileName.getBytes("UTF-8"), "ISO-8859-1"); } response.setHeader("Content-disposition", "attachment;filename=" + fileName);

5.3 性能优化配置

在解决基本问题后，可以考虑以下性能优化配置：

1. 调整 JSP 编译参数：

<servlet> <servlet-name>jsp</servlet-name> <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> <init-param> <param-name>development</param-name> <param-value>false</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet>

2. 启用静态资源缓存：

<filter> <filter-name>expiresFilter</filter-name> <filter-class>org.apache.catalina.filters.ExpiresFilter</filter-class> <init-param> <param-name>ExpiresByType text/css</param-name> <param-value>access plus 1 week</param-value> </init-param> </filter>

3. 配置连接池（以 HikariCP 为例）：

HikariConfig config = new HikariConfig(); config.setJdbcUrl("jdbc:mysql://localhost:3306/db?useUnicode=true&characterEncoding=UTF-8"); config.setUsername("user"); config.setPassword("password"); config.addDataSourceProperty("cachePrepStmts", "true"); config.addDataSourceProperty("prepStmtCacheSize", "250"); config.addDataSourceProperty("prepStmtCacheSqlLimit", "2048"); HikariDataSource ds = new HikariDataSource(config);

在实际项目中，我曾遇到一个棘手的乱码问题：所有配置都正确，但某些特定中文字符仍显示为问号。最终发现是数据库字段使用了错误的字符集。这个经历让我明白，编码问题需要从客户端到数据库的整个链路进行系统检查。