企业官网建设流程全解析

IDEA里创建JavaWeb项目，看似就是“新建项目→写代码→部署到Tomcat”三步的事，但很多初学者甚至工作一两年的同事，都容易在环境配置、目录结构、Tomcat部署这几个环节上卡住。这篇文章我就从实战角度，把IDEA创建JavaWeb项目的完整链路拆开讲一遍：从新建项目骨架，到补齐目录、配置Tomcat、跑通Servlet，再到处理那些一踩一个准的坑，尽量让照做的朋友能少走弯路。

这篇文章适合这么几类人看：刚接触JavaWeb的学生、从其他语言转Java的开发者，以及一直被各种教程绕晕、想搞清楚每一步“为什么这么干”的人。我会把关键操作和参数背后的原因也一并交代清楚，而不是只给一串“照着点”的步骤。好，直接进入正题。

1. 项目骨架与核心思路

1.1 JavaWeb项目的经典目录结构

在动手创建之前，先理解一个JavaWeb项目长什么样，后面操作会顺利很多。这里说的JavaWeb项目，最经典的结构是Maven约定的结构：

project-name/ ├── pom.xml ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/demo/ │ │ │ └── HelloServlet.java │ │ ├── resources/ │ │ └── webapp/ │ │ ├── WEB-INF/ │ │ │ └── web.xml │ │ └── index.jsp │ └── test/ │ └── java/

先别急着背，理解每个目录的作用：

• src/main/java：Java源码目录，存放Servlet、service、dao等业务代码。
• src/main/resources：资源文件目录，放配置文件，比如数据库连接配置文件、日志配置，这些文件最终会被打包到classpath根路径下。
• src/main/webapp：Web内容目录，放JSP、HTML、CSS、JS、图片等静态资源，以及WEB-INF目录。
• WEB-INF：这个目录比较特殊，它下面的文件对外部浏览器不可直接访问，只能通过服务器内部转发访问，适合放web.xml和一些不想暴露的页面资源。
• pom.xml：Maven的项目描述文件，管理依赖、插件、打包方式等。

这个结构不是IDEA随便生成的，而是Maven的约定。Maven之所以推荐这种“约定优于配置”的方式，是因为只要遵循约定，构建工具就能自动找到源码、资源和web内容做对应处理。如果目录放乱了，最常见的问题就是“代码能写但打不成war包”，或者“依赖下载了但运行时ClassNotFoundException”。

1.2 为什么推荐用Maven管理项目依赖

IDEA里创建JavaWeb项目有两条路：一条是用IDEA的Web Module手动建，另一条是用Maven建。我更推荐Maven，理由很简单：依赖管理省心。

手动方式需要自己下载各种jar包，然后复制到WEB-INF/lib目录下。刚开始项目里的jar少还好，一旦引入Spring、MyBatis这类框架，依赖关系就像一团乱麻，A版本兼容B版本，C又不兼容D了，手动维护非常痛苦。

Maven则把依赖统一写在pom.xml里，它会自动从中央仓库下载jar包并传递依赖。比如你引入Spring Web后，它依赖的Spring Core、Spring Beans等模块会自动下载进来，不需要手工一个个找。而且Maven构建出来的war包结构规范，Tomcat等容器能直接识别。

这里放一张对比表，方便你直观感受：

顺手说一句，老版本的IDEA在创建项目时还可以勾选“Maven Archetype”里的maven-archetype-webapp模板来生成JavaWeb项目，但新版IDEA的Archetype下载经常抽风，模板生成出来的目录也偏老，个人建议不选模板，直接创建一个普通的Maven项目再补webapp目录，反而更可控。后面的实操部分就按这个思路来写。

1.3 动手前的环境准备

再好的操作步骤也跳不过环境准备。我在本地用的比较稳定的一套组合如下：

JDK版本需要注意：如果你项目要部署到比较老的服务器环境，用JDK 8更保险；如果是新项目且服务器支持，JDK 11甚至17也未尝不可。但不管选哪个，IDEA里的Project SDK、Maven的Java版本、Tomcat支持的JDK版本最好保持一致，否则启动时会报“UnsupportedClassVersionError”或者“Class has been compiled by a more recent version of the Java Environment”这类错误。

Tomcat选择上，Tomcat 9基本是当下主流，支持Servlet 4.0，性能、稳定性都不错。Tomcat 10以上包名变了，从javax.servlet改成了jakarta.servlet，很多老教程的代码直接拿过去会编译报错，所以新手阶段建议先用Tomcat 9，避开这个坑。

2. 从新建到启动：一步步实操记录

2.1 新建项目：不选骨架，直接补全

第一步，打开IDEA，选择“New Project”。在左侧向导里选择“Maven”，然后设置Project SDK为你的JDK版本。注意：这里不需要勾选“Create from archetype”，直接创建一个空Maven项目即可。勾选Archetype会被网络状况卡住，而且生成的结构并不比我们手动补快多少。

接下来填写GroupId和ArtifactId。GroupId一般用公司或个人的域名反写，比如com.example；ArtifactId是项目名，比如javaweb-demo。这两个值最终会体现在pom.xml的坐标里，影响依赖的引用路径，但第一次创建不必纠结，后面可以改。

点击Finish后，IDEA会生成一个最基础的Maven项目，只有src/main/java和src/main/resources两个目录，没有src/main/webapp。这时候我建议在IDEA的Project面板里，src/main目录下新建一个文件夹，命名为webapp。然后在webapp下建WEB-INF，在WEB-INF里建web.xml。

为什么这个xml很重要？因为JavaWeb项目需要一个部署描述符来声明Servlet、过滤器、监听器等组件。Servlet 3.0之后虽然支持注解方式，但web.xml依然是传统方式的核心入口，同时也是Tomcat启动时识别Web应用的标志之一。

2.2 标记源码目录与补全pom.xml

目录建好后，还有一步很多人忽略：让IDEA正确识别目录的角色。具体操作是右键src/main/java，选择“Mark Directory as”→“Sources Root”；右键src/main/resources，选择“Resources Root”；右键src/main/webapp，选择“Web Resources Directory”。如果你没标记src/main/webapp，后面写JSP时IDEA会出现一堆关于“Web Resource”的警告，甚至可能导致Artifacts配置异常。

此时pom.xml大概率还是空的或者只有基础坐标，需要手动补上打包方式和依赖。一个最小可运行的JavaWeb项目pom大概长这样：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>javaweb-demo</artifactId> <version>1.0-SNAPSHOT</version> <packaging>war</packaging> <properties> <maven.compiler.source>8</maven.compiler.source> <maven.compiler.target>8</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> </dependency> <dependency> <groupId>javax.servlet.jsp</groupId> <artifactId>javax.servlet.jsp-api</artifactId> <version>2.3.3</version> <scope>provided</scope> </dependency> </dependencies> </project>

这里有两个关键点需要解释：

第一，<packaging>war</packaging>表示项目要打成为war包，war包才是JavaWeb应用的标准交付格式，Tomcat可以直接解压部署。如果你漏了这行，默认是jar包，部署时就会出问题。

第二，Servlet和JSP的依赖scope用了provided。这个scope的含义是“编译和测试时需要，但打包时不包含”。因为Tomcat本身已经内置了Servlet和JSP的实现类，如果在war包里再塞一份，运行时会遇到类冲突或重复定义的问题。等你后续引入Spring MVC等框架时，它们传递引入的servlet-api可能也会是provided，看到时不用慌。

2.3 写一个最简单的Servlet验证链路

项目骨架齐了，接下来写一个最简单的Servlet，用来验证从“浏览器请求→Tomcat→Servlet→浏览器响应”的完整链路。

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

package com.example.demo; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; public class HelloServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType("text/html;charset=UTF-8"); resp.getWriter().write("<h1>Hello JavaWeb</h1>"); } }

同时在web.xml里配置Servlet映射：

<?xml version="1.0" encoding="UTF-8"?> <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>helloServlet</servlet-name> <servlet-class>com.example.demo.HelloServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>helloServlet</servlet-name> <url-pattern>/hello</url-pattern> </servlet-mapping> </web-app>

为什么继承HttpServlet？因为HttpServlet已经封装好了HTTP请求处理逻辑，把get、post等不同类型的方法分发到对应的doGet、doPost方法里，我们只要重写关心的方法即可。如果你直接实现Servlet接口，那就要手动处理service方法里的一堆分支，没必要。

为什么<url-pattern>配/hello？这个值决定了浏览器访问路径。启动Tomcat后，访问http://localhost:8080/hello时，Tomcat会根据这个映射找到HelloServlet并调用。url-pattern的写法还有/（匹配所有请求）、*.do（后缀匹配）等，新手先把精确路径跑通，后续再扩展。

2.4 配置Tomcat并启动项目

接下来是让项目跑起来的关键一步。在IDEA顶部工具栏找到“Add Configuration...”，点击后选择“Tomcat Server”→“Local”。

在配置界面里需要做三件事：

第一，指定Tomcat目录。在Application Server那一栏点Configure，选择你本机Tomcat解压后的根目录。IDEA会读取到Tomcat版本信息。

第二，配置Deployment。切到“Deployment”标签页，点加号选“Artifact”，在弹出的对话框里选择javaweb-demo:war exploded。这里建议选war exploded而不是war，前者是展开目录形式，不需要每次改代码都重新打包，启动速度也更快，Tomcat直接加载展开的目录。后者是标准war包，IDEA会先构建war再部署，调试效率低不少。

第三，设置Application context。这里我习惯设为/，这样访问路径是http://localhost:8080/hello，干净。如果你填成/demo，那就要通过http://localhost:8080/demo/hello才能访问。Application context等同于部署后的上下文路径，它影响所有URL的根前缀，很多人404就是在这里没搞明白。

配置完成后，点击运行按钮（绿色三角形），IDEA会编译项目、启动Tomcat，并在运行窗口打印日志。看到“Server startup”相关的日志后，打开浏览器访问http://localhost:8080/hello，页面上出现“Hello JavaWeb”就说明整条链路已经通了。

2.5 启动后的一些细节验证

页面通了之后，建议再做几件事确认项目状态健康：

• 访问http://localhost:8080/看看Tomcat默认页面是否出现，这能帮你判断是不是项目上下文没生效。
• 在项目里改一行输出文字，再刷新浏览器，确认改动是否生效。如果用的war exploded，IDEA默认会触发自动更新，大多数情况下刷新页面即可看到变化。
• 观察IDEA运行窗口有没有红色异常日志。有异常不可怕，关键是学会看异常栈的第一行，那才是问题根源。

这里顺便说一句，IDEA的Tomcat配置属于运行配置，只对当前项目生效，不会污染Tomcat本身。所以同一个Tomcat可以同时被多个项目复用，只要端口不冲突就行。

3. 关键配置拆解：让项目跑得明白

3.1 pom.xml依赖的添加逻辑

很多新手对pom.xml有个误区，以为依赖随便加就行。其实Maven依赖的核心逻辑是“坐标”，每个依赖由groupId、artifactId、version三个值唯一定位。groupId一般是组织名，artifactId是模块名，version是版本号。类似于超市里买东西必须知道“哪个货架、什么商品、哪个批次”，缺一个都可能拿错东西。

在实际项目中，Spring、MyBatis这类框架的依赖不是自己写的groupId和version，而是直接从Maven中央仓库查来的。IDEA也提供了快捷方式：在pom.xml里Alt+Insert选择“Dependency”，输入关键字搜索，IDEA会从本地仓库和远程仓库索引里匹配，选中即可自动插入坐标。

依赖多了以后还有几个常见问题：

• 版本冲突。比如多个模块传递依赖了不同版本的fastjson，Maven会有自己的仲裁规则，但结果不一定是你想要的。解决办法是显式声明版本，用<dependencyManagement>或properties统一版本。
• scope用错。像servlet-api这种容器内置类，必须用provided；像JUnit这种只在测试用的，用test；默认的compile适用于大多数业务依赖。
• 依赖下载慢。Maven默认从中央仓库拉取，国内网络环境会慢。可以在Maven的settings.xml里配置镜像仓库，速度会明显提升。这个网上教程很多，属于开发环境的常规优化，建议尽早配好。

3.2 web.xml与注解方式如何选

传统方式是在web.xml里声明Servlet，这个方式的好处是“集中管理”，项目里几个Servlet一目了然。但Servlet一多，web.xml会变得很长，所以Servlet 3.0规范推出了@WebServlet注解，直接在Servlet类上标注映射路径，省掉了XML配置。

用注解写法，上面的HelloServlet可以改成：

@WebServlet("/hello") public class HelloServlet extends HttpServlet { // doGet方法一样 }

前提是项目运行在支持Servlet 3.0及以上的容器（Tomcat 8以上都支持），且web.xml里声明的metadata-complete不能为true，否则注解不会被扫描。这句话的意思是：web.xml的<web-app>标签里如果写了metadata-complete="true"，容器就会认为注解信息不需要扫描。默认情况下不写这个属性就没事。

实际开发中，我倾向于注解方式，因为配置写在类旁边，跳转方便。但有一个例外：Filter的执行顺序在注解方式下不好控制，如果多个过滤器有明确先后顺序要求，我仍会用web.xml配置。

3.3 Context Path与端口的关系

Context Path这个词初看抽象，其实就是一个URL里的项目路径部分。Tomcat部署一个war包后，会在webapps目录下生成同名文件夹作为上下文根。IDEA里的Application context就是设置这个上下文根。

打个比方：localhost:8080是你的服务器地址，Context Path是服务器众多房号中的一个房间号。如果房间号是/，代表默认房间，访问时不用加额外的路径；如果房间号是/demo，那所有项目内资源的URL都要带有这个前缀。

端口号默认是8080，配置文件在Tomcat的conf/server.xml里可以改。IDEA运行配置里也有一个“HTTP port”选项，如果要调试多个项目，可以给不同项目分配不同端口。改端口和Context Path是排查404时首先检查的两个点。

4. 踩坑实录：我遇到过的常见问题与排查套路

4.1 新建项目后找不到webapp目录

这是最高频的问题，尤其新版IDEA。原因很简单：IDEA的新建项目向导默认只生成Maven标准目录（java、resources），不包含webapp，因为webapp不是Maven的强制目录结构，只有打包成war时才需要。

解决方式就是手动创建。在src/main下新建目录webapp，然后再建WEB-INF和web.xml。如果IDEA的Project Structure里的Web模块没有自动识别，需要进Project Structure→Facets，找到Web，在Web Resource Directories里把src/main/webapp加上。

4.2 引入的jar包找不到或爆红

jar包爆红的原因通常是Maven依赖没下载成功，或者本地仓库里没有对应版本。先执行mvn clean compile看日志里的具体错误，是不是某个依赖下载超时。之后在IDEA右侧Maven面板点刷新按钮（Reload All Maven Projects），让IDEA重新解析依赖。

还有一种是代码里手动下载了jar复制进项目，这在Maven项目里会别扭。Maven项目应该把jar引入pom，由Maven统一管理来源和版本，手动塞lib目录反而容易让Maven打包时忽略它们。

4.3 页面404、Servlet类找不到或ClassNotFoundException

这一类问题要分场景来看。

如果启动Tomcat正常，但访问/hello是404，按这个顺序排查：

• 看IDEA运行日志，确认Tomcat到底有没有把Artifact部署进去。有类似“Deployment of web application directory ... has finished”的日志才算部署成功。
• 确认访问路径里有没有带上Context Path。Application context是/demo而你只访问了/hello，必然是404。
• 确认Artifacts里有没有lib。看IDEA的Project Structure→Artifacts，展开war包结构，WEB-INF下要有一个lib目录，里面包含所有依赖jar。如果lib目录为空，运行时就会报ClassNotFoundException或NoClassDefFoundError，尤其是Servlet类本身找不到。解决方式是右键Artifact选Put into Output Root或检查Artifact里的Available Elements是否把library加了进去。

如果日志里明确报Servlet类找不到，那多半是Artifacts漏了Web方面的资源目录，或者源文件没有重新编译。先Build→Rebuild Project，再重启Tomcat试试。

4.4 端口被占用

Tomcat启动时报Port 8080 was already in use是经典场景。可能是之前启动的Tomcat没关干净，也可能是其他程序占用了端口。

Windows下打开命令行执行：

netstat -ano | findstr 8080

找到对应的PID后，再：

taskkill /f /pid 对应的PID

macOS或Linux环境下：

lsof -i :8080 kill -9 对应的PID

如果这个端口有用途不想杀，那就改Tomcat端口。改端口有几种做法：改全局的conf/server.xml，或在IDEA运行配置里设置HTTP port，或通过VM options加-Dport.http=8081之类参数（取决于项目配置）。我建议改IDEA运行配置，最快最直观。

4.5 控制台出现乱码

乱码通常是编码不一致导致的。Tomcat启动时控制台输出、页面返回内容、日志文件，三者都有各自的编码场景。

最通用的一招，在IDEA的Help→Edit Custom VM Options里加一行：

-Dfile.encoding=UTF-8

然后在Tomcat运行配置的VM options里也加上同样的参数。此外，代码里设置响应编码时不要只写resp.setCharacterEncoding("UTF-8")，最好连同resp.setContentType("text/html;charset=UTF-8")一起设置，确保Content-Type头里带了charset。JSP页面头部记得加<%@ page contentType="text/html;charset=UTF-8" language="java" %>。

4.6 常见问题速查

这张表基本覆盖了入门阶段90%的问题。真正遇到没见过的报错时，我的排查套路是：先看日志栈顶的异常类型，再去搜这个异常对应的上下文配置，千万别从头到尾读一遍日志然后发懵，抓关键行比什么都重要。

5. 项目跑通之后，还能再往前一步

5.1 热部署配置，少熬几个夜

项目跑通只是开始，日常调试效率更值得优化。IDEA里Tomcat配置的On frame deactivation和On update action两个下拉框就是热部署的关键。

建议这样配：On update action选Update classes and resources，On frame deactivation也选Update classes and resources。这样当IDEA窗口失去焦点，或者手动触发Update时，改动的类和资源会自动同步到Tomcat的部署目录。不过要注意，改方法签名、新增类等结构性变动时，Update classes and resources不一定可靠，这时候选Redeploy或重启Tomcat更保险。

另外，开发时用war exploded部署本身就是热部署的前提。用完整war包的话，每次更新都要重新构建war再让Tomcat重新识别，效率低很多。所以日常开发请坚持使用exploded形式。

5.2 用Maven统一依赖版本，从源头减少冲突

当pom.xml里依赖多了以后，会发现同一个version字段散落在各处，升级版本时要一个个改。用Maven的<properties>标签可以把版本号抽出来统一管理：

<properties> <spring.version>5.3.30</spring.version> </properties> <dependencies> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-web</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context</artifactId> <version>${spring.version}</version> </dependency> </dependencies>

这样升级Spring时，只改properties里一处就可以了。很多开源项目的文档也是这么推荐的。这个习惯建议一开始就养成，而不是等项目依赖爆炸了再回来重构。

5.3 从“能跑”走向“分层”

HelloServlet能响应请求之后，很多人下一步开始往上堆代码，把所有业务逻辑都写在Servlet里。短期没问题，但Servlet代码会越来越臃肿，谁维护谁知道。

我在实际项目里的做法是，尽早引入分层意识：Servlet只负责接收请求和返回响应，业务逻辑放到Service层，数据访问放到Dao层，实体类单独放一个包。这样改动业务规则时不需要动Servlet，替换数据源时也不需要动Service。这就是MVC思想的雏形，哪怕不引入Spring，纯Servlet也完全可以做三层结构。

再进一步的话，可以学学过滤器（Filter）和监听器（Listener），在请求进入Servlet前做统一编码处理、登录校验、日志记录，这些是实际项目中必不可少的部分。等你把Servlet搭配Filter、ServletContextListener玩明白了，再去接触Spring MVC会顺手很多。

我个人在实际操作中的体会是：创建JavaWeb项目这件事，第一次跑通是最费劲的，因为里面牵扯到Maven、Tomcat、IDEA三者之间的配置协作，任何一环理解不到位就容易卡壳。但只要亲手从空目录一步步搭到浏览器出现“Hello JavaWeb”，后面接触Spring Boot、微服务这些更复杂的东西时，你会发现自己对“一个Web应用如何被部署、如何被访问”有了更踏实的底子。别嫌麻烦，也别一步到位用骨架生成器，耐心把每一步的配置和原因都过一遍，这个基本功什么时候都用得上。