1. 从一个war包说起：为什么Java Web项目离不开它

刚入行那会儿，我第一次拿到一个后缀是.war的文件，脑子里全是问号——这玩意儿跟.jar有什么区别？为什么部署到服务器上就能跑起来一个网站？后来做过的项目多了，从单体SSH/SSM到后来的Spring Boot，war包始终是Java Web世界里绕不开的一个交付形态。哪怕现在Spring Boot内嵌Tomcat大行其道，很多传统企业项目、老系统迁移、以及需要部署到外部Servlet容器的场景，依然要靠war包来交付。

简单说，war（Web Application Archive）就是一种Java Web应用的打包格式，本质是个zip压缩包，只不过内部遵循了Servlet规范约定的目录结构。它把编译后的class文件、JSP页面、静态资源、依赖jar包、配置文件全部打在一起，丢到Tomcat、Jetty、WebLogic这类Servlet容器里，容器解压后按约定加载，一个Web应用就跑起来了。这篇文章我想把三件事讲透：war包怎么打、怎么解压、怎么压缩，顺带把打包过程中那些容易踩的坑、参数背后的逻辑、以及不同构建工具（Maven、Gradle、Ant）的差异都掰开揉碎说清楚。不管你是刚接触Java Web的新手，还是想回头梳理一遍打包流程的老手，应该都能从里面找到能直接抄作业的东西。

我见过太多人打包全靠IDE右键，一旦IDE抽风或者要上CI/CD流水线就抓瞎。所以下面我会尽量用命令行和配置文件的视角来讲，让你脱离IDE也能把war包玩明白。

2. war包内部结构拆解：先搞懂它长什么样

2.1 标准目录结构长啥样

要理解打包和解压，得先知道war包解开之后应该是什么样。Servlet规范里定义得很清楚，一个标准的war包解压后大致是这样：

myapp.war ├── index.jsp ├── login.html ├── META-INF/ │ └── MANIFEST.MF └── WEB-INF/ ├── web.xml ├── classes/ │ └── com/example/... ├── lib/ │ ├── spring-core-5.3.x.jar │ └── ... └── ...

几个关键目录的作用必须记牢：

• 根目录：直接放JSP、HTML、CSS、JS、图片这些可以直接被浏览器访问的静态资源和页面。放在这里的文件，URL路径基本就是相对于应用上下文根的路径。
• WEB-INF：这是受保护目录，浏览器无法直接访问里面的内容。这是安全设计，防止别人直接下载你的class文件或者配置文件。
• WEB-INF/classes：存放编译后的.class文件和资源文件（比如application.properties、mapper.xml），包路径要和源码的package结构一致。
• WEB-INF/lib：存放应用依赖的第三方jar包。容器加载时会把这些jar加入应用的类加载器。
• WEB-INF/web.xml：部署描述符，配置Servlet、Filter、Listener、欢迎页、上下文参数等。Servlet 3.0之后可以用注解替代大部分配置，但web.xml依然存在。
• META-INF/MANIFEST.MF：元数据文件，记录版本、构建工具、主类等信息。war包一般不需要Main-Class，因为它是被容器加载而不是直接java -jar运行。

提示：很多人第一次解压war包发现找不到web.xml，别慌，Servlet 3.0+的项目可能完全用注解配置，web.xml是可选的。

2.2 war和jar、ear到底差在哪

这三个格式经常被搞混，我用一张表说清楚：

核心区别在于约定结构和加载方式。jar包没有目录约定，就是个类库；war包有严格的目录约定，容器按约定去WEB-INF/classes和WEB-INF/lib找类和依赖；ear则是更上层的打包，里面可以包含多个war和ejb jar。搞懂这个，你就明白为什么war包不能直接java -jar跑——它压根没设计成独立运行。

2.3 为什么现在还有人用war包

Spring Boot流行之后，很多人觉得war包过时了。但实际情况是，大量存量项目和特定场景依然依赖war包：

• 传统企业项目部署在统一的Tomcat集群上，运维要求所有应用以war形式交付，方便统一管理。
• 需要多个应用共享同一个Servlet容器、共享JNDI资源、共享会话的场景。
• 一些老旧的中间件和容器只认war包。
• 部分客户环境不允许内嵌容器，必须外置。

所以war包不是过时，而是适用场景不同。理解它，是Java Web工程师的基本功。

3. 打包实战：Maven、Gradle、Ant三条路线

3.1 Maven打包war：最主流的方式

Maven是现在最常用的构建工具，打war包的核心就一句话：把pom.xml里的packaging设成war。

<project> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>mywebapp</artifactId> <version>1.0.0</version> <packaging>war</packaging> ... </project>

设好之后，执行：

mvn clean package

Maven就会在target/目录下生成mywebapp-1.0.0.war。默认情况下，Maven会把src/main/webapp作为war的根目录，把src/main/java编译后的class放到WEB-INF/classes，把依赖jar放到WEB-INF/lib。

这里有个新手最容易踩的坑：如果你的项目用了Spring Boot，默认打出来的是可执行jar，想打war需要额外配置。要继承SpringBootServletInitializer并重写configure方法，同时把spring-boot-starter-tomcat的scope设为provided，否则内嵌Tomcat会和外部容器冲突。

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> <scope>provided</scope> </dependency>

provided的含义是：编译时需要，打包时不打进去，因为运行时容器会提供。这个scope选错，轻则war包体积暴涨，重则启动报类冲突。

3.2 控制war包内容和名称的实用配置

默认打出来的war包名字带版本号，部署时URL路径也会带上，很别扭。用finalName可以固定名字：

<build> <finalName>myapp</finalName> </build>

这样打出来就是myapp.war，部署后访问路径就是/myapp。

如果想把某些文件排除掉，用maven-war-plugin：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.2</version> <configuration> <warSourceExcludes>**/*.psd,**/test/**</warSourceExcludes> <failOnMissingWebXml>false</failOnMissingWebXml> </configuration> </plugin>

failOnMissingWebXml这个参数特别重要。Servlet 3.0+项目没有web.xml时，老版本插件会直接报错构建失败，设成false就能跳过检查。我见过不少人卡在这里半天找不到原因。

3.3 Gradle打包war：配置更简洁

Gradle打war包需要应用war插件：

plugins { id 'war' } war { archiveFileName = 'myapp.war' from 'src/main/webapp' }

执行gradle war即可。Gradle默认也是把src/main/webapp作为web根目录。如果用了Spring Boot，同样需要把内嵌容器的依赖改成providedRuntime：

dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat' }

providedRuntime对应Maven的provided，含义一致。Gradle的配置比Maven简洁，但灵活性上要写自定义任务时反而更绕，看个人习惯。

3.4 Ant打包war：老项目的救命稻草

虽然现在用Ant的少了，但维护老项目时经常遇到。Ant打war靠的是war任务：

<target name="war"> <war destfile="build/myapp.war" webxml="WebContent/WEB-INF/web.xml"> <fileset dir="WebContent"> <exclude name="WEB-INF/web.xml"/> </fileset> <lib dir="lib"/> <classes dir="build/classes"/> </war> </target>

war任务里，fileset指定web根目录内容，lib指定依赖jar，classes指定编译后的class。注意webxml属性指定的文件会被放到WEB-INF/web.xml，所以fileset里要把它排除掉，否则重复。这个细节不注意，打出来的war包可能有两个web.xml导致容器解析异常。

3.5 三种方式对比与选型建议

我的建议很直接：新项目无脑Maven或Gradle，老项目继续用Ant别折腾。迁移构建工具的成本往往比收益高，除非有明确的重构需求。

4. 解压与压缩：命令行实操全流程

4.1 用unzip解压war包

war包本质是zip，所以任何解压zip的工具都能解。Linux/macOS下最常用的是unzip：

# 解压到当前目录 unzip myapp.war # 解压到指定目录 unzip myapp.war -d ./myapp_extracted # 查看war包内容但不解压 unzip -l myapp.war # 覆盖已存在文件，不提示 unzip -o myapp.war -d ./myapp_extracted

-l参数特别有用，部署前想确认war包里到底有没有某个配置文件，直接列出来看，不用解压。-o在脚本里很关键，否则遇到同名文件会交互式询问，卡住自动化流程。

如果系统没装unzip，可以用jar命令（JDK自带）：

jar -xvf myapp.war

-x解压，-v显示过程，-f指定文件。jar命令的好处是只要有JDK就能用，不依赖额外工具。

4.2 用zip重新压缩成war包

改完war包里的配置想重新打包，用zip命令：

# 进入解压后的目录，从内部打包 cd myapp_extracted zip -r ../myapp_new.war . # 排除某些文件 zip -r ../myapp_new.war . -x "*.DS_Store" -x "__MACOSX/*"

这里有个极其重要的坑：必须在解压目录内部执行zip，且用.作为源。如果你在外部执行zip -r myapp.war myapp_extracted/，打出来的war包最外层会多一层myapp_extracted/目录，容器找不到WEB-INF，直接部署失败。这个错误我见过太多次，排查起来还特别费劲，因为war包看起来"没问题"。

-x排除参数在macOS下尤其重要，.DS_Store和__MACOSX这些系统文件混进去虽然一般不影响运行，但会让war包不干净，专业交付时最好排除。

4.3 用jar命令压缩的替代方案

不想用zip的话，jar命令也能打包：

cd myapp_extracted jar -cvf ../myapp_new.war .

-c创建，-v显示，-f指定输出文件。同样要注意在目录内部执行。jar命令打出来的包和zip基本兼容，容器都能识别。

4.4 解压压缩的常见错误与规避

我把这块最容易出问题的地方整理成一张速查表：

注意：在Windows上用压缩软件手动打war包时，一定要选"zip"格式而不是"rar"或"7z"，且压缩时不要勾选"添加顶层目录"，否则同样会多一层。

5. 打包参数背后的逻辑：为什么这么配

5.1 scope的选择决定了war包的体积和稳定性

Maven的scope是打包时最容易被忽视、又最影响结果的东西。我重点说三个：

• compile（默认）：编译、测试、运行都需要，会被打进war包的WEB-INF/lib。绝大多数业务依赖用这个。
• provided：编译和测试需要，运行时由容器提供，不打进war包。Servlet API、JSP API、内嵌Tomcat必须用这个，否则和容器自带的冲突。
• test：只有测试需要，不打进war包。JUnit、Mockito用这个。

选错scope的后果很直接：把servlet-api用compile打进去，部署到Tomcat可能报ClassCastException或者类加载冲突；把测试依赖用compile打进去，war包白白大几十兆。判断标准很简单：运行时容器会不会提供？会，就用provided；不会，就用compile。

5.2 finalName和context path的关系

很多人以为finalName只是改个文件名，其实它直接影响部署后的访问路径。Tomcat默认用war文件名（去掉.war）作为context path。myapp.war部署后访问就是http://host:8080/myapp/。如果你想要根路径访问，要么把war改名成ROOT.war，要么在Tomcat的server.xml或context.xml里显式配置context path。这个逻辑不理解，部署后访问路径对不上就会一脸懵。

5.3 依赖冲突的排查思路

war包部署后启动报NoSuchMethodError、ClassNotFoundException，十有八九是依赖冲突。排查步骤：

1. 用mvn dependency:tree打印依赖树，找同一个库的多个版本。
2. 用mvn dependency:analyze找未使用和未声明的依赖。
3. 在pom里用<exclusions>排除掉传递进来的旧版本。
4. 必要时用<dependencyManagement>统一版本。

我个人的习惯是，项目稳定后跑一次dependency:tree，把明显重复的版本用exclusion清掉，能省掉后面很多莫名其妙的运行时错误。

6. 常见问题与排查技巧实录

6.1 部署后访问404的排查顺序

这是最高频的问题，我按排查优先级列一下：

1. 确认war包结构：unzip -l myapp.war看最外层是不是直接就是WEB-INF，如果多了一层目录，就是打包方式错了。
2. 确认context path：看Tomcat日志里应用启动的context是什么，访问路径对不对。
3. 确认应用是否真的启动成功：看日志有没有Deployment of web application archive ... has finished，有没有异常。
4. 确认欢迎页配置：访问根路径404但访问具体页面正常，多半是web.xml或index.jsp的问题。
5. 确认端口和防火墙：这个最基础但偶尔也会中招。

6.2 中文乱码问题的根源

war包里如果有中文文件名或中文内容，乱码通常来自两个地方：一是打包时zip的编码，二是应用运行时的字符编码。打包层面，Linux下用zip -r一般没问题，Windows下用图形工具要注意选UTF-8。应用层面，要在web.xml里配CharacterEncodingFilter，或者用Spring的CharacterEncodingFilter统一设成UTF-8。这两个层面都处理了，乱码基本就绝迹了。

6.3 war包体积优化的几个手段

war包太大，上传部署慢，可以从这几方面优化：

• 检查scope，把provided和test的依赖清出去。
• 用mvn dependency:analyze找出没用到的依赖删掉。
• 排除依赖里的重复资源，比如多个jar里都带的license文件。
• 静态资源做压缩，图片用工具压一遍。
• 必要时把大依赖（如某些SDK）放到容器的共享lib目录，用provided引入。

我做过一个项目，war包从180M优化到60M，主要就是清理了scope错误和重复依赖，效果立竿见影。

6.4 常见问题速查表

6.5 我踩过的几个真实坑

说几个印象深刻的。有一次改完web.xml重新打包，部署后配置死活不生效，折腾半天发现是打包时把旧的web.xml也带进去了，容器加载了旧的那个。还有一次war包在本地Tomcat跑得好好的，上测试环境就报类冲突，最后查出来是测试环境的容器lib目录里有个同名的旧版本jar，和war包里的冲突了。这类问题没有捷径，就是解压看结构、看日志找异常、对比环境差异这三板斧。

另外一个经验：永远不要在生产环境直接改war包里的文件。改完当时能用，下次重新部署就丢了，而且没人记得改过什么。要改就改源码重新构建，或者把配置外置到容器层面。

7. 从war包延伸出去的几个实用场景

7.1 CI/CD流水线里怎么处理war包

在自动化流水线里，war包的处理通常是：构建阶段mvn clean package产出war，制品库归档，部署阶段把war推到目标服务器的容器部署目录，然后触发容器重新加载或重启。关键点是war包要带版本号归档，部署时用软链接指向当前版本，回滚时切换软链接即可。这套做法比直接覆盖war文件稳妥得多，出问题能秒回滚。

7.2 热部署与war包的关系

Tomcat支持热部署，把新war丢进webapps目录，容器检测到会自动解压部署。但生产环境我不建议依赖热部署，因为热部署可能带来内存泄漏和类加载器残留。稳妥做法是停应用、替换war、启应用。开发环境用热部署提效没问题，生产环境还是老实点。

7.3 war包和Docker的结合

现在容器化部署流行，war包也能进Docker。典型做法是基础镜像用Tomcat，把war包COPY进webapps目录，构建成应用镜像。这样既保留了war包的交付形态，又享受了容器化的便利。Dockerfile大概长这样：

FROM tomcat:9-jdk11 RUN rm -rf /usr/local/tomcat/webapps/* COPY target/myapp.war /usr/local/tomcat/webapps/ROOT.war EXPOSE 8080

注意把war命名成ROOT.war就能以根路径访问，省去context path的麻烦。这个技巧在容器化场景里特别实用。

war包这个东西，说简单也简单，说坑也多。核心就三件事：结构要对、scope要对、打包方式要对。把这三样吃透，剩下的都是熟练度问题。我个人的习惯是，任何war包交付前都先unzip -l看一眼结构，确认最外层是WEB-INF而不是多套了一层目录，这个动作花不了十秒，能省掉后面一堆排查时间。另外，构建配置尽量写进pom或build文件里，别依赖IDE的图形化配置，这样换台机器、上流水线都不会出岔子。