Tomcat部署与Servlet添加全攻略：从IDEA 2024环境配置到跑通第一个Servlet

这两年带新人做 Java Web 入门，我发现一个特别普遍的现象：很多同学跟着教程用 IDEA 敲完代码，项目能启动，但你要是问他“你刚才到底点了个什么按钮？Tomcat 和 IDEA 之间是怎么配合的？为什么访问地址是 localhost:8080 而不是 8081？”，基本上就沉默了。

其实 Tomcat 部署和 Servlet 添加这件事，本身不难，难的是很多人只记住了“点哪里”，没理解“为什么是点这里”。这篇文章我想用一种更接近实际操作的方式，把从下载 Tomcat 到在 IDEA 2024 里跑通第一个 Servlet 的整个链路讲清楚。不管你是刚学 Java Web 的在校生，还是半路转行、想补一补基础的前端或运维同学，照着这篇文章走一遍，再去回头看那些项目，你会觉得思路清晰很多。

为了让你少走弯路，我会把版本选型、目录结构、配置参数、踩坑记录全部放进来，包括那些网上教程一般不写、但新手一定会遇到的麻烦。

1. 部署之前的认知准备：Tomcat 到底在项目里扮演什么角色

很多教程上来就让你下载 Tomcat、配置环境变量，然后点启动，全程都在“操作”，没有解释“原理”。我建议你先花五分钟搞清楚一件事：Servlet 和 Tomcat 是什么关系，否则后面出错了，你连排查方向都没有。

1.1 从一次浏览器请求说起

你在浏览器地址栏输入 http://localhost:8080/hello 并回车，这个请求到达 Servlet 之前，其实已经经历了一整套流程：

浏览器发出 HTTP 请求 → 操作系统通过 localhost 找到本机 IP → 请求到达 8080 端口 → Tomcat 作为服务器在这里监听 → Tomcat 解析请求行和请求头 → 根据 URL 中的 /hello 查找对应的 Servlet 映射 → 找到后调用 Servlet 的 service 方法 → Servlet 生成响应内容 → Tomcat 把 HTTP 响应封装好返回给浏览器。

关键在于：Servlet 本身只是一个个 Java 类，它没有 main 方法，不能独立运行，也不知道怎么接收网络请求。真正负责“接收 HTTP 请求、解析请求、管理线程并发、调用 Servlet、封装响应”的，是 Tomcat 这个 Servlet 容器。你可以把 Servlet 理解成演员，Tomcat 是舞台和剧务团队。演员只管演好自己的戏，灯光、音响、场务、票务全是舞台这边在处理。

所以在学 Servlet 的时候，别把精力全放在背 API 上，先理解这个容器机制。后面你遇到的很多问题，比如 404、端口占用、请求找不到映射，本质上都是“Tomcat 在处理请求的某个环节出问题了”，而不是你的 Java 代码逻辑错了。

1.2 版本选型：javax.servlet 还是 jakarta.servlet

这是 2024 年新手最容易踩的坑，没有之一。

早期 Java EE 时代的 Servlet API 包名是 javax.servlet，Tomcat 8.x、9.x 用的就是这套。但从 Jakarta EE 9 开始，Oracle 把 Java EE 捐给了 Eclipse 基金会，包名从 javax.* 改成了 jakarta.*。Tomcat 10.x 和 11.x 已经全面切换到 jakarta.servlet，你在代码里写 import javax.servlet.* 会直接报错。

所以你下载 Tomcat 之前，先想清楚自己要学哪一套：

我的建议是新手直接选 Tomcat 10.1.x，配合 IDEA 2024 和 JDK 17，这是目前最舒服、最贴近生产环境主流的一套组合。你看到老教程里用的 javax.servlet 别慌，把包名前面的 javax 换成 jakarta 就通了，其它 API 用法基本一样。

还有一个细节：Tomcat 有个“汉化版”的说法，其实官方发行版就是英文，网上很多自称汉化版的包，实际上是别人改过的，不建议用。直接去 Apache 官网下载 zip 或 tar.gz 就行。

2. 环境准备：JDK 与 Tomcat 的下载安装配置

环境配置这部分看似简单，但很多新手卡在“明明按教程做了，为什么还是起不来”。我拆成 JDK、Tomcat、验证三步讲，每一处都会说明为什么这么做。

2.1 JDK 装哪个版本最省心

Tomcat 10.1 要求 JDK 11 起步，Tomcat 11 要求 JDK 17 起步。工程实践里 JDK 17 是 LTS 长期支持版本，IDE、框架、中间件兼容性都最好，所以我建议统一装 JDK 17。

去 Oracle 官网或者使用 OpenJDK 发行版都行，安装完成后打开命令行验证：

bash复制java -version

正常会看到类似这样的输出：

bash复制java version "17.0.10" 2024-01-16 LTS
Java(TM) SE Runtime Environment (build 17.0.10+8)
Java HotSpot(TM) 64-Bit Server VM (build 17.0.10+8, mixed mode, sharing)

如果提示 java 不是内部或外部命令，说明环境变量没配好，或者安装时没勾选添加到 PATH。Windows 上装 JDK 后，在系统环境变量的 Path 里加上 JDK 的 bin 目录即可。IDEA 2024 自己也能识别已安装的 JDK，所以这步只要命令行能跑通 java -version 就算过了。

另外提醒一下：如果你之前装过 JDK 8，又装了 17，命令行里 java -version 显示的可能是旧版本。最容易的办法是把旧版本卸载干净，或者确保 Path 里新 JDK 的 bin 目录排在前面。

2.2 下载并配置 Tomcat

Tomcat 的下载页一般提供两个版本：zip 和 tar.gz。Windows 用 zip，Mac 和 Linux 用 tar.gz。下载后解压到一个路径里不要有中文和空格的目录，比如 D:\tools\apache-tomcat-10.1.24，这一步很多人忽略，后续容易出现莫名其妙的问题。

解压后的目录结构你需要知道几个关键目录：

关于环境变量，很多教程会让你配 CATALINA_HOME。说实话，如果你只是用 IDEA 集成启动，这步可以跳过。但如果想用命令行独立启动 Tomcat，配一个更省事：新建系统变量 CATALINA_HOME，值为 Tomcat 解压目录，然后在 Path 里加 %CATALINA_HOME%\bin。

接着打开 conf/server.xml，找到 Connector 配置：

xml复制<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

默认 HTTP 端口是 8080。如果你机器上之前装过别的服务占用了 8080，可以在这里改成 8081 或 8088。改端口这个操作本身很简单，但你要理解：Tomcat 监听的就是这个端口，你浏览器访问的端口必须和它保持一致，否则连接被拒。

2.3 第一次启动 Tomcat 与常见启动问题

Windows 下双击 bin\startup.bat，会弹出一个命令行窗口，看到类似 Server startup in [xxx] milliseconds 就说明启动成功了。Mac/Linux 下执行：

bash复制sh bin/startup.sh

然后浏览器访问 http://localhost:8080，看到那只猫的默认首页就成功了。

新手最常见的两个问题，一个是“启动后窗口一闪而过”，这种情况基本是 JAVA_HOME 或 JRE_HOME 没配置，或者配置指向的目录不存在。Tomcat 的 startup.bat 脚本会去查 JAVA_HOME 环境变量，查不到就直接退出。把 JAVA_HOME 指到 JDK 安装目录，而不是 JDK 的 bin 目录。

另一个是端口被占用。启动日志报：

bash复制The Tomcat connector configured to listen on port 8080 failed to start.

说明 8080 被别的进程占了。命令行执行 netstat -ano | findstr 8080 查看占用进程 PID，然后去任务管理器结束它，或者干脆改 Tomcat 端口。

3. IDEA 2024 创建 Web 项目并接入 Tomcat

等 Tomcat 能独立启动之后，再回到 IDEA 2024 里创建项目。IDEA 2024 的向导界面和以前版本相比有一些变化，但核心逻辑是一样的。我下面会同时介绍两种创建方式，并给出我的推荐。

3.1 创建 Web 项目的三种方式与推荐

第一种，用 IDEA 自带的 Jakarta EE / Java Enterprise 模板。点击 File -> New -> Project，左侧选 Jakarta EE，右侧勾选 Web Application，IDEA 会自动生成一个带 web.xml 或注解支持的 Web 项目。这个方式最省事，但如果你不熟悉 IDEA 的模块结构，后面配置时容易懵。

第二种，创建普通 Maven 项目，然后手动添加 Web 支持。先点击 File -> New -> Project，选 Maven，填好 groupId、artifactId 和版本，生成项目后，右键模块名，选择 Add Framework Support，勾选 Web Application。IDEA 会自动生成 web 目录，但没有 web.xml，可以通过注解使用 Servlet。

第三种，用 Maven 的 webapp 原型（archetype）创建。在 New Project 的 Archetype 里选 org.apache.maven.archetypes:maven-archetype-webapp。这种方式生成的目录结构最接近传统 Java Web 项目，默认带有 src/main/webapp 和 web.xml，很多老教程用的就是这种方式。

我的建议是新手选第三种，用 Maven webapp 原型。原因有三个：第一，目录结构规范，后面学 Maven 打包部署不会陌生；第二，自带 web.xml，你可以同时看到 xml 和注解两种 Servlet 配置方式；第三，网上能找到的参考资料最多。

如果你用的 IDEA 2024 在新建项目时没有直接看到 webapp 的 archetype，可以选择 Maven 后，点击右下角的 Add Archetype，输入：

xml复制GroupId: org.apache.maven.archetypes
ArtifactId: maven-archetype-webapp
Version: 1.4

添加完成后刷新，再选中它创建即可。

3.2 配置 Tomcat 运行环境

项目创建好之后，下一步就是把 Tomcat 接入 IDEA。点击 IDEA 顶部工具栏的运行配置下拉框，选择 Edit Configurations。在左侧点加号，往下翻，找到 Tomcat Server，选择 Local。

在 Server 选项卡里，点击 Configure 按钮，选择你解压出来的 Tomcat 目录。IDEA 会自动识别 Tomcat 版本。这里有两点要注意：

第一，Application server 选的是 Tomcat 的根目录，不是 bin 目录，也不是 conf 目录。选错的话 IDEA 会报错提示找不到 Tomcat。

第二，如果你改了 Tomcat 端口，需要在 Server 选项卡里把 HTTP port 也改成对应端口。IDEA 默认会读取 server.xml 里的端口，但有时因为缓存原因不一致，建议手动确认一下。

URL 会自动变成 http://localhost:8080/，这个地址就是待会你要访问的地址。下面还有个 Open browser 选项，默认是启动后自动打开浏览器。我在开发时习惯把 After launch 取消掉，免得每次启动都弹一个空首页，这个看个人喜好。

配置好 Server 之后，重点来了：还要在 Deployment 选项卡里把项目部署进去。这也是很多新手忽略的地方。IDEA 里部署 Web 项目有两种形态：Exploded 和 Archive。Exploded 是解压后的目录，开发调试用这种，IDEA 会把编译输出的 class 文件和资源文件按 Web 应用结构组织好；Archive 是打包成 war 文件，一般用于生产部署。

我们开发阶段用 Exploded 就行。点击加号，选择 Artifact，选中项目名后面的 web exploded 版本。然后在 Application context 里填写上下文路径。这一个值决定你访问的 URL 前缀，非常关键。

3.3 引入 Servlet API 依赖

接好 Tomcat 之后，另一个问题就来了：代码里要用 HttpServlet，这个类从哪里来？

Tomcat 的 lib 目录里自带 servlet-api 的 jar，但如果你是 Maven 项目，更规范的做法是在 pom.xml 里显式引入依赖。打开项目根目录的 pom.xml，加上这段：

xml复制<dependencies>
    <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>6.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

注意 scope 是 provided，意思是编译和测试时用，真正运行时由 Tomcat 提供，打包时不要打进去。如果你用的 Tomcat 9，groupId 要改成 javax.servlet，artifactId 是 javax.servlet-api。

添加依赖后，IDEA 可能会提示你需要 Reload Maven Project，点一下右侧 Maven 侧边栏的刷新按钮，让依赖下载并加入项目。

4. 动手写第一个 Servlet 并成功访问

环境都准备好了，现在进入核心环节：写 Servlet 代码，配置映射，启动项目，在浏览器里看到自己的输出。这个过程如果理解了，后面再学 Spring MVC 的 DispatcherServlet、过滤器、拦截器都会轻松很多。

4.1 Servlet 代码示例与两种映射方式

在 src/main/java 下新建一个包，比如 com.example，然后创建一个类 HelloServlet，继承 HttpServlet，重写 doGet 方法。先看代码：

java复制package com.example;

import jakarta.servlet.ServletException;
import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import java.io.IOException;
import java.io.PrintWriter;
import java.time.LocalDateTime;

@WebServlet("/hello")
public class HelloServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        PrintWriter out = response.getWriter();
        out.println("<!DOCTYPE html>");
        out.println("<html>");
        out.println("<head><meta charset=\"UTF-8\"><title>第一个Servlet</title></head>");
        out.println("<body>");
        out.println("<h1>Hello Servlet 运行成功</h1>");
        out.println("<p>当前时间: " + LocalDateTime.now() + "</p>");
        out.println("</body>");
        out.println("</html>");
    }
}

这里面最关键的是 @WebServlet("/hello")，这就是 Servlet 的映射路径。它的意思说：当浏览器访问 上下文路径/hello 时，Tomcat 会把请求交给 HelloServlet 处理。这个注解是 Servlet 3.0 之后引入的，用起来非常方便，不用再在 web.xml 里写一堆配置。

但如果你用的是 Maven webapp 模板创建的项目，默认有 web.xml，也可以选择在 web.xml 里配置映射。两种方式等价，看个人习惯。使用注解的话，web.xml 里可以留空骨架；使用 xml 的话，配置是这样的：

xml复制<servlet>
    <servlet-name>helloServlet</servlet-name>
    <servlet-class>com.example.HelloServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>helloServlet</servlet-name>
    <url-pattern>/hello</url-pattern>
</servlet-mapping>

两种方式不要同时配置同一个路径，否则启动时可能报冲突。

关于 Servlet 的生命周期，我这里简单提一下，后面实操会用到：Tomcat 加载 Servlet 类并实例化，然后调用 init 方法做初始化，之后每次收到请求都会调用 service 方法。service 内部会根据请求类型调用 doGet 或 doPost。容器关闭时调用 destroy。这些方法有明确的调用规则，你在这些方法里做日志打印，就能看到 Tomcat 是怎么管理 Servlet 的。

4.2 Artifact 部署设置与访问路径推导

代码写完了，但不要急着点运行。先回到运行配置里看 Deployment 和 Tomcat 的配合关系。

之前我在 3.2 提到 Application context 这个值，现在它发挥作用了。假设你的项目 artifact 名叫 web_01_war_exploded，Application context 填的是 /，那访问地址就是 http://localhost:8080/hello。如果把 Application context 填成 /web_01，访问地址就变成 http://localhost:8080/web_01/hello。

很多人不理解为什么有时候访问 404、有时候能访问，根本原因就是上下文路径搞混了。Application context 等于你给应用起了一个访问别名。IDEA 里部署的 webapp 默认情况下，访问路径会是：

code复制http://localhost:8080/应用上下文/Servlet映射路径

所以你自己梳理一下：Tomcat 监听 8080 端口 → 应用上下文是 / 还是 /web_01 → Servlet 注解里的 /hello → 完整 URL 是什么。按照这个公式去推导，基本不会错。

另外你在配置 Deployment 时，IDEA 会显示一条 Deploy at the server startup 的信息，表示启动 Tomcat 时自动部署这个 artifact。开发阶段保持这个勾选状态不用改。

4.3 运行、调试与验证

现在可以点右上角的运行按钮了。注意这次运行的是 Tomcat 配置，不是运行普通 Java 类。控制台会输出 Tomcat 启动日志，等到看见 Server startup in [xxx] milliseconds，项目就算跑起来了。

打开浏览器，在地址栏输入对应的 URL。如果一切正常，你会看到一个 HTML 页面，上面显示“Hello Servlet 运行成功”和当前时间。

这里我要特别强调一个调试小技巧：把 Tomcat 启动方式切换成 Debug 模式，然后在 HelloServlet 的 doGet 方法第一行打断点，浏览器再访问一次，IDEA 会自动停在断点处。这时候你可以看到 request 对象里封装了哪些请求参数、header 信息，response 对象在写入前是什么状态。比你在代码里打印日志直观得多。

如果你在这个步骤遇到问题，不要急，下一章就是专门整理这些常见坑的。以下内容都是我在实际教学和开发中反复遇到的真实情况，希望能帮你节约时间。

5. 新手最容易踩的 6 个坑与排查实录

这部分是我最想写、也是平时答疑时被问得最多的内容。每个问题我都按照“现象 → 原因 → 解决方法”的结构给你写清楚。遇到问题时别慌，按这个表排查即可。

5.1 Tomcat 启动闪退 / 端口被占用

现象一：Windows 下双击 startup.bat，窗口一闪而过，Tomcat 没启动。

原因：绝大多数情况是 JAVA_HOME 环境变量没配，或者配错了。startup.bat 依赖 JAVA_HOME 找 java.exe，找不到就退出。解决办法是在系统环境变量里新建：

bash复制JAVA_HOME = D:\Program Files\Java\jdk-17

注意 JAVA_HOME 要指到 JDK 的根目录，不是 bin 目录，也不要在结尾加分号。

现象二：启动日志报端口 8080 被占用。

原因：很可能是以前启动的 Tomcat 没关闭，或者别的程序占用了端口。解决步骤：

bash复制netstat -ano | findstr 8080

查到的最后一列是 PID，然后打开任务管理器找到这个 PID，结束进程。如果你确定是另一个 Tomcat 实例占用，那就直接任务管理器结束掉，或者运行 shutdown.bat 关闭。

还有一种情况是虚拟机中的服务占用了端口，比如 Docker 容器映射了 8080，也会冲突。如果你本机跑着 Docker，先看一下是不是端口映射冲突了。

5.2 页面 404 的三种常见原因

404 这个错误太典型了，新手遇到 404 第一反应是代码写错了，其实大部分时候跟代码没关系。我总结三种最常见的原因：

第一，上下文路径没带对。你访问 http://localhost:8080/hello，但 Application context 填的是 /web_01，那实际上应该访问 http://localhost:8080/web_01/hello。这是我在教学里遇到最多的 404 原因。

第二，Servlet 映射路径写错了。注解里写的是 @WebServlet("/hello")，URL 还要带上 /hello，不是类名，也不是项目名。

第三，Artifact 没有部署到 Tomcat。运行配置的 Deployment 里什么都没添加，Tomcat 启动成功了，但你的应用根本没部署进去。解决方法是打开 Edit Configurations，在 Deployment 里把 web exploded artifact 加进去。

5.3 中文乱码：控制台乱码和页面乱码

乱码问题有两种，来源不同，不能混在一起解决。

控制台输出乱码，大多是 Tomcat 默认使用 UTF-8，而 Windows 命令行控制台使用的是 GBK。解决办法：在 IDEA 的 Help -> Edit Custom VM Options 里加上：

bash复制-Dfile.encoding=UTF-8

然后重启 IDEA。同时检查 Run Configuration 里 Tomcat Server 的 VM options 是否也加了 -Dfile.encoding=UTF-8。这两个地方都设成 UTF-8，控制台一般就正常了。

页面输出乱码，要看 Servlet 里有没有设置 ContentType：

java复制response.setContentType("text/html;charset=UTF-8");

这个设置告诉浏览器按 UTF-8 解析响应内容。同时 HTML 里也建议写 <meta charset="UTF-8"> 双保险。另外 IDEA 右下角要注意文件编码，默认 UTF-8 就行，不要改成 GBK。

5.4 IDEA 中 Tomcat 不断生成日志文件

有同学问我，为什么 IDE 里跑一个项目，Tomcat 目录下 logs 文件夹不断生成新文件，项目没跑几次，日志文件一大堆。

原因：IDEA 集成启动 Tomcat 时，Tomcat 本体是外部程序，它默认仍然会向 logs 目录写日志，频繁重启就会生成很多 catalina、localhost 相关的日志文件。

解决办法其实很简单。开发阶段这些日志不影响功能，但如果你看着难受，可以在 conf/logging.properties 里调整。比如把某些 logger 的级别调高，减少输出频率。举个例子：

properties复制org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = WARNING

把级别从 INFO 改成 WARNING，可以大幅减少访问日志的输出。另外定期清理 logs 目录也是开发中的常规操作，不影响的。

5.5 找不到 javax.servlet 或符号与包名报错

这个问题是版本差异引起的。如果你下载了 Tomcat 10.x，但在代码里写：

java复制import javax.servlet.http.HttpServlet;

IDEA 会直接提示找不到符号。因为 Tomcat 10 的 API 包名已经改成 jakarta.servlet 了。解决办法是把所有 import 语句从 javax.servlet 改成 jakarta.servlet。

反过来，如果你用 Tomcat 9，但代码里引入的是 jakarta.servlet，Tomcat 的 lib 里没有这套 jar，启动时会报 ClassNotFoundException。所以版本一定要对应好。

我用表格给你汇总一下：

这 6 个问题基本覆盖了从 0 到 1 部署 Tomcat 和添加 Servlet 时会遇到的绝大多数坑。我在带新人时经常说一句话：环境问题占了 80% 的时间，真正写 Servlet 代码的时间可能不到 20%。所以遇到环境报错别怀疑人生，大概率是版本、端口、路径这三件事里有一个不对。

我个人在实操中的习惯是：每配置一个新环境，先建一个最简单的测试项目跑通，再往里面加业务代码。这样能第一时间把环境问题和代码问题隔离开。比如你今天第一次配 Tomcat，那就先不要写什么复杂逻辑，就写上面那个 HelloServlet，能打印一行字就说明全链路通了。之后再扩展，每扩展一步验证一步，问题出现时定位范围会小很多。

以后学 Spring Boot 时你会发现，内嵌 Tomcat 把这些繁琐的部署配置都隐藏了，但底层原理还是这套东西。你把今天这个流程吃透了，后面遇到任何 Web 容器相关的问题，都知道去哪里看日志、去哪里改配置。

最后再分享一个小技巧：把 Tomcat 的 logs 目录加入 IDEA 的日志控制台视图。这样项目跑起来后，catalina 日志可以直接在 IDEA 下方看，不用切到文件管理器去查。IDEA 的优势就是把这些集成工作做得很细，学会用运行配置里的 Logs 选项卡，你排查问题的速度会快很多。