我这两年被问得最多的一个问题是老师我的JSP项目在IDEA里建出来为什么一运行就404为什么别人的项目长这样我的项目长那样其实这类问题十有八九不是代码写错了而是卡在“项目类型没选对”“Tomcat没接上”“Artifact没部署”这三件事上。所以这篇东西我不打算按官方文档那种“下一步、下一步”的流水账写而是把创建JSP Web项目前后最容易被忽略的底层逻辑挑出来讲清楚。无论你是刚学Java Web的学生、被课程设计难住的初学者还是从Eclipse切换到IDEA的老开发看完基本能对齐一个完整可跑的JSP项目以后再遇到这类问题也不用到处搜。1. 项目创建前先把三个选型问题说清楚1.1 IDEA版本社区版能不能建JSP项目很多人打开IDEA照着教程找New Project里的Java Enterprise入口结果翻了一遍没找到第一反应是“我的IDE坏了”。真不是很可能是版本问题。IDEA区分旗舰版付费和社区版免费。旗舰版内置了完整的企业级开发支持其中就包括Java Enterprise项目模板和Tomcat Server的图形化集成。社区版没有这些东西默认只能创建普通Java项目。如果你用的是社区版就别再找Java Enterprise入口了老老实实走“普通Java项目 手动添加Web框架支持”的路子或者用第三方插件补上Tomcat支持。那是不是社区版就完全不能开发JSP当然不是。你依然可以用社区版写JSP代码只是启动Tomcat、部署应用这些操作需要绕一下——比如手动把项目打包扔到Tomcat的webapps目录或者装一个开源的Smart Tomcat插件。对新手来说我更建议先解决“能不能跑起来”的问题而不是被IDE的版本差异卡住半天。1.2 JDK与Tomcat版本怎么搭配不闹心这是课程作业里翻车率最高的一关而且坑得很隐蔽。Tomcat本身是一个Servlet容器它负责处理浏览器请求、加载你的Servlet和JSP页面。JSP项目写出来之后必须放在Tomcat里才能运行。但Tomcat和JDK的版本是有关联的更重要的是Servlet API的包名在这几年发生过一次大变更。Tomcat 9及以前用的包名是javax.servlet.*而Tomcat 10及以后全面切换成了jakarta.servlet.*。如果你装了Tomcat 10又跟着老教程写import javax.servlet.http.HttpServlet;编译时直接报“程序包不存在”。这不是你代码写错了是规范换名字了。我的建议是如果你是在学习、做课程设计或者参考的是市面上大多数教材用Tomcat 8.5或9.x最省心配JDK 8或JDK 11都行。Tomcat 10适合新项目、Servlet 5以上规范但对新手不友好因为你会遇到大量老教程代码的兼容性报错。组合包前缀适配场景Tomcat 8.5 / 9.x JDK 8/11javax.servlet.*老教材、课程设计、绝大多数学习场景Tomcat 10.0 JDK 11jakarta.servlet.*新规范、新项目、追求最新特性Tomcat 10 javax.servlet代码javax.servlet.*经典翻车组合编译期就会报错1.3 需不需要用Maven或Gradle很多教程会直接带你用Maven骨架创建Web项目然后pom.xml里塞一堆依赖。但你只是想学JSP和ServletMaven反而会成为新的干扰项。IDEA在Java Enterprise模板中会让你选择构建系统有IntelliJ IDEA简单模式、Maven、Gradle三种。我的态度很明确纯学JSP第一次跑通选IntelliJ IDEA就够了。它会生成一个非常简单的项目结构没有pom.xml没有依赖排序问题所有的jar包手动放就行。当你需要引入数据库驱动、JSTL这类第三方库时再切换到Maven不迟。选型想清楚之后接下来进入创建部分。2. IDEA新建JSP项目的两条路径与完整操作2.1 路径一旗舰版用Java Enterprise模板这条路径最省事IDEA会自动帮你把Web目录、web.xml、Web Facet都配好。具体步骤打开IDEA选择New Project左侧选择 Java Enterprise部分版本也叫Jakarta EEProject SDK选择你已经安装好的JDK比如1.8或11在Additional Libraries and Frameworks区域确认Web Application被勾选Build system选择IntelliJ IDEA设置项目名点击Finish。生成后的目录通常是这样项目名/ ├─ .idea/ ├─ src/ ├─ web/ │ ├─ WEB-INF/ │ │ └─ web.xml │ └─ index.jsp └─ 项目名.iml这个结构里src放Java源码web是Web应用的根目录WEB-INF是受保护区域浏览器不能直接访问里面的内容。index.jsp是你访问项目根路径时的默认首页。这个结构基本对应Tomcat的部署格式IDE已经替你铺好了路。2.2 路径二普通Java项目手动添加Web支持这条路径适合社区版也特别适合想理解底层的同学因为你每一步都在手动配置IDE的理解能力。操作如下新建一个普通Java项目New Project → Java项目创建完成后右键项目根目录选择 Add Framework Support在弹出的窗口左侧勾选 Web Application下方勾选 Create web.xml点击OK。完成之后项目里也会出现web/WEB-INF/web.xml和web/index.jsp。不过这时候IDEA还不知道该怎样把项目交给Tomcat后面配置Tomcat和Artifact时要比路径一多花一点心思。说实话我反而建议新手走一遍这条路因为你被迫看到了很多隐藏配置而这些配置在用模板时会被自动隐藏。2.3 创建后先看懂这几个文件再动手无论走哪条路创建完成后先别急着运行打开web/WEB-INF/web.xml看一眼。这是一个Servlet规范要求的部署描述文件在Servlet 3.0以后的版本中它甚至可以不存在但JSP项目里常常还需要它来配置欢迎页。?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 welcome-file-list welcome-fileindex.jsp/welcome-file /welcome-file-list /web-appwelcome-file-list的作用是决定用户访问根路径时优先加载哪个文件。很多人后续遇到404就是这里配置的欢迎页和实际文件名对不上。再看web/index.jsp默认内容% page contentTypetext/html;charsetUTF-8 languagejava % html head title首页/title /head body h1Hello JSP/h1 /body /html这三行JSP指令非常重要。contentTypetext/html;charsetUTF-8告诉浏览器页面是HTML并且用UTF-8编码少了这个最容易出现中文乱码。3. Facet与Artifact理解IDEA的部署心智模型3.1 Web Facet告诉IDE这是一个Web项目很多人建好了项目却从来不打开Project Structure看一眼。其实IDEA管理项目的核心就两个字Facet和Artifact。这两个概念是IDEA的部署模型不懂它们你后面配置Tomcat全靠运气。Facet可以理解成“这个模块具备哪种技术能力”。普通的Java项目只有一个Java Facet表示这个模块能编译Java代码。当我们勾选了Web Application后IDEA会给项目增加一个Web Facet告诉IDE这里多了一个Web根目录里面的静态资源和JSP页面要按Web项目来对待。打开方式File → Project Structure → Facets选中Web右侧能看到Web Resource Directory的设置默认指向web目录或Maven项目的src/main/webapp。如果这里配错了部署时就会出现页面找不到的诡异问题。3.2 ArtifactIDEA是怎么“组织”你的项目的Facet定义的是项目的属性Artifact定义的是“最终要部署出去的那一坨东西长什么样”。在Project Structure → Artifacts里如果是Java Enterprise模板创建的项目通常会默认生成一个以war exploded结尾的条目。为什么叫这个名因为WAR包有两种方式一种是压缩成一个war文件另一种是直接以解压后的目录形式存在。后者就是exploded开发调试时特别方便因为Tomcat可以直接读取目录里的文件改完立即生效不用反复打包。这个Artifact本质上定义了编译后的class放在WEB-INF/classes里web目录下的页面和静态资源按原样复制第三方jar包放进WEB-INF/lib。所以你看lib目录根本不是你自己发明的而是部署模型里约定俗成的一部分。3.3 为什么lib要放WEB-INF/lib这是初学者最不理解的点之一。有人为了放一个MySQL驱动随便在src下建了个lib文件夹结果运行时报ClassNotFoundException一脸懵。Web应用的Java类加载机制规定Tomcat会自动加载WEB-INF/lib下的所有jar包也会加载WEB-INF/classes下的class文件。这两个位置是“官方指定”的运行时目录。src下爱建什么目录都行但编译后不会自动进到WEB-INF/libTomcat自然看不到。如果你用Maven就另当别论Maven会把依赖打包进WEB-INF/lib逻辑是一样的。记住这个就好办手搭项目时第三方jar一律放到web/WEB-INF/lib下。3.4 关于web.xml的缘分还有一个隐藏细节IDEA添加Web支持时如果没勾选Create web.xml项目里就没有这个文件。这不是错误Servlet 3.0之后允许用注解来代替XML配置比如写一个Servlet直接用WebServlet(/hello)。但对初学者来说我建议还是保留web.xml因为排查404时多一个可配置的可视化入口而且许多老教程的代码还是基于XML配置的。4. 把Tomcat接进来从Run Configuration到热部署4.1 下载和解压TomcatTomcat是绿色软件官网下载对应版本的核心zip包解压到一个路径没有中文、没有空格的目录里就行。比如D:\apache-tomcat-9.0.80。解压后目录里有bin、conf、lib、logs、webapps等文件夹无需安装。你可以双击bin/startup.bat手动启动并访问http://localhost:8080看到Tomcat默认首页但既然用了IDEA咱们直接在IDE里管理它更好。4.2 在IDEA里添加Tomcat Server旗舰版的操作路径是点击顶部工具栏的运行配置下拉框选择 Edit Configurations左上角点 往下找 Tomcat Server → Local第一次配置需要点击 Configure选择你本地Tomcat的根目录IDEA会自动识别版本填写Name比如Tomcat9。这里有个容易卡住的地方如果你的IDEA里找不到Tomcat Server这个选项或者整个配置列表里都没有应用服务器相关的项多半是当前项目没有任何Web FacetIDEA不会把这个选项显示出来。先去确认Web Facet已经配置好再回来添加Tomcat。4.3 部署Artifact并设置访问路径添加完Tomcat Server后还没完你需要在同一窗口里配置Deployment。切到Deployment页签点 → Artifact选择那个以war exploded结尾的条目。如果不添加Tomcat就算启动了打开的依然是Tomcat默认首页而不是你的项目页面。Server页签里有两个值得看的参数HTTP port默认8080如果端口被占用可以改成8081等Application context访问项目的根路径。默认常常是项目名我习惯改成/这样直接访问http://localhost:8080/就能看到首页如果改成/demo那就得访问http://localhost:8080/demo/。4.4 热部署改代码不用反复重启同一个配置界面里还有两个下拉框很多人永远保持默认其实它们决定了你的开发效率。On Update action指的是你手动触发Update按钮时执行的操作建议改成Update classes and resources意思是更新类和静态资源而不是重启服务器。On frame deactivation指的是IDEA窗口失去焦点时执行什么操作比如你切换到浏览器的一瞬间建议也改成Update classes and resources。这样每次改完JSP直接切到浏览器改动就能生效。但要注意一个细节对Java类的热更新IDEA在Debug模式下更可靠因为它可以通过JVM的HotSwap机制替换已经加载的类。如果你用普通Run模式运行时修改了Servlet方法体点Update不一定生效得重启Tomcat。所以开发阶段我推荐以Debug模式启动Tomcat不要用Run。这个习惯能为你每天省下大量重启等待的时间。5. 第一次运行的完整链路与高频故障排查5.1 JSP是怎么变成Servlet被执行的先把运行机制聊明白你排查问题时才会有方向感。你访问http://localhost:8080/时Tomcat返回的看起来是一个JSP页面但JSP本身并不是浏览器能直接理解的东西。它实际上在服务端被翻译成了一个Java类——一个Servlet。具体顺序是Tomcat把index.jsp读进来先翻译成一个index_jsp.java文件再编译成index_jsp.class然后实例化并调用它的_jspService()方法把拼接好的HTML输出给浏览器。因为翻译成Java代码需要时间所以你第一次访问JSP时通常会比后续访问慢这是正常现象。你可以去Tomcat安装目录下的work\Catalina\localhost\项目名_war_exploded\org\apache\jsp里看到生成的中间文件。看到它你对JSP的印象会彻底改变JSP就是反过来的Servlet一种方便写HTML的Servlet模板。5.2 打开页面是Tomcat默认首页或404现象原因处理方式访问根路径是Tomcat小猫首页Deployment没有添加Artifact在Run Configuration的Deployment里添加war exploded页面404但Tomcat已启动Application context与访问路径不匹配确认你访问的URL是否包含上下文路径页面404且控制台无报错欢迎页文件名不对或路径不对检查web.xml的welcome-file是否等于实际页面访问Servlet返回404Servlet映射没有生效检查WebServlet注解路径或web.xml中的servlet-mapping这里最容易被忽视的就是Application context。我把根路径设置为/时一切正常一旦有人改成了/web_war_exploded这类长串他又不记得访问完整路径自然看到404。排查时先看访问的URL和配置的上下文是否一致。5.3 端口占用8080被别的进程占用了启动Tomcat时如果控制台报类似Address already in use: JVM_Bind null:8080的信息说明8080端口已经被占用。处理方式无非两种找出占用进程杀掉或者改IDEA里的HTTP port端口。Windows下在命令行执行netstat -ano | findstr 8080然后用taskkill /PID 进程号 /F结束进程。macOS或Linux下则是lsof -i :8080端口占用不一定是你之前残留的Tomcat也可能是别的服务。我遇到过不少次是Vue的调试服务占用了8080后来干脆把Tomcat的端口统一改成9090省得互相打架。5.4 中文乱码的完整修复思路JSP的中文乱码问题由三个环节可能导致页面输出、URL参数传递、控制台日志。不同场景的修复方式不同别一种方法包打天下。乱码场景常见原因处理方式页面输出中文显示成问号JSP未声明UTF-8或文件本身不是UTF-8编码JSP头部加contentTypetext/html;charsetUTF-8设置IDEA File Encoding为UTF-8URL传参中文乱码客户端与容器的编码不一致Tomcat 8.0以上默认UTF-8老版本改conf/server.xml的Connector加URIEncodingUTF-8IDEA控制台日志中文乱码JVM默认编码非UTF-8Run Configuration的VM options加-Dfile.encodingUTF-8数据库读写乱码JDBC连接URL未指定字符集连接串加useUnicodetruecharacterEncodingUTF-8页面乱码是最高频的问题。记住三件事JSP页面第一行写上% page contentTypetext/html;charsetUTF-8 languagejava %IDEA右下角把文件编码改成UTF-8然后在File → Settings → Editor → File Encodings里把项目编码和属性文件编码统一改成UTF-8。这三处一致后页面乱码基本不会出现。5.5 缺Servlet API依赖的经典报错新手手动建项目后写一个Servlet类编译时报程序包javax.servlet不存在。这不是你写错而是项目里根本没引入Servlet API。解决办法也很直接打开Project Structure → Modules → Dependencies点 添加Application Server Library选中Tomcat对应的库。这样编译时就能找到javax.servlet和javax.servlet.http这些包了。但注意不要为了图省事把Tomcat目录下lib里的servlet-api.jar复制到WEB-INF/lib下。Tomcat运行时会自己提供Servlet API如果在WEB-INF/lib里再放一份可能产生类加载器之间的冲突出现一些特别奇怪的错误。让依赖留在Tomcat那层项目里只需要能编译即可。另外一个和版本强相关的坑是你在写Servlet时用了javax.servlet但Tomcat是10.x运行时直接抛NoClassDefFoundError原因是Tomcat 10已经把javax改成jakarta了。所以再次强调跟着老教程走就用Tomcat 9。6. 从“能跑”到“好维护”几个忠告6.1 尽早用包结构管理代码初学者很容易把Servlet建在默认包default package里。这确实能跑但后续写多了你会发现自己变成在“文件夹里翻垃圾”。建议从一开始就养成建包的习惯比如com.example.web把Servlet和Filter按功能分开放。IDEA里右键src→ New → Package非常方便。6.2 用注解替代部分web.xml配置如果你是跟着老课程学web.xml的应用那没问题。但自己写新Servlet时我推荐直接用注解package com.example.web; 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 from Servlet/h1); } }WebServlet(/hello)把URL路径直接绑到Servlet上省去web.xml里一对对servlet和servlet-mapping配置。这种写法是Servlet 3.0之后的规范IDEA对它的支持也很好写好直接重启Tomcat就能访问。6.3 项目演进到Maven的时机如果你发现自己在手工下载一堆jar包、手动复制到WEB-INF/lib说明该上Maven了。Maven可以自动帮你下载依赖、管理版本、打包war。切换的方式也不难在项目根目录右键添加Frame Support选择Maven或者在现有项目里手动生成一个pom.xmlIDEA会自动识别。但我不建议学习初期就切换。JSP阶段最应该掌握的是Servlet生命周期、请求响应流程、内置对象这些底层概念。把这些搞明白再接触Maven、Spring Boot你会觉得一切都顺理成章。反过来如果一开始就陷在Maven依赖冲突、仓库下载失败这些环境问题里你很难分辨到底是自己代码的问题还是工具的问题。6.4 我最推荐的组合最后说一下我个人给学生、朋友和那些私信求助的读者最常推荐的组合IDEA旗舰版 JDK 8或11 Tomcat 9 IntelliJ IDEA构建系统。这个组合和大多数教材、课程设计模板兼容代码里的javax.servlet.*都是可用的网上搜到的老帖子、老博客基本都能照着抄。项目跑通之后可以试着写一个小功能做闭环一个Servlet接收表单参数往Session里存数据再转发到一个JSP页面显示。这样一个二十行代码的小项目能把Servlet、JSP、请求转发、Session、部署配置这些核心点全部串起来。我记得当年自己第一次让这个流程跑通时对Java Web的很多疑问一下子都通了。我的体会是新建一个JSP项目在IDEA里从来不是什么高深技术难点集中在版本选择、部署模型和Tomcat的关联这三件事。只要这三点想明白了后面出现任何报错你至少能判断出它在整个链路里的位置不会像无头苍蝇一样乱改。希望这篇经验对你有用。