手把手教你用 Maven 搭建 JavaWeb 项目（避坑版）—— 解决 404 / 文件部署失败问题

一、前言

1.1 为什么选 Maven 做 JavaWeb 项目？

传统 JavaWeb 开发需要手动下载 Servlet、JSP 等依赖包，还要手动导入到项目，容易出现版本冲突、包缺失等问题；而 Maven 作为项目管理工具，能自动管理依赖、统一项目结构、简化打包部署流程，是 JavaWeb 开发的标配。

1.2 新手常见痛点（结合实战踩坑）

我在初次用 Maven 搭建 JavaWeb 项目时，踩了一堆坑：访问 index.jsp 报 404、target/out 目录凭空消失、改了代码页面却没变化、Servlet 配置后访问不到…… 这篇文章会把「从创建项目到成功运行」的全流程讲清楚，还会把这些坑的解决方法融入其中，让新手少走弯路。

二、前置准备

2.1 环境要求

• JDK：推荐 1.8 及以上版本（兼容大部分 Servlet/Tomcat 版本）；
• IDE：IntelliJ IDEA（社区版 / 旗舰版均可）；
• Maven：可使用 IDEA 内置 Maven，或手动安装并配置环境变量；
• Tomcat：9.0 版本（适配 Servlet 4.0，新手友好）。

2.2 环境验证

打开 cmd / 终端，输入以下命令验证环境是否生效：

bash

运行

# 验证 JDK java -version # 验证 Maven mvn -v

若能输出对应版本信息，说明环境配置成功；若提示「不是内部或外部命令」，需检查环境变量是否配置正确。

三、核心步骤：用 IDEA 创建 Maven JavaWeb 项目

3.1 新建 Maven 项目

1. 打开 IDEA，点击「New Project」；
2. 左侧选择「Maven」，勾选「Create from archetype」（基于骨架创建），然后选择org.apache.maven.archetypes:maven-archetype-webapp（这是 Maven 官方的 Web 项目骨架）；
3. 点击「Next」，填写项目信息：
   • GroupId：包名前缀，比如com.example；
   • ArtifactId：项目名，比如javaweb-demo；
   • Version：版本号，默认1.0-SNAPSHOT即可；
4. 点击「Next」，确认 Maven 路径（推荐用 IDEA 内置 Maven，无需额外配置），点击「Finish」；
5. 等待 IDEA 自动下载骨架和依赖，首次创建可能需要几分钟（取决于网络）。

3.2 补全项目目录结构（新手必做）

Maven 骨架生成的目录不完整，需要手动补全：

1. 在src/main目录下新建java文件夹（存放 Java 源码，比如 Servlet 类）；
2. 在src/main目录下新建test/java文件夹（可选，存放测试代码）；
3. 标记目录类型（关键！否则 IDEA 不认）：
   • 右键src/main/java→ 「Mark Directory as」→「Sources Root」（图标变为蓝色）；
   • 右键src/main/webapp→「Mark Directory as」→「Resources Root」（图标变为小地球，解决静态文件部署问题）。

3.3 配置 pom.xml（核心依赖）

pom.xml 是 Maven 项目的核心配置文件，负责管理依赖。在<dependencies>标签内添加 Servlet 和 JSP 核心依赖：

xml

<dependencies> <!-- Servlet 核心依赖 --> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> <!-- 运行时由 Tomcat 提供，避免包冲突 --> </dependency> <!-- JSP 核心依赖 --> <dependency> <groupId>javax.servlet.jsp</groupId> <artifactId>jsp-api</artifactId> <version>2.2</version> <scope>provided</scope> </dependency> </dependencies>

添加后点击右上角「Import Changes」，Maven 会自动下载依赖。

3.4 配置 Tomcat 运行环境

1. 点击 IDEA 右上角「Add Configuration」；
2. 左侧点击「+」，选择「Tomcat Server」→「Local」；
3. 配置 Tomcat 路径：点击「Configure」，选择本地 Tomcat 安装目录，点击「OK」；
4. 切换到「Deployment」标签页，点击「+」→「Artifact」，选择当前项目的xxx:war exploded（热部署模式，改代码无需重启 Tomcat）；
5. 确认「Application context」（项目访问路径，比如/javaweb-demo），点击「OK」。

四、新手避坑指南（实战解决）

4.1 坑 1：访问 index.jsp 报 404

现象

启动 Tomcat 后，访问http://localhost:8080/javaweb-demo/index.jsp报 404 错误。

原因

webapp 目录未被纳入部署包，IDEA 未将 index.jsp 复制到 out/target 目录。

解决方法

1. 确认 webapp 已标记为「Resources Root」；
2. 打开「File」→「Project Structure」→「Artifacts」；
3. 右键「<output root>」→「Add Copy of」→「Directory Content」；
4. 选择项目中的src/main/webapp文件夹，点击「OK」→「Apply」；
5. 重新构建项目：「Build」→「Build Project」。

4.2 坑 2：target/out 目录消失 / 看不到

现象

构建项目后，左侧项目栏找不到 target/out 目录。

原因

IDEA 默认隐藏编译输出目录，并非真的消失。

解决方法

点击左侧项目栏顶部的「齿轮图标」，勾选「Show all files」，即可看到 target/out 目录。

4.3 坑 3：修改代码后页面无变化

现象

改了 index.jsp 或 Servlet 代码，重启 Tomcat 后页面还是旧内容。

原因

IDEA 缓存未刷新，或旧的编译文件未清理。

解决方法

1. 「Build」→「Clean Project」（清理旧编译文件）；
2. 「Build」→「Build Project」（重新构建）；
3. 若仍无效：「File」→「Invalidate Caches / Restart」→「Invalidate and Restart」（清除 IDEA 缓存并重启）。

五、实战测试：写一个简单的 Servlet

5.1 编写 Servlet 类

在src/main/java/com/example下新建RequestLineServlet.java：

java

运行

package com.example; 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; // 配置 Servlet 访问路径 @WebServlet("/RequestLineServlet") public class RequestLineServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { // 设置响应编码，避免中文乱码 resp.setContentType("text/html;charset=UTF-8"); PrintWriter out = resp.getWriter(); // 输出 HTTP 请求相关信息 out.println("请求方法：" + req.getMethod() + "<br/>"); out.println("完整请求URL：" + req.getRequestURL() + "<br/>"); out.println("请求URI：" + req.getRequestURI() + "<br/>"); out.println("请求参数：" + req.getQueryString() + "<br/>"); out.println("客户端IP：" + req.getRemoteAddr() + "<br/>"); out.println("服务器端口：" + req.getLocalPort() + "<br/>"); } }

5.2 运行测试

1. 点击右上角 Tomcat 启动按钮，等待控制台显示「Server started in xxx ms」；
2. 访问http://localhost:8080/javaweb-demo/RequestLineServlet；
3. 若页面显示请求方法、IP、端口等信息，说明 Servlet 运行成功；
4. 若想测试请求参数，访问http://localhost:8080/javaweb-demo/RequestLineServlet?name=张三&age=20，页面会显示「请求参数：name = 张三 & age=20」。

六、总结

1. Maven 创建 JavaWeb 项目的核心是「目录标记 + 依赖配置 + Artifact 部署」，三者缺一不可；
2. 新手遇到 404 优先排查：部署目录（out/target）里有没有对应文件 → Artifact 有没有包含 webapp 目录 → 目录是否标记正确；
3. 缓存问题是 IDEA 高频坑，Clean + Rebuild + 清缓存基本能解决。

Maven 搭建 JavaWeb 项目看似繁琐，但掌握核心逻辑后会非常顺畅。希望这篇文章能帮到刚入门的小伙伴，如果你踩过其他坑，欢迎在评论区交流～

七、附录（可选）

7.1 常用 Maven 命令

bash

运行

# 清理编译文件 mvn clean # 编译源码 mvn compile # 打包（生成 war 包） mvn package

7.2 常见问题 Q&A

Q：依赖下载慢怎么办？A：修改 Maven 镜像为阿里云：打开settings.xml，在<mirrors>标签内添加阿里云镜像配置。Q：Tomcat 启动报端口被占用？A：修改 Tomcat 端口：打开conf/server.xml，把<Connector port="8080">改为 8081 等未被占用的端口。