1. 从零搞懂Tomcat与war包：为什么你的JavaWeb项目需要它
刚接触JavaWeb那会儿，我最困惑的一件事就是：明明在本地IDE里跑得好好的项目，怎么一放到服务器上就各种报错？后来才慢慢搞明白，问题往往出在“部署方式”上。本地开发时，IDE帮你把类加载、路径映射、资源定位这些脏活累活全干了，可一旦脱离IDE，你得自己把项目“打包”成一个容器能读懂的格式，再交给Tomcat去跑。这个格式，就是war包。
war，全称Web Application Archive，直译过来就是“Web应用归档文件”。你可以把它理解成一个“项目压缩包”，但它比普通zip多了几样东西：固定的目录结构、一个必须存在的WEB-INF文件夹、以及可选的web.xml描述文件。Tomcat拿到这个包之后，会自动解压到webapps目录下，按照约定好的规则去加载类、初始化Servlet、映射URL。说白了，war包就是你和Tomcat之间的一份“合同”，你按格式交东西，它按规则跑服务。
那为什么不用jar包？这是很多人会问的问题。jar包是Java的通用归档格式，什么都能装，但它没有“Web应用”这个概念。Tomcat不认识jar里的Web结构，你硬塞给它，它也不知道该从哪里找Servlet、哪里找静态资源。war包则不同，它的目录结构是Servlet规范里写死的：根目录下放HTML、CSS、JS这些静态文件，WEB-INF下放classes（编译后的class文件）、lib（依赖jar）、web.xml（部署描述符）。Tomcat一看就懂，直接按这个结构去初始化上下文。
这篇文章适合谁看？如果你正在学JavaWeb，已经能写Servlet和JSP，但一到“部署上线”就卡壳；或者你平时用Spring Boot内嵌Tomcat跑得挺爽，但公司老项目还在用外置Tomcat加war包部署，你不得不接手——那这篇内容就是给你准备的。我会从目录结构讲起，把Maven和Gradle两种打包方式都过一遍，再聊部署时常见的坑和排查思路。不扯虚的，全是能直接抄作业的操作。
提示：war包不是唯一部署方式，但在传统JavaWeb项目和部分企业级场景里，它依然是最稳妥、最通用的选择。理解它，等于理解了Servlet容器的工作逻辑。
2. war包目录结构拆解：每个文件夹到底装什么
2.1 标准目录长什么样
一个规范的war包解压后，结构是这样的：
myapp.war ├── index.html ├── css/ ├── js/ ├── images/ ├── WEB-INF/ │ ├── web.xml │ ├── classes/ │ │ └── com/example/... │ └── lib/ │ └── xxx.jar └── META-INF/ └── MANIFEST.MF根目录下的东西，是直接暴露给浏览器的。比如你放一个index.html，用户访问http://host:8080/myapp/就能看到。css、js、images这些静态资源也放这里，Tomcat会直接返回，不走Servlet。
WEB-INF是核心，也是“禁区”。浏览器无法直接访问WEB-INF下的任何文件，这是Servlet规范强制要求的。为什么？因为这里面放的是class文件、依赖jar和配置，如果暴露出去，别人就能下载你的字节码反编译，安全风险极大。classes目录放你编译后的.class文件，包路径要和源码一致。lib目录放项目依赖的第三方jar，Tomcat会自动把这些jar加入类加载路径。web.xml是部署描述符，用来配置Servlet映射、过滤器、监听器、欢迎页等。
META-INF里通常只有MANIFEST.MF，记录版本、构建工具等信息，一般不用手动改。
2.2 为什么目录结构不能乱
我见过有人把class文件直接扔在根目录，或者把jar放在WEB-INF外面，结果Tomcat启动时报ClassNotFoundException。原因很简单：Tomcat的类加载器只认WEB-INF/classes和WEB-INF/lib这两个位置。你放别处，它根本扫不到。
还有一个常见错误：web.xml的版本声明和Tomcat版本不匹配。比如你用Servlet 4.0的schema，但Tomcat 8只支持到3.1，启动就会报解析错误。所以打包前一定要确认目标Tomcat的版本，再决定web.xml的schema地址。
注意：从Servlet 3.0开始，web.xml变成可选了。你可以用注解（@WebServlet、@WebFilter）来配置，但传统项目里web.xml依然是主流，建议保留。
2.3 静态资源与WEB-INF的边界
静态资源放根目录，动态资源放WEB-INF，这个边界要清晰。有人把JSP放在根目录，虽然能访问，但不利于权限控制。JSP本质是Servlet，放WEB-INF下可以防止直接访问，只能通过Controller转发，更安全。
另外，根目录下的文件会参与Tomcat的默认Servlet处理，而WEB-INF下的不会。所以如果你有需要保护的页面，放WEB-INF；需要直接下载的，放根目录。
3. Maven打包war包：pom.xml里的关键配置
3.1 packaging改成war
Maven默认打包类型是jar，要打war包，第一件事就是在pom.xml里改：
<packaging>war</packaging>这一行决定了Maven用哪个插件来打包。改成war后，maven-war-plugin会自动介入，按照Web应用的标准结构去组装。
3.2 依赖scope要分清
不是所有依赖都要打进war包的lib目录。比如servlet-api和jsp-api，Tomcat本身已经提供了，你如果再打进去，可能导致版本冲突。所以这两个依赖的scope要设为provided：
<dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> </dependency>provided的意思是：编译和测试时用，打包时不放进去。Tomcat运行时自己会提供。如果你用的是jakarta命名空间（Tomcat 10+），groupId和artifactId要换成jakarta.servlet对应的。
其他业务依赖，比如数据库驱动、JSON库，scope用默认的compile，会被打进lib目录。
3.3 配置maven-war-plugin
虽然默认配置就能用，但有些场景需要自定义。比如你想改war包的名称，或者排除某些文件：
<build> <finalName>myapp</finalName> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.2</version> <configuration> <warName>myapp</warName> <failOnMissingWebXml>false</failOnMissingWebXml> </configuration> </plugin> </plugins> </build>failOnMissingWebXml设为false，是因为Servlet 3.0之后web.xml可选，不设的话Maven会报错。finalName决定war包的名字，部署后访问路径就是/myapp。
3.4 执行打包命令
配置好后，在项目根目录执行：
mvn clean packageclean先清掉target目录，package触发打包。成功后target目录下会出现myapp.war。你可以用jar -tf myapp.war查看内容，确认结构是否正确。
实操心得：打包前先跑
mvn clean test，确保测试通过。我遇到过测试失败但强行打包，部署后运行时才报错，排查成本高很多。
4. Gradle打包war包：build.gradle配置要点
4.1 应用war插件
Gradle打war包，第一步是应用war插件：
plugins { id 'war' }应用后，Gradle会自动添加war任务，并且把src/main/webapp作为Web资源目录。
4.2 依赖配置
和Maven类似，servlet-api要用providedCompile或compileOnly：
dependencies { providedCompile 'javax.servlet:javax.servlet-api:4.0.1' implementation 'com.example:some-lib:1.0.0' }providedCompile是war插件提供的配置，表示编译时需要但打包时不包含。implementation的依赖会被打进WEB-INF/lib。
4.3 自定义war任务
如果需要改war包名或排除文件：
war { archiveFileName = 'myapp.war' from('src/main/webapp') { exclude '**/*.psd' } }执行gradle war，产物在build/libs目录下。
4.4 Maven与Gradle的选择
两者都能打war包，区别在于Maven配置更声明式，Gradle更灵活。老项目多用Maven，新项目Gradle也不少。我个人习惯：如果团队已经用Maven，就别折腾换Gradle；如果从零开始，Gradle的构建速度确实快一些。关键是把依赖scope分清楚，不然打出来的war包要么缺jar，要么多jar。
5. 部署到Tomcat：三种方式与实操细节
5.1 直接丢进webapps目录
最简单的方式：把war包复制到Tomcat的webapps目录下，启动Tomcat。它会自动解压war包，生成同名文件夹。访问路径是http://localhost:8080/myapp。
这种方式适合快速测试，但生产环境不推荐。因为Tomcat启动时会扫描所有war包，如果包多，启动慢。而且热部署时，Tomcat会重新解压，可能造成短暂服务中断。
5.2 配置server.xml指定Context
在conf/server.xml的Host标签内加：
<Context path="/myapp" docBase="/opt/apps/myapp.war" reloadable="false" />path是访问路径，docBase是war包的绝对路径。reloadable设为false，生产环境别开，开了会频繁扫描class变化，耗性能。
这种方式的好处是war包可以放在webapps外面，方便管理。但改server.xml需要重启Tomcat。
5.3 使用context.xml独立配置
在conf/Catalina/localhost下新建myapp.xml：
<Context docBase="/opt/apps/myapp.war" reloadable="false" />文件名就是访问路径。这种方式不用改server.xml，Tomcat会自动加载。改完也不用重启，Tomcat会检测到变化。
5.4 部署后的验证步骤
部署完别急着庆祝，先做几项检查：
- 看Tomcat日志，catalina.out里有没有异常堆栈。
- 访问首页，确认静态资源能加载。
- 触发一个Servlet请求，确认类加载正常。
- 检查数据库连接，确认依赖jar都在。
注意：如果war包名带版本号，比如myapp-1.0.0.war，访问路径会变成
/myapp-1.0.0。想固定路径，要么改finalName，要么用Context配置。
6. 常见问题与排查技巧实录
6.1 启动报ClassNotFoundException
最常见的原因：依赖jar没打进WEB-INF/lib。检查pom.xml或build.gradle，确认依赖scope不是provided或test。如果是provided，Tomcat又没提供，就会找不到类。
另一个原因：jar包冲突。比如两个版本的同一个库，Tomcat加载了旧版本。用mvn dependency:tree看依赖树，排除重复。
6.2 404错误：路径对不上
访问/myapp/hello报404，先确认war包名和访问路径是否一致。如果war包叫myapp.war，访问路径就是/myapp。如果用了Context配置，path属性决定路径。
还要检查web.xml里的url-pattern，或者@WebServlet的value。大小写敏感，别写错。
6.3 500错误：初始化失败
500通常是Servlet初始化抛异常。看catalina.out里的堆栈，定位到具体行。常见原因：数据库连接配置写错、配置文件路径不对、静态初始化块报错。
如果是Spring项目，可能是applicationContext.xml没找到。确认配置文件在classes目录下。
6.4 中文乱码
Tomcat默认编码是ISO-8859-1，处理中文会乱码。解决办法：在server.xml的Connector标签加URIEncoding="UTF-8"。或者在代码里用request.setCharacterEncoding("UTF-8")。
6.5 内存溢出
war包部署后，如果频繁Full GC，可能是lib目录下jar太多，或者有内存泄漏。用jvisualvm或jmap看堆dump，定位大对象。
实操心得：我习惯在部署前用
unzip -l myapp.war列一下内容，确认WEB-INF/lib下的jar数量合理。如果超过50个，就要考虑是不是依赖没排除干净。
6.6 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
| ClassNotFoundException | 依赖未打包 | 检查scope，看lib目录 |
| 404 | 路径不匹配 | 确认war包名和url-pattern |
| 500 | 初始化异常 | 看catalina.out堆栈 |
| 中文乱码 | 编码不一致 | 加URIEncoding或setCharacterEncoding |
| 内存溢出 | 依赖过多或泄漏 | jmap看堆，排除重复jar |
| 启动慢 | war包多或扫描慢 | 减少webapps下war包，关reloadable |
7. 打包与部署的进阶经验
7.1 用profile区分环境
开发、测试、生产环境的配置不同，可以用Maven profile来管理：
<profiles> <profile> <id>prod</id> <properties> <db.url>jdbc:mysql://prod-host:3306/mydb</db.url> </properties> </profile> </profiles>打包时用mvn package -Pprod，资源文件里的占位符会被替换。
7.2 排除不必要的文件
src/main/webapp下的源码、PSD、备份文件，不该打进war包。在maven-war-plugin里配置excludes：
<configuration> <packagingExcludes>**/*.psd,**/*.bak</packagingExcludes> </configuration>7.3 自动化部署脚本
手动复制war包容易出错，写个脚本：
#!/bin/bash WAR_FILE="target/myapp.war" TOMCAT_WEBAPPS="/opt/tomcat/webapps" cp $WAR_FILE $TOMCAT_WEBAPPS/ sleep 5 tail -f /opt/tomcat/logs/catalina.out复制后等几秒，看日志确认启动成功。
7.4 版本回滚策略
每次部署前，把旧war包备份成myapp.war.bak。出问题就换回来，重启Tomcat。别小看这一步，线上故障时能救命。
7.5 个人体会
我刚开始学JavaWeb时，总觉得打包部署是“运维的事”，后来才发现，开发不懂部署，等于半条腿走路。war包这东西，看着简单，但目录结构、依赖scope、Tomcat版本匹配，每个细节都能让你卡半天。我的建议是：本地装一个干净的Tomcat，手动部署几次，把每个报错都记下来，比看十篇教程都管用。另外，别怕看日志，catalina.out里的堆栈信息，往往直接告诉你答案。最后分享一个小技巧：如果war包部署后行为诡异，先删掉webapps下解压的文件夹，让Tomcat重新解压，很多时候是缓存导致的。
