1. 从一个war包说起为什么Java Web项目离不开它刚入行那会儿我第一次拿到一个后缀是.war的文件脑子里全是问号——这玩意儿跟.jar有什么区别为什么部署到服务器上就能跑起来一个网站后来做过的项目多了从单体SSH/SSM到后来的Spring Bootwar包始终是Java Web世界里绕不开的一个交付形态。哪怕现在Spring Boot内嵌Tomcat大行其道很多传统企业项目、老系统迁移、以及需要部署到外部Servlet容器的场景依然要靠war包来交付。简单说warWeb 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到底差在哪这三个格式经常被搞混我用一张表说清楚格式全称用途运行方式典型容器jarJava Archive普通Java类库或可执行程序java -jar或作为依赖JVMwarWeb Application ArchiveJava Web应用部署到Servlet容器Tomcat/JettyearEnterprise Archive企业级应用含多个模块部署到Java EE容器WebLogic/WAS核心区别在于约定结构和加载方式。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 modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmywebapp/artifactId version1.0.0/version packagingwar/packaging ... /project设好之后执行mvn clean packageMaven就会在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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId scopeprovided/scope /dependencyprovided的含义是编译时需要打包时不打进去因为运行时容器会提供。这个scope选错轻则war包体积暴涨重则启动报类冲突。3.2 控制war包内容和名称的实用配置默认打出来的war包名字带版本号部署时URL路径也会带上很别扭。用finalName可以固定名字build finalNamemyapp/finalName /build这样打出来就是myapp.war部署后访问路径就是/myapp。如果想把某些文件排除掉用maven-war-pluginplugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-war-plugin/artifactId version3.3.2/version configuration warSourceExcludes**/*.psd,**/test/**/warSourceExcludes failOnMissingWebXmlfalse/failOnMissingWebXml /configuration /pluginfailOnMissingWebXml这个参数特别重要。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同样需要把内嵌容器的依赖改成providedRuntimedependencies { 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 namewar war destfilebuild/myapp.war webxmlWebContent/WEB-INF/web.xml fileset dirWebContent exclude nameWEB-INF/web.xml/ /fileset lib dirlib/ classes dirbuild/classes/ /war /targetwar任务里fileset指定web根目录内容lib指定依赖jarclasses指定编译后的class。注意webxml属性指定的文件会被放到WEB-INF/web.xml所以fileset里要把它排除掉否则重复。这个细节不注意打出来的war包可能有两个web.xml导致容器解析异常。3.5 三种方式对比与选型建议维度MavenGradleAnt配置方式XML啰嗦但直观Groovy/Kotlin DSL简洁XML全手动依赖管理内置强大内置更灵活需手动管理学习曲线平缓中等陡峭要自己写流程适合场景绝大多数新项目追求构建性能的项目维护老项目war打包便利度高高中我的建议很直接新项目无脑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 解压压缩的常见错误与规避我把这块最容易出问题的地方整理成一张速查表现象原因解决部署后404war包多了一层目录进入目录内部用.打包中文文件名乱码zip编码问题用zip -r并确保文件名UTF-8解压后class缺失打包时漏了classes目录检查构建输出路径部署报web.xml重复打包时web.xml被放了两次排除重复的web.xmlwar包体积异常大依赖scope错误测试依赖被打入检查provided/test scope权限问题无法解压文件属主或权限不对chmod调整或换用户操作注意在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十有八九是依赖冲突。排查步骤用mvn dependency:tree打印依赖树找同一个库的多个版本。用mvn dependency:analyze找未使用和未声明的依赖。在pom里用exclusions排除掉传递进来的旧版本。必要时用dependencyManagement统一版本。我个人的习惯是项目稳定后跑一次dependency:tree把明显重复的版本用exclusion清掉能省掉后面很多莫名其妙的运行时错误。6. 常见问题与排查技巧实录6.1 部署后访问404的排查顺序这是最高频的问题我按排查优先级列一下确认war包结构unzip -l myapp.war看最外层是不是直接就是WEB-INF如果多了一层目录就是打包方式错了。确认context path看Tomcat日志里应用启动的context是什么访问路径对不对。确认应用是否真的启动成功看日志有没有Deployment of web application archive ... has finished有没有异常。确认欢迎页配置访问根路径404但访问具体页面正常多半是web.xml或index.jsp的问题。确认端口和防火墙这个最基础但偶尔也会中招。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 常见问题速查表问题可能原因快速排查启动报ClassNotFound依赖没打进lib或scope错解压看WEB-INF/lib启动报类冲突同一库多版本dependency:tree访问404目录结构或context pathunzip -l 看日志中文乱码编码未统一检查filter和打包编码部署超时war包过大优化体积静态资源404放错目录确认在web根而非WEB-INF配置文件没生效被覆盖或路径错解压确认文件位置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的图形化配置这样换台机器、上流水线都不会出岔子。 
长河君 · 2026/10/24 0:18:48 · 阅读 1.2k Java war包打包解压压缩全攻略：Maven、Gradle、Ant实战与避坑指南
1. 从一个war包说起为什么Java Web项目离不开它刚入行那会儿我第一次拿到一个后缀是.war的文件脑子里全是问号——这玩意儿跟.jar有什么区别为什么部署到服务器上就能跑起来一个网站后来做过的项目多了从单体SSH/SSM到后来的Spring Bootwar包始终是Java Web世界里绕不开的一个交付形态。哪怕现在Spring Boot内嵌Tomcat大行其道很多传统企业项目、老系统迁移、以及需要部署到外部Servlet容器的场景依然要靠war包来交付。简单说warWeb 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到底差在哪这三个格式经常被搞混我用一张表说清楚格式全称用途运行方式典型容器jarJava Archive普通Java类库或可执行程序java -jar或作为依赖JVMwarWeb Application ArchiveJava Web应用部署到Servlet容器Tomcat/JettyearEnterprise Archive企业级应用含多个模块部署到Java EE容器WebLogic/WAS核心区别在于约定结构和加载方式。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 modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmywebapp/artifactId version1.0.0/version packagingwar/packaging ... /project设好之后执行mvn clean packageMaven就会在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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId scopeprovided/scope /dependencyprovided的含义是编译时需要打包时不打进去因为运行时容器会提供。这个scope选错轻则war包体积暴涨重则启动报类冲突。3.2 控制war包内容和名称的实用配置默认打出来的war包名字带版本号部署时URL路径也会带上很别扭。用finalName可以固定名字build finalNamemyapp/finalName /build这样打出来就是myapp.war部署后访问路径就是/myapp。如果想把某些文件排除掉用maven-war-pluginplugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-war-plugin/artifactId version3.3.2/version configuration warSourceExcludes**/*.psd,**/test/**/warSourceExcludes failOnMissingWebXmlfalse/failOnMissingWebXml /configuration /pluginfailOnMissingWebXml这个参数特别重要。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同样需要把内嵌容器的依赖改成providedRuntimedependencies { 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 namewar war destfilebuild/myapp.war webxmlWebContent/WEB-INF/web.xml fileset dirWebContent exclude nameWEB-INF/web.xml/ /fileset lib dirlib/ classes dirbuild/classes/ /war /targetwar任务里fileset指定web根目录内容lib指定依赖jarclasses指定编译后的class。注意webxml属性指定的文件会被放到WEB-INF/web.xml所以fileset里要把它排除掉否则重复。这个细节不注意打出来的war包可能有两个web.xml导致容器解析异常。3.5 三种方式对比与选型建议维度MavenGradleAnt配置方式XML啰嗦但直观Groovy/Kotlin DSL简洁XML全手动依赖管理内置强大内置更灵活需手动管理学习曲线平缓中等陡峭要自己写流程适合场景绝大多数新项目追求构建性能的项目维护老项目war打包便利度高高中我的建议很直接新项目无脑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 解压压缩的常见错误与规避我把这块最容易出问题的地方整理成一张速查表现象原因解决部署后404war包多了一层目录进入目录内部用.打包中文文件名乱码zip编码问题用zip -r并确保文件名UTF-8解压后class缺失打包时漏了classes目录检查构建输出路径部署报web.xml重复打包时web.xml被放了两次排除重复的web.xmlwar包体积异常大依赖scope错误测试依赖被打入检查provided/test scope权限问题无法解压文件属主或权限不对chmod调整或换用户操作注意在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十有八九是依赖冲突。排查步骤用mvn dependency:tree打印依赖树找同一个库的多个版本。用mvn dependency:analyze找未使用和未声明的依赖。在pom里用exclusions排除掉传递进来的旧版本。必要时用dependencyManagement统一版本。我个人的习惯是项目稳定后跑一次dependency:tree把明显重复的版本用exclusion清掉能省掉后面很多莫名其妙的运行时错误。6. 常见问题与排查技巧实录6.1 部署后访问404的排查顺序这是最高频的问题我按排查优先级列一下确认war包结构unzip -l myapp.war看最外层是不是直接就是WEB-INF如果多了一层目录就是打包方式错了。确认context path看Tomcat日志里应用启动的context是什么访问路径对不对。确认应用是否真的启动成功看日志有没有Deployment of web application archive ... has finished有没有异常。确认欢迎页配置访问根路径404但访问具体页面正常多半是web.xml或index.jsp的问题。确认端口和防火墙这个最基础但偶尔也会中招。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 常见问题速查表问题可能原因快速排查启动报ClassNotFound依赖没打进lib或scope错解压看WEB-INF/lib启动报类冲突同一库多版本dependency:tree访问404目录结构或context pathunzip -l 看日志中文乱码编码未统一检查filter和打包编码部署超时war包过大优化体积静态资源404放错目录确认在web根而非WEB-INF配置文件没生效被覆盖或路径错解压确认文件位置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的图形化配置这样换台机器、上流水线都不会出岔子。