踩坑实战分享如何在 IntelliJ IDEA 中创建一个包含 JSP 和 Servlet6.0 的 Maven Web 项目，并配置 Tomcat 进行调试

在现代 Java Web 开发体系中虽然 Spring Boot 早已成为主流但 JSP Servlet 依然是理解 Web 容器原理、请求响应机制、MVC 分层思想的重要基础。对于初学者来说能够在 IntelliJ IDEA 中从零创建一个包含 JSP 和 Servlet 6.0 的 Maven Web 项目并成功配置 Tomcat 进行调试不仅能打通“开发—部署—运行—排错”的完整链路也能为后续学习 Spring MVC、Spring Boot、微服务架构打下扎实基础。本文讲解以下内容如何在 IDEA 中创建 Maven Web 项目、如何引入 Jakarta Servlet 6.0 依赖、如何编写 JSP 与 Servlet、如何配置 Tomcat 10、如何进行断点调试、如何处理常见报错。文章尽可能覆盖细节让你照着一步步操作就能跑通项目。一、准备工作与版本说明在开始之前需要先明确一个关键事实Servlet 6.0 属于 Jakarta EE 10 规范包名是 jakarta.servlet.*并不再是旧时代的 javax.servlet.*。因此Tomcat 版本也要匹配 Jakarta 命名空间。1. 必备软件JDK 17 或更高版本推荐 JDK 17稳定且兼容性好IntelliJ IDEACommunity 版也可完成主要操作Ultimate 更方便Maven 3.8Tomcat 10.1非常关键Tomcat 9 对应 javax不适配 Servlet 6.02. 版本匹配建议推荐组合JDK17Maven3.9.xServlet API6.0.0JSP APIJakarta JSP 3.1Tomcat10.1.xIDEA2023 或 2024二、在 IntelliJ IDEA 中创建 Maven Web 项目下面正式开始创建项目。1. 新建项目打开 IDEA选择File → New → Project在新建页面中选择左侧MavenJDK选择本机 JDK 17勾选如果有Create from archetype 可以不选直接空项目更清晰点击 Next填写GroupIdcom.exampleArtifactIdjsp-servlet6-demoVersion1.0-SNAPSHOT完成后点击 Finish。2. 调整项目目录结构为标准 Web 结构创建并确认如下目录非常重要textjsp-servlet6-demo ├─ src │ ├─ main │ │ ├─ java │ │ │ └─ com/example/web │ │ ├─ resources │ │ └─ webapp │ │ ├─ WEB-INF │ │ │ └─ web.xml 可选Servlet 6可用注解替代 │ │ └─ index.jsp │ └─ test │ └─ java └─ pom.xml如果 src/main/webapp 没有自动出现可以手动创建。在 IDEA 中右键目录可标记类型Mark Directory as但 Maven 项目通常会自动识别。三、编写 pom.xml引入 Servlet 6.0 与 JSP 依赖下面给出一个可用的 pom.xml 示例。重点是依赖与打包方式xmlproject xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdjsp-servlet6-demo/artifactId version1.0-SNAPSHOT/version packagingwar/packaging properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies!-- Servlet 6.0 API容器提供故 scopeprovided --dependency groupIdjakarta.servlet/groupId artifactIdjakarta.servlet-api/artifactId version6.0.0/version scopeprovided/scope /dependency!-- JSP API通常容器提供这里用 provided --dependency groupIdjakarta.servlet.jsp/groupId artifactIdjakarta.servlet.jsp-api/artifactId version3.1.1/version scopeprovided/scope /dependency!-- JSTL如果你后续 JSP 要用标签库可加入 --dependency groupIdorg.glassfish.web/groupId artifactIdjakarta.servlet.jsp.jstl/artifactId version3.0.1/version /dependency /dependencies build finalNamejsp-servlet6-demo/finalName plugins!-- 编译插件 --plugin artifactIdmaven-compiler-plugin/artifactId version3.11.0/version /plugin!-- WAR 打包插件 --plugin artifactIdmaven-war-plugin/artifactId version3.4.0/version /plugin /plugins /build /project关键解释packaging 必须是 war因为我们部署到 Tomcat。jakarta.servlet-api 必须用 provided否则会和容器内置版本冲突。Servlet 6.0 对应的是 jakarta.* 包名代码里不能再写 javax.*。四、编写 Servlet 与 JSP 页面接下来写最小可运行示例一个首页 JSP一个 Servlet。1. 编写 HelloServlet.java在 src/main/java/com/example/web/ 下新建javapackage com.example.web; 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.time.LocalDateTime; WebServlet(/hello) public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { String username req.getParameter(name); if (username null || username.isBlank()) { username Guest; } req.setAttribute(username, username); req.setAttribute(now, LocalDateTime.now().toString());// 转发到 JSP 展示req.getRequestDispatcher(/WEB-INF/views/hello.jsp).forward(req, resp); } }这里使用了注解 WebServlet(/hello)因此可以不写 web.xml 映射。2. 编写 JSP 页面在 src/main/webapp/WEB-INF/views/ 下新建 hello.jspjsp% page contentTypetext/html;charsetUTF-8 languagejava % !DOCTYPE html html head meta charsetUTF-8 titleHello JSP/title /head body h2Hello, ${username}!/h2 pCurrent Time: ${now}/p pThis page is rendered by JSP Servlet 6.0/p /body /html再在 src/main/webapp/ 下新建 index.jsp 作为入口页jsp% page contentTypetext/html;charsetUTF-8 % !DOCTYPE html html head meta charsetUTF-8 titleHome/title /head body h1JSP Servlet 6.0 Demo/h1 a hrefhello?nameIdea访问 HelloServlet/a /body /html五、是否需要 web.xml两种方式都讲清楚Servlet 3.0 以后就支持注解配置Servlet 6.0 同样支持。所以你可以方式A推荐初学者只用注解 WebServlet不写 web.xml方式B传统方式使用 web.xml 显式配置 servlet 和映射如果你想保留 web.xml可在 WEB-INF/web.xml 写xml?xml version1.0 encodingUTF-8? web-app xmlnshttps://jakarta.ee/xml/ns/jakartaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttps://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd version6.0 display-namejsp-servlet6-demo/display-name /web-app注意 schema 与 version 要和 Jakarta EE 10 / Servlet 6.0 对齐。六、在 IDEA 中配置 Tomcat 进行运行与调试这是最关键的实操环节。1. 添加 Tomcat 服务器菜单进入Run → Edit Configurations...点击左上角 选择Tomcat Server → Local在弹窗中设置NameTomcat10-jsp-servlet6Application server点击 Configure选择你本地 Tomcat 10.1 安装目录JRE选择 JDK 172. 部署 Artifact切换到Deployment选项卡点击 选择 Artifact...选择 jsp-servlet6-demo:war exploded推荐 exploded调试更方便设置 Application context/jsp-servlet6-demo可自定义3. 启动前构建在Before launch中确保有BuildBuild Artifacts如有这样每次启动会先编译项目。七、启动项目并访问测试点击运行绿色三角启动 Tomcat。控制台看到类似日志说明启动成功Server startup in ... msDeploying web application directory ...浏览器访问首页http://localhost:8080/jsp-servlet6-demo/Servlet 页面http://localhost:8080/jsp-servlet6-demo/hello?nameTomcat如果你看到 JSP 渲染的用户名和时间说明项目链路已经跑通。八、如何在 IDEA 里进行断点调试调试是学习 Servlet 生命周期和请求流程的最佳方式。1. 打断点在 HelloServlet#doGet 内点击行号左侧打红点例如javaString username req.getParameter(name);2. Debug 启动不要点 Run改点 Debug小虫子图标。访问 /hello?namedebug 后程序会停在断点处。3. 常用调试操作Step OverF8逐行执行Step IntoF7进入方法内部Resume ProgramF9继续运行Evaluate Expression临时计算表达式你可以观察req.getParameter(...) 如何取值req.setAttribute(...) 如何传递到 JSPforward 与 redirect 的行为差异九、常见错误与解决方案高频踩坑1. ClassNotFoundException: javax.servlet...原因你代码或依赖仍在使用 javax.servlet。解决全部改为 jakarta.servlet并使用 Tomcat 10。2. 404 找不到 Servlet检查顺序URL 是否正确含 context pathWebServlet(/hello) 路径是否匹配Artifact 是否部署成功是否启动的是正确 Tomcat 配置3. JSP 访问 /WEB-INF/... 404这是正常的WEB-INF 下资源不能被浏览器直接访问。正确方式是通过 Servlet forward 转发进去。4. 端口冲突Address already in use8080 被占用。去 Tomcat 配置中改端口例如 8081或释放占用端口。5. 页面中文乱码确保三处统一 UTF-8JSP contentTypetext/html;charsetUTF-8HTML meta charsetUTF-8IDEA 文件编码 UTF-86. Maven 依赖下载慢或失败可配置国内镜像如阿里云 Maven 镜像并检查 IDEA Maven settings 使用的 settings.xml。十、进阶建议让项目更接近真实开发当基础项目跑通后可以逐步增加以下能力引入 JSTL 与 EL 完整视图表达增加 Filter字符编码、登录拦截增加 Listener应用启动初始化引入数据库访问JDBC / MyBatis按 MVC 分层controller/service/dao统一异常处理与日志框架Logback这些实践会让你从“教学 demo”走向“可维护项目”。十一、完整流程回顾速记版你可以把本文浓缩成以下 10 步安装 JDK17、IDEA、Maven、Tomcat10.1IDEA 新建 Maven 项目pom.xml 设置 packagingwar引入 jakarta.servlet-api:6.0.0provided创建 src/main/webapp 与 JSP 页面编写 HelloServlet使用 jakarta.servlet.*可选编写 web.xml 6.0 描述Run Configurations 添加 Tomcat LocalDeployment 选择 war explodedRun/Debug 启动浏览器访问并断点调试在 IntelliJ IDEA 中创建 JSP Servlet 6.0 的 Maven Web 项目看似是一个“传统技术栈练习”但它背后连接的是 Java Web 最根本的运行机制请求如何进入容器、Servlet 如何处理参数、JSP 如何参与视图渲染、Tomcat 如何管理应用生命周期。当你真正把这套流程独立跑通并能调试排错时你对 Java Web 的理解会明显提升。后续无论学习 Spring MVC、Spring Boot还是理解网关、过滤器、拦截器、会话管理都会更轻松。