我当年学Java Web的时候卡得最久的一步不是在Servlet语法上而是不知道怎么在IDEA里把一个Servlet程序真正跑起来。网上的教程东一个版本西一个版本有说要用Maven的有说直接建Web项目的结果照着操作了半天浏览器永远是一行404。现在回头看问题主要出在“工具版本”和“项目结构”这两件事上。这篇文章用两种方法来创建Servlet项目一种是不依赖Maven的轻量方式适合新手先跑通Demo另一种是Maven标准Web工程更接近真实企业开发。无论你现在用IntelliJ IDEA的免费社区版还是付费版只要JDK和Tomcat装好都能照着一步步做出来。文章最后还会把404、端口占用、中文乱码这类高频问题整理成速查表方便你排错。1. 动手之前先把Servlet和这次要用到的工具链捋清楚1.1 Servlet在Web开发里到底扮演什么角色很多零基础同学第一次接触Servlet听到“服务端小程序”这种官方解释就懵了。我习惯用餐厅来打比方浏览器是客人Tomcat是前台服务员Servlet是后厨的厨师。客人点菜服务员收单子厨师按菜单做菜做完再由服务员端上桌。具体到一次访问的流程里你在浏览器输入一个地址、按下回车这个HTTP请求先到达Tomcat。Tomcat从请求URL里判断出你要找哪个Servlet然后实例化它并调用对应的方法。Servlet方法里可以读取浏览器传过来的参数、查询数据库、做业务运算最后生成一段HTML文本通过HTTP响应原样返回给浏览器。浏览器再把这段HTML渲染成你看到的页面。这里的核心认知是没有Servlet的Tomcat只是一个静态文件服务器它只能把webapps目录下的HTML、图片原样发给浏览器做不到根据用户输入动态生成内容。有了ServletJava程序才真正参与到每一次HTTP请求-响应过程中这也是Java后端开发的起点。1.2 一句话分清IDEA、Tomcat、Servlet的关系新手最容易产生的困惑是这三个东西到底谁负责谁我见过不少同学在IDEA里点了运行按钮结果弹出一个普通Java程序的控制台而不是Tomcat启动日志就是没搞清楚它们的协作方式。用一句话概括IDEA负责写代码和编译把.java变成.class文件Tomcat负责接收HTTP请求、加载Servlet并执行它是一个独立的Web服务器程序Servlet是运行在Tomcat里的Java类负责具体的业务处理。IDEA并不会“直接运行”Servlet。你点运行按钮本质上是IDEA帮你启动了Tomcat并且把项目部署到Tomcat里。Tomcat启动后监听端口有请求进来就分发给对应的Servlet。理解了这个关系后面配置Smart Tomcat、配置Web项目结构时你就知道每一步在干什么了。1.3 版本说明JDK、Tomcat、IDEA怎么搭配最省事我在这里直接给一套经过验证的稳定搭配新手照着装就行JDK1.88或者11都可以建议8网上教程资料最多Tomcat9.x版本这个版本使用javax.servlet包名和绝大多数教程保持一致IDEACommunity Edition社区版免费且功能足够不需要碰任何付费破解相关的东西如果你不小心装了Tomcat 10或11注意Servlet的包名会变成jakarta.servlet老教程里的import javax.servlet会报错这就是为什么我推荐Tomcat 9。版本之间没有强绑定但“JDK8 Tomcat9 IDEA社区版 javax.servlet”这一套是目前最不容易出错的新手组合。确认版本匹配能帮你省掉大量“明明是照着做的却报错”的时间。2. 准备环境IDEA和Tomcat一个都不能少2.1 下载安装IDEA社区版去JetBrains官网下载Community版安装包。社区版是开源免费的正版软件功能足够支撑Java Web学习和绝大多数日常开发如果以后做企业级JavaEE开发需要专业版Studio会有提供官方免费的试用或教育授权但我个人建议学生阶段先把社区版用熟再决定要不要换。安装时我建议勾选“Create Desktop Shortcut”和“Add to PATH”后者能让你之后在命令行直接使用IDEA的一些工具命令。安装完成后打开IDEA首次启动会让你选择主题和快捷键方案默认就可以主题选自己喜欢的即可不影响写代码。新版IDEA默认英文界面不需要急着汉化。因为后续配置Tomcat、查看日志、搜索插件时你迟早要跟英文菜单打交道把英文界面当学习过程反而省事。2.2 下载并验证Tomcat去Apache Tomcat官网下载Tomcat 9的Windows zip版解压到一个没有中文、没有空格的目录比如D:\dev\tomcat9。解压后目录里会有bin、conf、lib、webapps等文件夹这些目录各司其职先不用全部理解只要知道bin里放启动脚本、webapps里放部署的项目就行。验证Tomcat能不能跑起来进入bin目录双击startup.bat。如果看到控制台输出“Server startup in…”之类的日志说明启动成功。打开浏览器访问http://localhost:8080能看到Tomcat默认首页就正常了。关闭Tomcat再运行shutdown.bat或者直接关掉启动窗口。这里有个小坑Tomcat启动窗口如果闪退大概率是环境变量里的JAVA_HOME没配好。Tomcat本身不需要CATALINA_HOME但必须能找到JAVA_HOME。你在系统环境变量里新建一个JAVA_HOME指向JDK安装目录比如C:\Program Files\Java\jdk1.8.0_211然后再启动Tomcat就能成功。2.3 确认IDEA里的JDK配置打开IDEA进入File - Project Structure确认左侧Project里的Project SDK指向你安装的JDK。如果没有点New...选择JDK目录。这一步不做好后面写Servlet时会提示找不到javax.servlet相关的类导致无法编译。到此开发环境已经准备完毕。整个过程不做任何多余配置目标只有一个让IDEA能写代码、让Tomcat能启动。接下来进入两种创建Servlet项目的实操环节。3. 方法一IDEA Smart Tomcat 快速创建Servlet项目3.1 新建普通Java项目并手动搭建Web目录这个方法的核心思路是不用IDEA自带的JavaEE框架支持也不用Maven完全手动搭一个Tomcat能认的目录结构。它的优点是对新手极度友好你能看清Servlet项目最底层的组织方式。打开IDEA点击New Project左侧选择“Empty Project”或者“Java”给项目起名servlet-demo。如果是空项目需要先新建一个Module选Java模块。这一步完成之后你得到一个普通Java项目没有web目录没有web.xml什么都没有。接下来手动补目录结构。在项目根目录下新建一个web文件夹再在web下新建WEB-INF文件夹。最终结构长这样servlet-demo ├── src │ └── com │ └── example │ └── servlet │ └── HelloServlet.java └── web └── WEB-INF为什么要建web目录因为Tomcat把每个Web应用看作一个带特定结构的目录web目录就是部署根目录。浏览器访问时根路径对应这个目录里面的文件可以对外访问而WEB-INF是Tomcat约定的受保护目录外部浏览器直接访问不到用来放web.xml、编译后的Class文件等内部资源。3.2 编写第一个Servlet类在src下创建一个包com.example.servlet然后在包里新建类HelloServlet让它继承HttpServlet。完整代码如下package com.example.servlet; 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; WebServlet(/hello) public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(h1我的第一个Servlet程序/h1); resp.getWriter().write(p请求方式 req.getMethod() /p); resp.getWriter().write(p当前时间 new java.util.Date() /p); } Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { doGet(req, resp); } }逐行解释一下这段代码在做什么。WebServlet(/hello)是Servlet 3.0引入的注解作用是把当前类和URL路径/hello绑定起来。tomcat启动时扫描到注解就知道当浏览器请求/hello路径时要调用这个类。extends HttpServlet意味着我们不需要实现Servlet接口的全部方法只需要重写关心的doGet和doPost。doGet处理GET请求doPost处理POST请求这里我把doPost直接转发给doGet方便表单提交时也能用同一套逻辑。setContentType是新手最容易忽略的一行。HTTP响应必须告诉浏览器数据类型和编码text/html;charsetUTF-8表示返回的是HTML文本使用UTF-8编码。少了这行浏览器可能把中文显示成乱码。3.3 安装Smart Tomcat插件IDEA社区版默认没有Tomcat集成入口需要装一个第三方插件Smart Tomcat。打开File - Settings - Plugins切到Marketplace页签搜索“Smart Tomcat”点Install安装然后重启IDEA。这个插件的作用相当于帮社区版补上了Tomcat集成能力。它能自动把项目class文件复制到web/WEB-INF/classes目录下启动Tomcat并加载你的项目。你只需要把项目目录告诉它剩下的部署工作插件自动完成。安装完插件后点击菜单栏Run - Edit Configurations左上角加号选择Smart Tomcat就能看到配置界面了。这也是我推荐这个方法给新手的原因不用敲命令不用手动复制文件全程图形化点击操作。3.4 配置Smart Tomcat并启动项目在Smart Tomcat配置界面里有四个核心字段需要填Name随便写比如ServletDemoTomcat Server点击Configure选择你的Tomcat 9解压目录比如D:\dev\tomcat9Context Path填/servlet-demo这个代表项目对外访问的根路径Deployment Directory选择项目的web目录也就是你手动建的那个部署根目录。其他配置保持默认点击Apply和OK保存。接下来点击IDEA工具栏的绿色运行按钮看到控制台输出Tomcat启动日志同时出现Starting ProtocolHandler [http-nio-8080]之类的内容说明部署成功。浏览器访问http://localhost:8080/servlet-demo/hello你就能看到页面显示“我的第一个Servlet程序”以及请求方式和当前时间。这里的URL拼接逻辑是http://localhost:8080是Tomcat地址前缀/servlet-demo是Context Path对应项目访问前缀/hello来自WebServlet(/hello)注解。三者缺一不可后面遇到404时也照这个思路排查。3.5 方法一的局限性与定位方法一优点在于足够简单能让你把注意力全部集中在Servlet代码本身。但它也有明显短板手动维护目录结构很麻烦项目一复杂依赖的第三方jar包不知道往哪里放目录规范全凭自觉不适合团队协作。所以我把它定位成“新手第一课”目的就一个——先跑通一个最小Web程序建立“请求→Tomcat→Servlet→响应”的完整认知。等你理解了这套流程再切换到第二种方法Maven标准工程就不会觉得Maven是个黑盒了。4. 方法二用Maven创建标准Servlet Web项目4.1 为什么企业开发几乎都用Maven方法二要请出Maven。Maven是Java界的项目管理与构建工具它解决了两大痛点依赖管理和标准化目录结构。依赖管理指的是你不需要手动下载、复制jar包到WEB-INF/lib目录只要在pom.xml里声明依赖坐标Maven会自动从中央仓库下载并管理版本。标准化目录结构则让每个Java项目的目录长得一样新同事接手项目时不需要看文档就能快速定位代码位置。真实的企业项目里几乎没有纯手工维护目录的Servlet项目Maven就是标配。所以我在方法一跑通之后建议立刻切换到方法二把它彻底吃透。4.2 在IDEA中创建Maven Web项目打开IDEA点击New Project左侧选择Maven勾选“Create from archetype”在archetype列表里找到org.apache.maven.archetypes:maven-archetype-webapp。这个骨架会生成一个标准Web项目最基础的模样包含src/main/webapp目录和web.xml文件。需要填写GroupId通常是公司域名倒写比如com.example、ArtifactId项目名比如servlet-demo、Version默认1.0-SNAPSHOT即可。点Finish后IDEA会开始下载Maven依赖第一次构建会慢一些底部状态栏能看到进度条耐心等它跑完。生成的项目里可能没有src/main/java目录因为webapp骨架默认只建了资源目录。你需要手动创建这个目录右键src/mainNew - Directory输入java并回车然后右键这个java目录选择Mark Directory as - Sources Root告诉IDEA这里是源码根目录。这一步不做好之后新建Servlet类时IDEA不会把它当成源码编译。最终目录结构如下servlet-demo ├── pom.xml └── src ├── main │ ├── java │ │ └── com │ │ └── example │ │ └── servlet │ │ └── HelloServlet.java │ └── webapp │ ├── WEB-INF │ │ └── web.xml │ └── index.jsp └── test4.3 在pom.xml里配置Servlet依赖用Maven项目所有第三方库都要在pom.xml里显式声明。打开项目根目录的pom.xml在dependencies标签内加入Servlet API依赖dependencies dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency /dependencies这里的scope设置为provided值得多说一句。它表示编译时需要这个jar但部署运行时不打包进项目里因为Tomcat自身已经提供了servlet-api的实现。如果改成默认的compile打包出的war包里会带上servlet-api反而可能和Tomcat自带的版本冲突引发各种奇怪问题。这是新手比较容易忽略的细节。设置完成后IDEA会自动下载依赖。右下角出现Maven导入进度等待完成。此时你再写import javax.servlet.http.HttpServlet就不会再报红了。4.4 编写Servlet并配置web.xml映射在src/main/java/com/example/servlet下新建一个HelloServlet类代码逻辑和方法一里完全一样依然使用WebServlet注解。这里我先演示注解方式package com.example.servlet; 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; WebServlet(/hello) public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(h1Hello Maven Servlet/h1); } }同时打开src/main/webapp/WEB-INF/web.xml把骨架自带的旧版本声明替换成Servlet 4.0的完整配置并通过servlet和servlet-mapping实现URL映射?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd version4.0 servlet servlet-nameHelloServlet/servlet-name servlet-classcom.example.servlet.HelloServlet/servlet-class /servlet servlet-mapping servlet-nameHelloServlet/servlet-name url-pattern/hello/url-pattern /servlet-mapping /web-app你可能发现我同时用了注解和web.xml两种方式。在真实项目里这两种方式可以共存同一个Servlet如果同时被注解和web.xml映射web.xml的优先级更高。但为了新手理解源码的逻辑我建议先用注解再对比看一下web.xml里的写法搞清楚servlet-name、servlet-class、url-pattern三者的对应关系。这段web.xml的作用本质上就是告诉Tomcat名字叫HelloServlet的类对应com.example.servlet.HelloServlet访问/hello这个路径时去调用它。老项目里没有注解所有映射都写在web.xml里所以面试时被问老项目结构你至少要看得懂这段配置。4.5 运行Maven Web项目Maven项目跑起来有两种常见方式这里都演示一下。方式一继续用Smart Tomcat插件。在Edit Configurations里新建Smart Tomcat配置Distinct目录选择src/main/webappContext Path填/servlet-demoTomcat Server仍然指向Tomcat 9安装目录。启动后访问http://localhost:8080/servlet-demo/hello。这种方式和方法一的区别仅在于项目目录运行逻辑完全一致。方式二使用Maven Tomcat插件。在pom.xml中配置build plugins plugin groupIdorg.apache.tomcat.maven/groupId artifactIdtomcat7-maven-plugin/artifactId version2.2/version configuration port8080/port path/servlet-demo/path uriEncodingUTF-8/uriEncoding /configuration /plugin /plugins /build配置好之后在IDEA右侧Maven面板里找到Plugins - tomcat7 - tomcat7:run双击运行。或者在项目根目录打开命令行执行mvn tomcat7:run。控制台出现“Starting ProtocolHandler”就说明启动成功访问路径同样是http://localhost:8080/servlet-demo/hello。需要说明的是这个插件内置的是Tomcat 7内核虽然名字带7但跑Servlet 3.0、注解映射这些四平八稳的功能完全没问题。适合本地快速验证不适合生产环境。4.6 Maven标准项目的核心优势方法二相比方法一最大的变化是目录结构被Maven约定死了不能再随心所欲。这种“约定优于配置”的理念一开始可能让新手觉得束缚但过了适应期你会发现它的好处源码、资源、测试、部署目录各归其位项目再大也不会乱依赖jar包由Maven统一管理不会出现“我本地能跑别人电脑跑不了”的依赖问题可以配合后续的Spring Boot、MyBatis等框架它们的官方文档默认都是Maven项目。合作关系里后端框架全家桶全部基于Maven所以方法二是长期必选项。5. 两种方法怎么选逐项对比与建议5.1 对比表格为了看得清爽我把两种方法的差异整理成下表对比维度方法一手工Web目录 Smart Tomcat方法二Maven Web工程项目结构手动创建简单灵活Maven标准结构统一规范第三方依赖手动下载jar复制到WEB-INF/libpom.xml声明自动下载创建速度快无需等待依赖下载首次较慢需要联网拉依赖学习成本低适合理解底层目录中需要了解Maven基础运行方式Smart Tomcat配置即可Smart Tomcat或Maven插件团队协作不方便依赖管理混乱标配适用于真实项目适合场景练手Demo、理解原理企业项目、后续框架学习5.2 我的建议路线如果你是完全零基础我的建议是按照“方法一 → 方法二”的顺序走。先手动搭一个最小项目亲手建立目录、写Servlet、用Smart Tomcat跑起来这个过程能让你对Web项目结构有最直观的体感。然后再切换到Maven标准工程你会发现之前手工做的事Maven都帮你自动化了理解起来事半功倍。如果你已经在带你的团队里见过Maven项目或者时间比较紧可以直接用方法二但一定要自己动手把pom.xml里的依赖配置写一遍把Smart Tomcat和Maven插件的运行方式各跑一次。只有亲手踩过一遍坑后面学习Spring Boot时才不会因为不会配Maven而卡壳。还有一点补充说明如果你用的是IDEA专业版New Project里面会有Java Enterprise的选项可以直接创建带Web支持的Servlet项目原理上和方法一的目录结构类似。但既然是求稳的教程我建议新手哪怕用专业版也按这里说的方法走一遍一来能理解目录结构的来龙去脉二来以后遇到团队项目各种奇怪结构也不慌。6. 新手常见问题速查与排错实录6.1 最经典的404URL路径没对上404是新手遇到最多的问题。浏览器显示404时你心里要有一根排查链条第一Tomcat是否真的启动了看控制台有没有启动日志没有的话先解决启动问题。第二Context Path是否正确在Smart Tomcat里你填的是/servlet-demo那么URL中间这一段必须是它。第三Servlet映射路径是否正确如果用注解WebServlet(/hello)URL末尾必须是/hello如果用web.xml检查url-pattern里的值和Servlet类是否匹配。第四项目是否成功部署Smart Tomcat配置里的Deployment Directory如果选错了目录Tomcat加载不到项目访问路径下面整个资源都不存在。这四条按顺序排查下来80%的404都能解决。唯一例外是404页面是Tomcat默认的猫咪页面说明Tomcat正常但项目没部署进去重点查部署目录。6.2 IDEA控制台报错端口被占用Tomcat默认监听8080端口如果报错信息里有Port 8080 required by Tomcat v9.0 Server is already in use说明端口被别的程序占用了。在Windows命令行里执行netstat -ano | findstr :8080最后一列是占用端口的进程PID再执行taskkill /PID 对应的PID /F就能强制结束占用进程。注意看杀掉的进程是不是别的项目免得误伤。也可以直接改Tomcat的conf/server.xml把Connector port8080改成8081但要记得每次访问URL也跟着变。6.3 页面中文变成问号或乱码乱码几乎都是编码不一致造成的。你需要检查三处项目文件编码、HTTP响应编码、浏览器解析编码。IDEA中进入File - Settings - File Encodings把Global Encoding、Project Encoding、Default encoding for properties files都设成UTF-8。代码里的setContentType必须写成text/html;charsetUTF-8这一行能保证响应头告诉浏览器用UTF-8解析页面。如果用Maven Tomcat插件URL里的中文参数可能出现乱码在插件配置里加一行uriEncodingUTF-8/uriEncodingTomcat自带的URI默认解码格式才能正确识别中文。6.4 编译报错程序包javax.servlet.http不存在这个报错说明项目编译时找不到Servlet API。重点检查两点一是pom.xml里有没有添加servlet-api依赖依赖的scope是不是provided二是Maven依赖有没有真正下载成功看右侧Maven面板里Dependencies下有没有对应的jar。如果IDEA报红色波浪线按AltEnter选择Add Maven dependency或者手动去pom.xml里补充依赖。方法一手动建目录的项目如果出现这个报错是因为项目没有Tomcat运行库。你需要手动找到Tomcat安装目录下的lib/servlet-api.jar通过File - Project Structure - Libraries添加进去或者干脆切换到方法二的Maven方式。6.5 修改代码后刷新页面没变化新手经常遇到这个问题Servlet代码改了一行浏览器刷新还是旧结果。原因很简单——没有重新编译部署。在IDEA里点击Smart Tomcat的运行并不会自动热部署所有改动。修改代码后需要先停止Tomcat红色方块按钮再重新点运行按钮。如果你装了JRebel这类热部署插件可以热更新但对于新手学习阶段我建议手动重启养成“改完代码重新编译部署”的习惯也避免以后误以为每次改动都会自动生效。6.6 访问出现“源服务器未能找到目标资源的表示”或者看到JSP源码这种情况通常是部署目录指错了。Smart Tomcat插件配置的Deployment Directory如果指向了src而不是web或src/main/webappTomcat会把源码目录当部署根目录自然就找不到WEB-INF下的资源或返回不了正确的Servlet。检查配置把部署目录改到真正的Web部署目录即可。我把这些高频问题整理成一张速查表方便你对照现象常见原因解决方案404URL路径/部署目录错误按CTX路径→映射路径→部署目录顺序排查端口占用8080被其他程序占netstat查PIDtaskkill杀进程或改端口中文乱码编码不统一文件编码、setContentType、URIEncoding都设UTF-8缺少HttpServlet类没加入Servlet API依赖pom.xml加provided依赖或本地导入jar改了没效果没重新编译部署停止Tomcat后重新运行看到源码部署目录指错修正Deployment Directory个人经验是这些报错本身并不可怕可怕的是新手看到一个英文报错就开始慌然后全盘推翻重来。遇到问题先看控制台红字把它复制到搜索引擎里十有八九能找到答案。实在不行把Web目录结构截图、pom.xml内容贴出来社区里很多热心人会帮你。我一直觉得学Servlet的正确姿势不是把它背熟而是亲手把它从零跑起来。两种方法里我更推荐你先用方法一快速体验一下“网页上出现自己写的动态内容”的成就感然后再扎进方法二里把Maven顺手学会。等你跑通了这两个项目再回头看Servlet生命周期、Filter、Session这些概念会轻松很多。我自己当年就是因为在一个404上卡了两天才决定把环境搭建和项目骨架这部分彻底搞明白后面学Spring时基本没在项目结构上再栽过跟头。希望这篇教程能帮你跨过同样的坎。