企业官网建设流程全解析

做了这么多年JavaWeb项目，从早期用MyEclipse、Eclipse，到后来换到IDEA，最常被问到的问题就是：“项目在IDEA里跑得好好的，怎么打成war包部署到服务器上就不行？”其实这中间的步骤并不复杂，但每一步都有容易踩坑的地方：打包出来的war内容不完整、Tomcat版本和JDK不匹配、端口被占用、部署后404……这些问题我在项目上线时全遇到过。

这篇文章就把JavaWeb项目从打包、部署到Tomcat、再到启动验证的完整流程整理出来。没有高深的知识，全是实际干活时用的步骤和参数，适合刚学JavaWeb的初学者，也适合希望部署流程更规范、更少出错的人。我会把每个关键环节的“为什么”和“注意事项”一起写清楚，照着做能少走不少弯路。

1. 打包部署前，先把整体思路捋清楚

1.1 为什么生产上一定要用war包

先说一个最基本的问题：JavaWeb项目编译后为什么是war包，而不是像普通Java程序那样的jar包？

开发的时候，我们习惯在IDEA里直接配置Tomcat并运行，IDEA会把项目按Exploded方式发布到Tomcat的临时目录中。这种方式的优点是改完代码立刻生效，debug也方便，适合开发阶段。但到了生产环境，服务器上往往没有IDE，我们要把整个Web应用打成压缩包丢给Tomcat，由Tomcat自己去识别和加载。war包就是这个Web应用的“标准交付格式”。

war包内部是严格按照Servlet规范组织的一个目录结构，包含WEB-INF、classes、lib、web.xml这些内容。Tomcat启动时会扫描webapps目录下的war包，自动解压并部署。因为war包是一个有结构约定的包，所以它天然适合跨环境部署，只要Tomcat版本和JDK版本匹配，换一台机器也能正常跑。

这里顺手提一下war和jar的区别。jar包是把class文件、资源文件压缩到一起的普通Java归档包，主要用于类库或可执行程序；war包则必须符合Web应用的标准，里面必须有WEB-INF目录，而且部署方式不是用java -jar执行，而是丢进Web容器里加载。

1.2 部署时Tomcat到底做了什么

很多人只知道把war放到webapps下面，但不知道Tomcat启动后具体干了什么。理解这个流程之后，排查问题会快很多。

Tomcat启动时，容器会扫描webapps目录。如果发现一个war包，并且该war包对应的目录还不存在，Tomcat会先把war文件解压成一个同名目录，然后基于这个目录完成Web应用的上下文加载。如果war包对应的目录已经存在，Tomcat会根据解压后的内容直接加载。

一个非常常见的坑：有人手动把war解压了，然后改了解压目录里的东西，再重启Tomcat，结果发现修改被“还原”了，或者应用启动报错。原因就是Tomcat的启动逻辑是按“目录不存在时才解压”来处理的。所以我的建议是：除非你明确设置了unpackWARs=false，否则不要手动解压，让Tomcat自己去处理war文件。

整个部署链路用文字描述就是：

源代码 -> Maven编译打包 -> target目录下生成.war -> 复制到Tomcat的webapps目录 -> 启动Tomcat -> 自动解压war -> 加载classes和lib -> 初始化Spring/MyBatis等框架 -> 监听端口 -> 等待请求

这个链路每一步都可以验证：war有没有生成，webapps下有没有自动解压，日志里有没有Deployment信息，端口有没有监听。后面我会按这个顺序一步步写。

2. 环境准备：别让版本搭配拖垮你

2.1 JDK、Tomcat、Maven版本匹配关系

我做过的项目里，至少有一半的部署失败，最后查下来是版本匹配问题。JavaWeb项目对版本关系特别敏感，尤其是从Servlet到Spring的依赖，选错了版本直接编译不过或者启动不下去。

比较常见的稳定组合有两个习惯，我列成表格方便对照：

这两个组合不是随便拍的。Tomcat 9.x用的是javax命名空间，Tomcat 10.x开始改用jakarta命名空间，也就是说原来项目里import javax.servlet.的代码，到了Tomcat 10上如果没换成jakarta.servlet.，编译会直接报错。如果不小心用错了，最常见的结果就是部署后报NoClassDefFoundError或Servlet初始化失败。

2.2 关键环境变量的配置

部署Tomcat前，建议先确认几个环境变量。

• JAVA_HOME：指向JDK安装目录，Tomcat启动脚本依赖它去找java命令。
• CATALINA_HOME：指向Tomcat安装目录。
• MAVEN_HOME（如果用命令行打包）：指向Maven安装目录。

具体怎么看？Windows下在命令行输入echo %JAVA_HOME%，能正常打印出来就行。如果为空，就去系统环境变量里补上。很多新手遇到的“Tomcat双击startup.bat闪退”，十有八九是JAVA_HOME没配置或者是配置到了JRE上。

注意一个容易搞错的地方：JAVA_HOME不要配到包含bin的路径。正确写法是C:\Program Files\Java\jdk1.8.0_xxx，而不是C:\Program Files\Java\jdk1.8.0_xxx\bin。Tomcat的脚本会自动在JAVA_HOME后面拼接bin目录，配多一层bin反而找不到java。

CATALINA_HOME的设置同理，指向Tomcat解压后的根目录，比如D:\apache-tomcat-9.0.85，不要指到bin或者webapps。

2.3 IDEA里的JavaWeb项目结构怎么看

在开始打包前，先看一遍项目的目录结构，确保它确实是一个标准的Maven Web工程。

一个标准JavaWeb项目通常长这样：

my-webapp/ ├── pom.xml ├── src │ ├── main │ │ ├── java │ │ ├── resources │ │ └── webapp │ │ ├── WEB-INF │ │ │ └── web.xml │ │ ├── js │ │ ├── css │ │ ├── index.jsp │ │ └── ... │ └── test │ └── java └── target ├── classes └── my-webapp.war

这里最常见的坑是：把静态页面放错目录。如果你把页面直接放在src/main/java下面，Maven打包时它们是进不了war的正确位置的。应该统一放在src/main/webapp下。WEB-INF下的内容在部署后是受保护的，浏览器不能直接访问，所以如果你的jsp或页面资源需要被用户访问到，不要塞到WEB-INF内部，要么放外面，要么通过Controller转发。

3. 用Maven把项目打成war包

3.1 pom.xml里这几个配置别漏掉

打包前，先检查pom.xml。最关键的几个配置如下：

<groupId>com.example</groupId> <artifactId>my-webapp</artifactId> <version>1.0.0</version> <packaging>war</packaging> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <build> <finalName>my-webapp</finalName> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.2</version> </plugin> </plugins> </build>

解释一下这几个配置项：

• <packaging>war</packaging>：告诉Maven这是一个Web应用，打包时按war模式处理。如果是默认jar，生成的包结构就不对。
• <maven.compiler.source/target>：指定编译用的JDK语法版本。这里用了1.8。如果你的服务器上JDK是更高版本，可以适当升级，但注意Tomcat版本要能兼容。
• <project.build.sourceEncoding>：很多中文乱码问题其实在这里就能提前拦住。不设置编码时，Maven会依赖系统默认编码，容易把UTF-8的源文件编译成乱码class。
• <finalName>：决定war包的文件名。这一项非常有用，后面部署时的访问路径就跟它有关。
• maven-war-plugin：负责执行war打包的插件。如果你的pom里配了其他插件，比如maven-shade-plugin或者spring-boot-maven-plugin，要搞清楚它们会不会改变打包方式，别同时生效。

3.2 在IDEA里完成clean和package

环境配好、pom检查完，就可以打包了。我还是建议直接用IDEA的Maven面板操作，方便且不容易出错。

在IDEA右侧找Maven窗口，展开你项目的Lifecycle，双击clean，再双击package。打包完成后，控制台会打印BUILD SUCCESS，同时target目录下会出现你的war包。

要注意Maven是一条生命周期链，直接执行package时会自动执行编译和测试。我建议第一次打包时，先clean再package，把target目录先清干净，避免旧文件残留干扰判断。

如果没有Maven面板，也可以从IDEA顶部菜单操作：View -> Tool Windows -> Maven。

打包期间如果遇到下载依赖卡住，大概率是网络问题。可以在项目的settings.xml里配置国内镜像源，比如阿里云镜像。这个不属于本文主题，但你如果遇到过，会明白我为什么提它。

3.3 命令行打包与跳过测试

有时候服务器上直接打包，或者你习惯用命令行，那就用Maven命令行：

mvn clean package

如果项目里有测试用例，但暂时不想执行测试，可以加上参数跳过：

mvn clean package -Dmaven.test.skip=true

-Dmaven.test.skip=true会跳过编译测试代码，也比-DskipTests更彻底。开发环境快速出包我用前者比较多。

命令行打包的前提是mvn命令可用，也就是说MAVEN_HOME配置正确，并且在系统PATH里加入%MAVEN_HOME%\bin（Windows）。

3.4 打包报错与解决办法

打包最常见的错误就这么几类，我直接列出来：

1. 编译错误：某个类报红，这种用IDEA打开就看得见，解决源代码问题后重新打包。
2. 编码错误：报unmappable character for encoding，通常是没有设置project.build.sourceEncoding，按3.1的配置加上即可。
3. 依赖下载失败：建议配置国内镜像源，或者检查网络代理。
4. 测试失败：报Tests run: X, Failures: Y，可以临时跳过测试打包，排查测试失败原因。
5. 版本冲突：比如两个jar包里的类冲突，可以执行mvn dependency:tree查看依赖树，再用exclusion排除冲突包。

有个实用小技巧：执行打包命令时，加上-X可以输出调试信息，虽然日志很长，但用于排查依赖和插件问题非常好用。平时不用开。

4. 把war包部署到Tomcat

4.1 部署war的三种常见方式

拿一个war包，放到哪里都行？不是。Tomcat部署war常见有几种方式：

• 直接拷贝到webapps目录：最简单，Tomcat启动时自动识别并部署。适合大多数单机场景。
• 通过Tomcat Manager界面或API上传：需要提前配置manager用户角色，适合远程图形化操作。
• 在server.xml的Host节点配置Context指向war路径：适合war包放在自定义目录的情况，但修改配置文件时必须格外小心。

我一般在生产环境用第一种。简单直接，而且Tomcat自动处理解压，几乎不会出问题。Manager方式适合服务器不在手边、需要通过浏览器上传的场景，但要记得把tomcat-users.xml里的manager-script或manager-gui角色配上，同时注意权限和密码管理。

4.2 手把手往webapps里放war包

假设Tomcat已经解压到D:\apache-tomcat-9.0.85，webapps目录就在D:\apache-tomcat-9.0.85\webapps，我把上一步打好的my-webapp.war拷贝进去。

启动Tomcat后，它会自动在webapps下生成my-webapp目录。然后访问路径就是：

http://localhost:8080/my-webapp/

这里有一个要点：war包的文件名就是应用上下文路径，也就是URL里第一级路径。如果你打出来的war叫my-webapp-1.0.war，访问路径就必须带my-webapp-1.0。想让路径干净些，就用finalName配置，或者直接把war改成想要的名字再放进去，比如改成ROOT.war。

注意：放好war包之后，如果Tomcat已经处于运行状态，一定要先执行shutdown再执行startup。webapps目录默认不支持自动加载新war，只点startup重启不一定能更新成功。

4.3 让应用以根路径访问

很多项目上线后希望直接通过http://localhost:8080/访问，不带项目名。做法很简单：把war包改名为ROOT.war再放到webapps目录。Tomcat会把ROOT应用解析为根上下文。

需要注意，webapps目录下默认会有一个ROOT目录（Tomcat自带默认首页）。部署前最好先把原ROOT目录和ROOT.war清掉，否则新旧应用冲突，可能出现你访问根路径时看到的还是Tomcat默认页面。

如果你想保留原来的ROOT，也可以改部署方式，在server.xml里配置Context的path为空串。但个人经验是不太推荐在server.xml里频繁动Context，容易漏掉配置影响其他应用。ROOT.war这个方案最稳。

4.4 调整Tomcat端口与JVM参数

Tomcat默认端口8080。如果端口冲突，修改conf/server.xml里Connector的port属性：

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

把port改成别的值，比如8081，然后重启Tomcat。

但端口不是唯一要调的东西。正式部署时JVM参数经常要考虑。启动常见JVM参数配置有两种做法：

• 修改bin/catalina.bat（Windows）或bin/catalina.sh（Linux），在文件顶部加JAVA_OPTS。
• 在bin目录创建setenv.bat或setenv.sh，Tomcat启动脚本会自动加载setenv中的配置。

我推荐第二种方式，因为Tomcat升级时不会因为修改catalina脚本而丢失配置。setenv.bat示例：

set JAVA_OPTS=-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=256m -Dfile.encoding=UTF-8

对应的Linux下setenv.sh：

export JAVA_OPTS="-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=256m -Dfile.encoding=UTF-8"

为什么设置这些？-Xms控制堆内存初始值，-Xmx控制堆内存最大值。项目不大时512m到1024m足够。MaxMetaspaceSize控制类元数据内存上限，Spring等框架类多，不设可能默认占用太大。加-Dfile.encoding=UTF-8可以处理很多邪门的中文乱码问题。

5. 启动Tomcat并验证整个链路

5.1 用startup脚本启动并确认端口

Windows下进入Tomcat的bin目录，双击startup.bat，或者使用命令行：

D:\apache-tomcat-9.0.85\bin>startup.bat

命令行会弹出一个新窗口显示启动日志。注意这个窗口别关，关了相当于强制结束Tomcat。

Linux服务器上使用：

/opt/apache-tomcat-9.0.85/bin/startup.sh

我更推荐在Linux调试时用前台启动方式：

/opt/apache-tomcat-9.0.85/bin/catalina.sh run

这样日志直接打在前台，能立刻看到问题。确认无误后再改用startup.sh后台运行。

启动后确认Tomcat是否在监听端口：

netstat -ano | findstr 8080 # Windows ss -lntp | grep 8080 # Linux

看到端口监听，才说明Tomcat进程正常。

5.2 看日志确认部署成功

日志是判断部署成功与否最重要的依据，比看界面靠谱得多。Tomcat日志在logs目录下，重点看catalina.out（Linux）和catalina.日期.log。

成功的部署在日志里会看到类似：

INFO: Deploying web application archive [D:\apache-tomcat-9.0.85\webapps\my-webapp.war] INFO: Deployment of web application archive [D:\apache-tomcat-9.0.85\webapps\my-webapp.war] has finished in [5,382] ms

如果应用里有Spring，还会看到Spring容器初始化的日志。看到类似Started Application或Deployment has finished，基本就成功了。

有问题时，日志里往往有异常堆栈，比如数据库连接失败、端口冲突、Bean创建失败等。拿到堆栈再去搜解决方案，比自己瞎猜要快得多。

5.3 浏览器验证与常见页面路径

部署完成后，浏览器访问：

http://localhost:8080/my-webapp/

能打开你的首页就算成功。如果首页叫index.jsp或index.html，Tomcat会直接把它作为欢迎页。

如果访问报404，先看是不是路径问题：war包名、Context路径、项目里Controller的RequestMapping路径，这三者要拼得对。比如war包是my-webapp.war，Controller映射是/user/list，完整URL是http://localhost:8080/my-webapp/user/list，少一层都会404。

浏览器缓存有时也会干扰，刷新时强制Ctrl+F5，确认拿到的是最新页面。

6. 复盘常见问题：从闪退到404

6.1 Tomcat打不开，窗口一闪而过

这是被问得最多的。双击startup.bat后窗口闪退，原因通常是：

• JAVA_HOME环境变量没有配置或配置错误。
• JDK版本和Tomcat版本不兼容。
• 默认端口8080被占用，但不一定闪退，可能停在日志里。

排查方式：不要用双击，先用命令行执行startup.bat，这样关闭窗口前能看到错误提示。再检查logs/catalina.out，里面的报错会比弹窗更完整。

我见过一个典型场景：本机装了多个JDK，JAVA_HOME指到了旧版本，但IDEA里用的却是新版本，结果用命令行启动Tomcat就是闪退。统一JAVA_HOME和IDEA里的JDK，问题就消失了。

6.2 端口被占用，起不来

如果启动日志报Port 8080 was already in use，就是端口被其他程序占了。

Windows先找占用者：

netstat -ano | findstr 8080

最后一列是进程PID，再用tasklist查看是什么程序，决定结束进程还是改Tomcat端口。

一个细节：杀掉占用进程前，先确认不是其他正在运行的服务或数据库，杀错了会影响其他环境。我通常在测试环境直接改Tomcat端口到8081，比杀进程更省事。

6.3 访问项目一直404或路径不对

404分好几种，最常见的是应用404（页面不存在）和Tomcat全局404（应用根本没部署）。区别在于：应用404通常能显示你的项目名字或框架的404页面，Tomcat全局404显示的是Tomcat默认错误页。

如果看到的是Tomcat默认404：

• 先检查webapps下有没有自动解压出来的项目目录。
• 确认war有没有成功放入webapps。
• 看日志里有没有Deployment失败。

如果应用本身404：

• 检查Context路径是否写对。
• 检查WEB-INF里的welcome-file配置。
• 检查Controller路由和前端URL是否一致。

另外，很多人会把页面放在WEB-INF下，然后抱怨访问不到。这是Servlet规范故意设计的保护机制：WEB-INF下的内容不接受浏览器直接访问，要通过Servlet/Controller转发。如果你要直接访问jsp，请放在WEB-INF外部。

6.4 中文乱码问题

乱码有两个位置：页面显示乱码和日志乱码。

页面乱码，先检查响应编码。可以给JSP或HTML加：

<%@ page contentType="text/html;charset=UTF-8" language="java" %>

或者确保CharacterEncodingFilter配置了UTF-8。

日志乱码，检查Tomcat日志编码。在conf/logging.properties里把java.util.logging.ConsoleHandler.encoding改为UTF-8，同时setenv里加-Dfile.encoding=UTF-8。这个方法能解决一大片莫名其妙的中文乱码。

6.5 打包时报出奇怪的编译错误

我碰到过一种典型的“本地跑得好，打包就报错”的情况：项目代码依赖了某个jar包，但那个包只在某个模块下被引入，Maven打包时没有按预期包含完整依赖。排查时优先看mvn dependency:tree。

如果编译错误集中在某些import找不到，多半是scope配置问题。比如某依赖scope是provided，编译时有，打包时就不带依赖。排查一下pom里每个依赖的scope，必要时改成compile。

6.6 部署后ClassNotFound或依赖丢失

war部署后启动报ClassNotFoundException或NoClassDefFoundError，不用怀疑，就是lib目录里少依赖。

war包内的WEB-INF/lib是应用运行时的依赖位置。如果你发现war里没有lib目录，或lib里没有jar，说明打包时依赖没有正确收集。常见原因：maven-war-plugin版本过低、打包方式被其他插件影响、pom里依赖标了provided或test。

打开war包检查是最快方法。war本质上是个zip包，用压缩软件打开，看目录结构是不是完整：

• WEB-INF/classes：编译后的class
• WEB-INF/lib：运行时依赖jar
• WEB-INF/web.xml：web配置

缺哪块补哪块，不用一上来就怀疑代码。

我的习惯是，每次部署前先看一遍日志目录里上次启动的报错，顺手清理掉老的war和解压目录，再放新的war。这个习惯帮我躲过了不少“改了代码但没生效”的坑。毕竟JavaWeb部署本身不难，难的是每一步都带着思考去操作。希望这篇流程整理对你的项目上线有帮助，如果你也遇到过某些没写进来的坑，欢迎在评论区补充。