IDEA 2024部署Tomcat并创建第一个Servlet：从0到1完整教程

最近有同学问我，在IDEA里搭一个基于Tomcat的Servlet项目怎么都跑不起来，明明照着网上的步骤一步步来，最后还是各种报错。这个问题我太有共鸣了，当年初学Java Web的时候，光是让Tomcat在IDEA里启动就折腾了一个晚上，后来踩坑多了才把整个流程理顺。这周正好用IDEA 2024最新版重新走了一遍“从0到1部署Tomcat并添加Servlet”的完整流程，把每个容易出问题的细节都记录下来，分享给正在入门Java Web的同学。

这篇教程会覆盖几个核心环节：Tomcat的下载安装与配置、IDEA 2024中创建Web项目、把Tomcat配置到IDEA并成功启动、手写第一个Servlet类并让它能通过浏览器访问。不管你是刚接触Java Web的初学者，还是之前没怎么用过IDEA的新手，只要跟着这篇文章走一遍，基本就能把这个环境跑通。另外，我会在每一章里穿插说明“为什么要这么做”，因为只照着抄步骤，换一个环境大概率还是会卡住，理解了原理后面排查问题会容易很多。

1. 部署前的准备：Tomcat到底是什么，为什么需要它

1.1 先搞清楚Tomcat和Servlet的关系

很多人第一次接触Tomcat时会有个困惑：我学的是Java，为什么还要装一个Tomcat？这里打个比方，你写的Java类就好比一个会做菜的厨师，但厨师不能站在大马路上做菜，他需要一个厨房，Tomcat就是那个提供炉灶、水电、排风系统的厨房。

更专业一点说，Servlet是一组Java API规范，它定义了Java程序如何处理HTTP请求和响应，但你写好的Servlet类不能自己运行，它需要被一个Servlet容器加载、实例化并调用。Tomcat就是最常见的Servlet容器之一，它实现了Servlet规范，同时也内置了HTTP服务器功能，所以它既能接收浏览器的HTTP请求，又能把这些请求转发给你写的Java类去处理。

还有个关键点需要提前知道：Tomcat不是把Servlet当普通Java类一次性执行完就结束，而是常驻运行的服务进程。它会启动一个端口（默认8080）持续监听外部请求，收到请求后创建对应的请求对象和响应对象，调用Servlet方法，再把响应写回浏览器，整个过程循环往复。这也是为什么后面你要把Tomcat作为服务启动，而不是像普通程序那样跑一次就退出。

1.2 下载哪个版本？javax和jakarta的区别要提前搞明白

去Tomcat官网下载的时候，很多人直接选最新版，结果代码一写发现到处都是红线。原因很简单：Tomcat版本更新到10之后，Servlet规范的包名从javax.servlet改成了jakarta.servlet，这是Oracle把Java EE捐给Eclipse基金会后做的品牌调整。

如果你是刚开始学习，我建议直接使用Tomcat 9.0.x版本，对应的Servlet规范是4.0版本，包名是javax.servlet，网上绝大多数教程、视频、面试题都是基于这个包名写的，遇到问题更容易找到资料。当然，如果你有精力，也可以选择Tomcat 10.x版本学习jakarta.servlet包名，虽然只是前缀不同，但代码里所有import语句都要跟着变。

从实战角度看，很多公司老项目还在用Tomcat 8.5或者9.0，新项目则越来越倾向Spring Boot内嵌Tomcat，所以学Tomcat 9.0的javax.servlet并不算过时。下载时注意看Tomcat官网提供的发行版列表，Windows系统选择64-bit Windows zip压缩包就行，下载后是免安装版，解压即可使用，不需要额外的安装向导。

提示：如果你看到网上有些教程让你同时下载jdk、Tomcat、IDEA三个软件，不要慌，这是Java Web开发的基础三件套，这章先解决Tomcat，后面章节再和IDEA组合起来用。

1.3 安装、环境变量和启动验证

Tomcat解压后的目录结构需要先认识一下，后续很多操作都和这几个目录有关。

• bin：存放启动和关闭脚本，Windows下是startup.bat和shutdown.bat
• conf：配置文件目录，核心文件是server.xml，端口号就在这里改
• webapps：放Web项目的地方，把打包好的war包丢进来就能被Tomcat加载
• lib：Tomcat运行所需的jar包，后面Servlet API也在这里

下载解压后，你还得确保系统里已经装了JDK，并且配置了JAVA_HOME环境变量。Tomcat本身是Java程序，启动时需要找到Java运行环境。配置方式很常规，在系统环境变量里新建JAVA_HOME，变量值填JDK安装目录，然后编辑Path，加上%JAVA_HOME%\bin。

如果一切正常，双击bin目录下的startup.bat脚本，会弹出一个命令行窗口，显示类似INFO: Server startup in [xxx] milliseconds这样的日志，然后打开浏览器访问http://localhost:8080，能看到一个带“小猫”图标的默认首页，就说明Tomcat安装成功了。这个页面内容来自webapps目录下的ROOT项目，是Tomcat自带的默认应用，后面你要清理或者替换它也可以。

2. IDEA 2024中创建第一个Web项目

2.1 普通Java工程还是Maven工程？两条路的取舍

IDEA 2024比起旧版本，新建项目的向导界面变得简洁了不少。打开IDEA后，选择New Project，你会看到很多初始模板选项。对于新手学习Servlet，我不建议一上来就勾选复杂的Jakarta EE模板，也不要急着引入Maven。

虽然现在互联网上大部分Java项目都用Maven管理依赖，但对于“只跑通一个Servlet”这个目标来说，Maven反而会引入额外的学习成本——你得多学一个构建工具，还要处理依赖下载、仓库配置这些事。这里我采用的路径是：创建一个普通的Java项目，然后手动添加Web框架支持，再手动引入Servlet API相关的jar包。

这样做的好处是，你能清楚地看到整个Web项目由什么构成，理解哪部分是IDEA提供的工具支持，哪部分是Tomcat提供的运行环境，不容易像用Maven那样“点一下什么都好，但根本不知道背后发生了什么”。当你理解了基本原理之后，再切换到Maven工程，就是水到渠成的事。

2.2 在IDEA里添加Web框架支持

新建好一个普通的Java项目后，你需要让这个项目变成“能部署到Tomcat的Web项目”。右键点击项目根目录，选择“Add Framework Support”，在弹出来的列表里勾选“Web Application”。

这个操作会帮你完成几件事：生成一个名为web的目录，web目录下有WEB-INF文件夹；创建web.xml配置文件（不同版本IDEA行为略有差异，有的版本会直接生成）；在项目结构中注册Web Facet，让IDEA知道这是一个Web项目。

这时候看一下项目结构，大概长这样：

code复制MyWebProject
├── src
├── web
│   └── WEB-INF
│       └── web.xml

其中web目录就是Web项目的根目录，将来你的HTML、JSP、图片等静态资源都放这里，而WEB-INF目录是受保护目录，浏览器无法直接访问到里面的内容，你后面写的Servlet类编译产物就会放在WEB-INF的classes目录下。web.xml是Web应用的部署描述符，Servlet的映射关系可以在这里配置，也可以改用注解方式。

2.3 配置Artifact：IDEA部署到Tomcat的关键概念

这一节是很多人容易忽略的重点。把Web项目部署到Tomcat，不是简单地把代码复制过去，而是在IDEA里生成一个“部署单元”，这个部署单元在IDEA里叫Artifact。

打开项目结构设置（File -> Project Structure，快捷键Ctrl+Alt+Shift+S），左侧选择Artifacts，如果添加框架支持后IDEA没有自动创建，你就手动点“+”号，选择Web Application: Exploded。

这里解释一下Exploded是什么意思：它表示“展开的”目录结构，即把Web项目的资源按原样放好，直接以目录形式参与部署。另一种打包方式是war包，也就是把Web项目压缩成war文件。开发调试阶段我们通常选择Exploded，因为修改代码后能更快地同步到Tomcat里，不需要每一次都重新打war包。

做这一步的时候，注意观察右下角的警告提示，通常它会告诉你缺少可用的库或依赖。你需要把Tomcat目录lib下的servlet-api.jar（如果是Tomcat 10以上则是jakarta.servlet-api.jar）添加进来，这个jar包提供了Servlet接口和类，编译期必须靠它才能写Servlet代码。添加方式可以在Artifacts界面选择Available Elements里的库再点Put into WEB-INF/lib，也可以在Modules的Dependencies选项卡里添加。

3. 在IDEA 2024中配置并启动Tomcat

3.1 添加Tomcat Server运行配置

现在项目这边准备得差不多了，接下来要把Tomcat集成到IDEA的运行管理里。打开顶部工具栏的Run/Debug Configurations下拉菜单，选择Edit Configurations，然后点击左上角的“+”号，在列表里找到Tomcat Server，选择Local。

这里的Local表示使用本地安装的Tomcat，区别于远程部署的Remote。选完Local之后，右侧会有一大堆配置项，你重点看Application server这一栏，点击Configure按钮，选择你的Tomcat安装目录，IDEA会自动检测到Tomcat版本和它的依赖库。

配置页里还有几个参数需要理解一下。Open browser的选项建议选择After launch，意思是在Tomcat启动完成后自动打开浏览器，让你第一时间看到访问结果。URL这一栏会自动填充成http://localhost:8080/，但等会儿配置完Deployment后，它会变成带项目上下文路径的完整地址。HTTP port默认是8080，如果这个端口被占用了，后面会讲到怎么排查。

3.2 Deployment和Application context怎么理解

这是部署环节最核心的一步。在Tomcat Server的配置窗口里，找到Deployment选项卡，点击“+”号，选择Artifact，然后选中你之前创建的那个Web项目Artifact。

添加完成后，下面会出现一个Application context输入框，默认值通常是/项目名。这个路径就是浏览器访问时的上下文根路径，举个例子，如果Application context是/myweb，启动后访问地址就是http://localhost:8080/myweb/。

很多新人会困惑Application context和Servlet路径之间的关系，我简单解释一下：Tomcat可以根据不同的Application context区分同一个端口下挂载的多个Web应用。http://localhost:8080/后面第一段对应Application context，它帮你定位到具体的Web应用；再往后才是这个应用内部的资源路径。比如http://localhost:8080/myweb/hello，其中myweb是应用上下文，hello就是匹配到你写的Servlet的路径。

配置好后，IDEA会自动把之前的URL从http://localhost:8080/更新成http://localhost:8080/myweb/。这个细节要留意，很多新手第一次启动后浏览器自动弹出404，就是因为访问的URL没带上Application context。

3.3 成功启动的标准：从日志到页面

所有配置完成后，点击运行按钮启动Tomcat。第一次启动时，IDEA底部会打开Run工具窗口，显示类似下面的日志信息：

code复制Connected to server
[2025-xx-xx xx:xx:xx,xxx] Artifact ...: Artifact is being deployed, please wait...
[2025-xx-xx xx:xx:xx,xxx] Artifact ...: Artifact is deployed successfully
[2025-xx-xx xx:xx:xx,xxx] Artifact ...: Deploy took ... milliseconds

这几行日志非常关键，它表示IDEA已经把项目部署到Tomcat里了。如果你只看到Tomcat启动日志，而没有看到Artifact部署相关的日志，说明Deployment配置没生效，项目可能根本没有被部署进去。

启动成功后浏览器访问http://localhost:8080/myweb/，如果页面是空白或者显示目录结构列表，不用慌，目前的web根目录下还没有任何可显示的页面。你可以先在web目录下创建一个最简单的hello.html文件，里面写一句欢迎语，再刷新浏览器验证一下Tomcat和IDEA的联动是不是正常的，这一步能帮我们把“环境问题”和“代码问题”分开排查。

4. 手写第一个Servlet：从类到浏览器

4.1 Servlet类的代码结构和生命周期

环境跑通了，现在进入正题，写第一个Servlet。先创建一个类，取名叫HelloServlet，让它继承javax.servlet.http.HttpServlet。Servlet规范要求所有的Servlet类要么实现Servlet接口，要么继承HttpServlet这个便捷类，我们在Web开发中几乎都是继承HttpServlet。

重写doGet方法，这个方法是用来处理HTTP GET请求的。方法本身有两个参数：HttpServletRequest表示请求对象，封装了浏览器发来的全部信息；HttpServletResponse表示响应对象，你可以通过它向浏览器输出内容。代码很简单：

java复制import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.PrintWriter;

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

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        resp.setContentType("text/html;charset=UTF-8");
        PrintWriter writer = resp.getWriter();
        writer.println("<h1>Hello Servlet</h1>");
        writer.println("<p>第一个Servlet运行成功</p>");
    }
}

这里有几个点值得深入理解。@WebServlet("/hello")是Servlet 3.0之后引入的注解，作用是告诉Servlet容器：这个类是一个Servlet，并且当请求路径匹配/hello时调用这个类处理。charset=UTF-8用来处理中文乱码，这章先不多展开，后面会专门讲乱码问题。

Servlet的生命周期可以总结为三个阶段：init方法在Servlet第一次被访问时调用，用于初始化资源；service方法根据请求类型调用doGet或doPost等方法，这是真正处理业务逻辑的地方；destroy方法在Web应用卸载或服务器关闭时调用，用于释放资源。生命周期方法都是由Tomcat容器管理的，你不需要手动调用，这体现了容器对Servlet的管理作用。

你可能会好奇，为什么Servlet容器要“单实例多线程”地管理Servlet？因为每个请求如果都创建和销毁一个Servlet实例，开销会非常大。Tomcat默认只为每个Servlet创建一个实例，所有请求共享这一个实例，所以Servlet是线程不安全的，编写时要注意不要在里面定义可修改的成员变量，或者至少要保证访问方式是线程安全的，这是一个重要的面试考点，在实际编码中也要有这个意识。

4.2 注解映射和web.xml映射，两种方式怎么选

上面代码里用了@WebServlet注解，这是现在主流的做法，简单直接，一眼就能看出路径和类的对应关系。不过还有一种更传统的方式，通过web.xml配置Servlet映射，很多老项目里还能看到这种写法，原理上两种方式是等效的。

web.xml的写法长这样：

xml复制<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                             http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">
    <servlet>
        <servlet-name>hello</servlet-name>
        <servlet-class>com.example.HelloServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>hello</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>
</web-app>

需要特别提醒一点：如果同时使用注解和web.xml配置同一个Servlet，容器会优先使用web.xml中的配置。另外，在Servlet规范中，同一个URL模式只能映射到一个Servlet，如果有多个Servlet都声明了相同的匹配路径，项目部署阶段可能报错或者行为不确定，写代码的时候要注意避免这种冲突。

对于初学者，我建议优先使用注解方式，因为有IDE的语法提示，写错了路径一眼就能看到。但在实际开发中，了解web.xml的配置方式也很重要，比如Servlet的初始化参数（init-param）、过滤器Filter、监听器Listener这些组件的配置，在web.xml里配置仍然是必不可少的。

4.3 访问Servlet并观察执行过程

写好代码以后，如果你想立即看到效果，可以重启Tomcat，因为新添加的Servlet类需要重新编译、部署。重启方式很简单，在IDEA里先点停止按钮，再重新点运行按钮。虽然IDEA有热部署功能，但新类文件往往需要重新部署才能生效，这个我在后面章节会详细讲。

启动成功后，浏览器访问http://localhost:8080/myweb/hello。如果一切正常，你会看到网页上显示“Hello Servlet”和一行说明文字。到这一步，你已经完成了一个完整的Web请求闭环：浏览器发起HTTP请求，Tomcat接收并解析请求，根据URL映射找到HelloServlet类，容器调用它的doGet方法，方法把HTML内容写入响应对象，Tomcat把响应内容发送回浏览器，最后浏览器渲染出来。

可以用一个小实验加深理解：在doGet方法里加一行System.out.println("请求已到达");，然后刷新浏览器页面，你会看到IDEA控制台打印出了这行日志。这个方法非常实用，以后排查问题的时候，可以在Servlet的各个方法里打印日志，结合Tomcat日志判断请求到底走到了哪个环节。

5. 高频报错与排查技巧实录

5.1 启动报404，九成是这七个原因

404大概是Java Web开发中最常见的错误了。很多人一看到404就以为是自己写的代码出问题了，但实际上404的原因要分好几类，我用一张表把常见原因和解决办法列出来，方便你对照排查。

这个表你可以收藏一下，后面遇到问题直接对照排查。从数量上看，第一大坑是没配Deployment或配错了Artifact，第二大坑是Servlet的URL映射没对上，这两个问题占了404的绝大多数。

5.2 中文乱码问题：编码策略要统一

Tomcat开发中乱码是个经典坑，表现形式有多种多样，我在跑通这个项目的过程中也专门做了测试。

第一种是浏览器页面中文显示成问号或菱形乱码。这在Servlet代码里一般是因为响应头没有设置UTF-8编码。解决办法是加resp.setContentType("text/html;charset=UTF-8")，注意这个设置必须在获取Writer对象之前调用，否则不生效。如果你还加了resp.setCharacterEncoding("UTF-8")，这两个方法配合使用效果更好。

第二种是启动Tomcat时控制台出现中文乱码，比如启动日志里提示“找不到属性”之类的告警信息显示乱码。这个不是代码问题，而是Tomcat日志编码和Windows控制台编码不一致导致的，毕竟Windows系统在中文环境下默认代码页是GBK，Tomcat日志默认输出UTF-8，两边就不一致了。解决办法是修改Tomcat安装目录下conf目录的logging.properties文件，找到java.util.logging.ConsoleHandler.encoding这一行，把UTF-8改成GBK，一般就能解决。

第三种是IDEA控制台打印的中文乱码。有时候代码里的System.out.println输出中文，IDEA控制台显示乱码，这需要在IDEA的设置里调整编码，或者检查项目编译编码是不是UTF-8。你可以打开File -> Settings -> Editor -> File Encodings，把IDE Encoding、Project Encoding、Properties Files的编码都统一设置成UTF-8，顺便把右下角的“Transparent native-to-ascii conversion”勾选上。

5.3 端口被占用，项目启动不起来的几种解法

Tomcat默认端口是8080，如果你之前安装过其他服务占用了这个端口，或者上一个Tomcat实例没有完全关闭，IDEA里启动时就会报“Port 8080 was already in use”之类的错误。

排查方法在Windows下用命令netstat -ano | findstr 8080，查看哪个进程占用了8080端口。拿到进程PID之后，打开任务管理器找到对应进程结束掉，或者在命令行执行taskkill /F /PID 进程号。Linux或者Mac系统下用lsof -i:8080，然后kill -9 进程号。

如果你不想关掉占用端口的程序，还有一个更优雅的解决办法：修改Tomcat的端口号。打开Tomcat安装目录下conf目录的server.xml文件，找到Connector配置，把port属性的值从8080改成8081或者你喜欢的其他空闲端口。修改完成后，你会发现IDEA里的Tomcat配置也自动更新了端口号，访问地址也会跟着变。

5.4 IDEA的部署机制和效率问题

最后聊一个特别影响开发效率的点：热部署。在IDEA里，你修改一个Servlet类的方法体，点击Ctrl+F9重新编译后，IDEA会自动把编译产物同步到Tomcat里，这个过程叫热部署。但热部署有时候并不完全好使，比如新增了一个Servlet类，或者修改了web.xml、注解这类配置信息，往往需要重启Tomcat才能生效。

什么情况下需要重启，什么情况热部署能搞定？实际操作经验是：修改Java方法体内的逻辑，热部署通常没问题；但新增类、删除类、修改类名、改Servlet映射路径，这些结构性变更最好还是重启Tomcat。如果项目比较复杂，重启一次要等半天，那建议研究一下DevTools、JRebel这类热部署工具，或者直接上Spring Boot的DevTools，但那是后话了。

我个人的建议是，学习阶段不要过度依赖热部署。每次改完代码，主动重启一次，多观察一下Tomcat的启动日志，这样能加深你对整个部署过程的理解，等熟练掌握之后再去追求开发效率。

5.5 其他容易踩的小坑汇总

再整理几个我这次实操中遇到的小问题，虽然不致命，但遇到了也会让人烦躁。

IDEA右下角可能出现“Unescaped XML or other character expression”这类提示，如果只是写在注解或注释里的特殊字符，一般不影响编译，但最好把代码规范化，用到什么字符就转义什么字符。

Tomcat启动后还会自动打开一个浏览器页面，如果这个页面不是你想看的页面，可以在Run配置里把Open browser改成Because of an error or no browsers are available选项，或者干脆取消自动打开浏览器。这个小习惯能让你更专注于日志输出，而不是被浏览器切换打断思路。

另外，项目名称和Application context如果有中文字符，在有些环境里会导致路径编码问题，建议项目名和context都使用英文小写加连字符的命名方式，比如my-web-app，既符合Java包名的规范，也能减少编码相关的奇奇怪怪的问题。

6. 从“能跑”到“懂跑”：下一步怎么学

到这里，你已经成功地在IDEA 2024中完成了从0到1部署Tomcat并添加Servlet的全过程，这个流程虽然短，但它涉及的知识链条很长：HTTP协议的请求响应模型、Servlet容器的部署机制、Java类的编译打包、IDEA的项目配置结构。每一条线都值得往深了挖。

如果还想继续进阶，我建议按下面的顺序去学习：先完善Servlet代码，比如重写doPost方法接收表单数据，学习如何处理请求参数、设置响应头；然后学习JSP，搞清楚Servlet和JSP的分工；接着学Session和Cookie，理解HTTP无状态特性下怎么保持会话；再往后学Filter过滤器，用Filter解决所有请求的编码、校验等公共问题；最后学习MVC分层思想，看Model、View、Controller分别由哪些组件承担。

在技术选型上，等你掌握了Servlet原生的处理方式，再切换到Spring MVC或者Spring Boot，会发现它的ModelAndView、DispatcherServlet这些概念都有原生Servlet的影子，学起来会轻松很多。不要零基础直接冲Spring Boot，Servlet和Tomcat这些底层原理不具备的话，遇到问题排查起来会特别费劲。

工具层面的学习建议是：多用IDEA的调试功能。你可以在Servlet的doGet方法里打一个断点，然后用浏览器刷新页面，IDEA会在断点处停下来，你可以看到req和resp对象里到底包含哪些数据，这种直观的感受比看十遍文档都有用。

最后再分享一个小技巧：平时多利用浏览器开发者工具里的Network面板查看HTTP请求的详情。当你访问http://localhost:8080/myweb/hello时，你会看到浏览器发出的请求头、URL参数、请求方式等信息，点开响应还能看到状态码和响应头。这个面板能看到Web开发中最底层、最真实的数据流动，是排查问题时最得力的助手之一。

注意：这篇文章里提到的配置方式都是基于Tomcat 9.0.x和IDEA 2024的组合，如果你使用的是Tomcat 10.x版本，需要将文中所有javax.servlet替换成jakarta.servlet，其余操作流程基本一致。

技术这条路就是这样，第一遍跑通觉得难，等跑通了再回头看重难点，会发现其实每一步都有迹可循。希望这篇教程能帮你把环境问题一次搞定，把更多时间留给真正值得研究的代码和原理。