企业官网建设流程全解析

1. 从一个被忽略的部署事故说起

前阵子帮一个朋友排查线上问题，场景很典型：他用 Maven 打了一个 war 包，扔到 Tomcat 的webapps目录下，重启之后访问 404。他反复确认代码没问题、本地 IDE 里跑得好好的，但就是部署不上去。最后定位到的原因让人哭笑不得——他为了"图省事"，直接把开发目录里的target/xxx.war用解压工具解开，改了一个配置文件，然后又用普通压缩工具重新压成了一个 zip，改后缀名成.war丢进去。结果这个 war 包的目录结构里多了一层文件夹，WEB-INF和META-INF不在根目录，Tomcat 自然找不到入口。

这件事让我意识到，war这个格式虽然天天在用，但真正能把"打包、解压、压缩、目录结构"这几件事讲清楚的人并不多。很多人对 war 的认知停留在"Java Web 项目打成的包"，但一旦涉及到手工改配置、重新压缩、跨环境部署，就很容易踩坑。这篇内容就围绕 war 包的打包命令、解压命令、压缩命令这三条主线展开，把 Java 项目从源码到可部署 war 包的完整链路讲透，同时把那些文档里不会写、只有踩过才知道的细节一并交代清楚。

不管你是刚接触 Java Web 的新手，还是已经工作几年但一直用 IDE 一键打包、从没手工敲过命令的老手，这篇内容都能帮你把这块知识补全。因为一旦涉及到 CI/CD 流水线、容器化部署、离线环境发布，手工操作 war 包几乎是绕不开的基本功。

2. war 包到底是什么：先搞懂它的目录结构

2.1 war 与 jar 的本质区别

很多人第一次接触 war 会问：它和 jar 有什么区别？从技术上讲，war 本质上就是一个 jar，都是 ZIP 格式的归档文件，只是扩展名不同、约定的内部结构不同。jar 通常用来打包普通的 Java 类库或可执行程序，而 war（Web Application Archive）是专门为 Web 应用设计的归档格式，它有一套 Servlet 规范约定的目录结构。

你可以把 war 理解成一个"有固定房间布局的房子"：jar 是随便你怎么摆的仓库，war 则是规定了厨房在哪、卧室在哪的精装房。Web 容器（Tomcat、Jetty、Undertow 等）会按照这套约定去房子里找东西，找不到就报错。

2.2 标准 war 包的目录布局

一个规范的 war 包解压后，根目录下通常长这样：

myapp.war (解压后) ├── index.jsp ├── static/ │ ├── css/ │ └── js/ ├── WEB-INF/ │ ├── web.xml │ ├── classes/ │ │ └── com/example/... │ ├── lib/ │ │ ├── spring-core.jar │ │ └── ... │ └── views/ └── META-INF/ └── MANIFEST.MF

这里有几个关键点必须记住：

• WEB-INF和META-INF必须在根目录，这是硬性约定。如果你解压后看到的是myapp/WEB-INF/...这种多一层的情况，说明打包时把父目录也打进去了，部署必然失败。
• WEB-INF/classes放的是编译后的.class文件和资源文件（如application.properties）。
• WEB-INF/lib放的是项目依赖的第三方 jar 包。
• WEB-INF目录对外不可直接访问，这是安全设计，浏览器无法直接请求WEB-INF下的资源，所以配置文件放这里相对安全。
• 根目录下的静态资源和 JSP是可以被外部直接访问的。

提示：web.xml在 Servlet 3.0 之后变成了可选配置，很多项目用注解或 Java Config 替代了它。但目录结构约定依然不变。

2.3 为什么目录结构这么重要

因为 Web 容器的类加载器是按目录约定去加载资源的。Tomcat 启动一个 Web 应用时，会做这几件事：读取WEB-INF/web.xml（如果存在）初始化 Servlet、把WEB-INF/classes和WEB-INF/lib/*.jar加入应用的类加载路径、把根目录作为静态资源根。任何一环的路径不对，应用就起不来或者访问不到。

我见过最隐蔽的一个坑是：有人用命令行jar命令打包时，在WEB-INF目录内部执行了打包命令，导致打出来的包里根目录直接就是classes、lib，少了WEB-INF这一层。这种包在本地某些宽松的容器里可能"碰巧"能跑，换一个严格的环境立刻挂掉。所以理解目录结构不是纸上谈兵，它直接决定了你的包能不能用。

3. Java 项目打包成 war 的几条主流路径

3.1 Maven 打包：最通用的方式

Maven 是目前 Java Web 项目打包 war 最主流的方式。核心操作就一条命令：

mvn clean package

但这条命令背后有几个关键前提，很多人忽略了：

第一，pom.xml里的打包类型必须是 war。

<packaging>war</packaging>

如果不写这一行，Maven 默认按 jar 打包，你拿到的就是 jar 而不是 war。这是新手最常犯的错误之一。

第二，需要引入maven-war-plugin。虽然 Maven 有默认的 war 打包行为，但显式配置插件能让你控制更多细节，比如指定web.xml路径、排除某些文件、自定义webappDirectory：

<build> <finalName>myapp</finalName> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.4.0</version> <configuration> <warSourceDirectory>src/main/webapp</warSourceDirectory> <failOnMissingWebXml>false</failOnMissingWebXml> </configuration> </plugin> </plugins> </build>

这里failOnMissingWebXml设为false很关键。Servlet 3.0 之后很多项目没有web.xml，如果不设这个参数，Maven 打包时会直接报错说找不到web.xml。这个坑我踩过不止一次，尤其是接手老项目改造成注解配置的时候。

第三，finalName决定 war 包的名字。不配置的话，默认是artifactId-version.war，比如demo-1.0.0.war。部署到 Tomcat 后，访问路径就是/demo-1.0.0，很多人以为访问/demo结果 404，就是没注意这个。配置<finalName>myapp</finalName>后，包名就是myapp.war，访问路径就是/myapp。

打包完成后，产物在target/目录下。你可以用ls -lh target/*.war确认包的大小和生成时间。

3.2 Gradle 打包：更灵活的写法

用 Gradle 的项目，打包 war 需要应用war插件：

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

执行命令：

./gradlew clean war

产物同样在build/libs/目录下。Gradle 的 war 插件默认也会遵循src/main/webapp作为 web 资源目录的约定，和 Maven 保持一致。

3.3 纯手工打包：离线环境的救命稻草

有些场景下你没有 Maven、没有 Gradle，甚至没有网络，只能手工打包。这时候就要用 JDK 自带的jar命令。假设你的项目已经编译好，目录结构是这样的：

build/ ├── index.html ├── static/ └── WEB-INF/ ├── web.xml ├── classes/ └── lib/

那么打包命令是：

cd build jar -cvf ../myapp.war .

注意几个细节：

• 必须在build目录内部执行，用.表示打包当前目录的所有内容，这样WEB-INF才会在 war 包的根目录。
• -c创建、-v显示过程、-f指定文件名，这是jar命令的三个基础参数。
• 如果你在build的上级目录执行jar -cvf myapp.war build/，打出来的包里根目录会是build/，多了一层，部署就废了。这是手工打包最容易犯的错。

注意：jar命令打出来的包，META-INF/MANIFEST.MF会自动生成。如果你需要自定义Class-Path等属性，可以先用jar -x解压，改完再重新打包，或者用jar -m指定 manifest 文件。

3.4 三种方式怎么选

我的建议是：日常开发用 Maven 或 Gradle，把打包命令固化到 CI 脚本里；只有在离线环境或者需要临时改包的时候，才动用手工jar命令。而且手工打包前，一定要先解压一个标准 war 包对照目录结构，确认无误再压。

4. war 包解压：不只是双击那么简单

4.1 用 jar 命令解压

JDK 自带的jar命令可以直接解压 war：

jar -xvf myapp.war

-x表示解压，-v显示过程，-f指定文件。解压后会在当前目录生成WEB-INF、META-INF等目录。所以执行前最好先建一个空目录并cd进去，避免污染当前工作区：

mkdir myapp_extracted && cd myapp_extracted jar -xvf ../myapp.war

4.2 用 unzip 命令解压

因为 war 本质是 ZIP，所以unzip也能用：

unzip myapp.war -d myapp_extracted

-d指定解压目标目录，比jar命令更直观。如果只想看包里的内容而不解压，用：

unzip -l myapp.war

这会列出包内所有文件，非常适合快速确认目录结构对不对。我排查 war 包问题时，第一步永远是unzip -l看一眼根目录有没有WEB-INF。

4.3 解压后要重点检查什么

解压不是目的，检查才是。我一般会重点看这几项：

• 根目录是否有WEB-INF：没有就是打包结构错了。
• WEB-INF/lib里的依赖是否完整：有时候 Maven 的providedscope 依赖不会被打进去，如果容器本身没提供，运行时就报ClassNotFoundException。
• WEB-INF/classes里是否有编译后的 class：如果只有源码没有 class，说明打包时没编译。
• META-INF/MANIFEST.MF内容：看看有没有异常的Class-Path配置。

4.4 解压后修改再重新压缩的正确姿势

这是最容易出事的环节。假设你解压后改了WEB-INF/classes/application.properties，想重新压回 war。正确做法是：

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

关键还是那个.——在解压目录内部执行，保证WEB-INF在根目录。如果你用图形化压缩工具（比如某些系统自带的归档管理器），一定要确认压缩时没有多包一层文件夹。很多图形工具默认会把选中的文件夹本身也打进去，导致结构变成myapp_extracted/WEB-INF/...，这就是文章开头那个朋友踩的坑。

提示：重新打包后，务必用unzip -l myapp_new.war | head -20确认根目录结构，再部署。这一步花不了十秒，能省掉半小时的排查。

5. war 压缩命令的细节与常见误区

5.1 压缩命令的本质

前面反复提到，war 就是 ZIP。所以"压缩成 war"本质上就是"用 ZIP 格式归档，并把扩展名命名为.war"。理解了这一点，很多命令就通了：

# 用 zip 命令压缩（在项目目录内部执行） zip -r ../myapp.war .

-r表示递归压缩子目录。同样，.保证根目录结构正确。

5.2 压缩时的编码问题

这是一个非常隐蔽的坑。如果你的项目里有中文文件名，用jar或zip命令压缩时，可能会因为编码不一致导致文件名乱码。jar命令默认使用系统编码，在有些环境下会出现中文文件名变成乱码的情况。

解决办法有两个：一是尽量避免在 war 包内使用中文文件名（推荐，Web 资源用英文命名是基本规范）；二是如果必须用，压缩和解压时保持编码一致，比如用zip时注意-UN=UTF8之类的参数（不同版本支持情况不同，需实测）。

5.3 压缩级别与包体积

zip命令支持压缩级别参数-0到-9，-0是不压缩只归档，-9是最高压缩率。对于 war 包，我的经验是：

• 默认级别（-6）足够用，包体积和压缩时间的平衡最好。
• 不要用 -0，虽然打包快，但包会大很多，传输和部署都吃亏。
• -9 收益有限，jar 文件本身已经是压缩过的，再压收益很小，反而拖慢构建。

5.4 一个真实的排查案例

之前有个项目，CI 流水线打出来的 war 包部署后总是报NoClassDefFoundError，但本地打包就正常。排查过程是这样的：

1. 先用unzip -l对比本地包和 CI 包的目录结构，发现 CI 包里WEB-INF/lib少了一个关键 jar。
2. 查 CI 脚本，发现打包前执行了mvn clean package -DskipTests，但流水线里配置了一个 profile，把某个依赖设成了provided。
3. 而本地打包用的是默认 profile，依赖是compilescope，所以被打进去了。
4. 最终定位到是 profile 配置差异导致依赖 scope 不同。

这个案例说明，war 包的问题往往不在打包命令本身，而在打包前的依赖解析和 profile 配置。所以排查 war 包问题时，不要只盯着命令，要往上游看。

6. 部署视角：war 包放进去之后发生了什么

6.1 Tomcat 的自动解压机制

把 war 包丢进 Tomcat 的webapps目录，启动 Tomcat 后，它会自动做两件事：把 war 解压成一个同名文件夹，然后加载这个应用。所以你会看到webapps下同时存在myapp.war和myapp/目录。

这里有个坑：如果你更新了 war 包但没删掉旧的解压目录，Tomcat 可能不会重新解压，导致你部署的还是旧代码。正确做法是：更新 war 包时，先停 Tomcat，删掉旧的myapp/目录和myapp.war，放入新 war，再启动。或者直接删掉解压目录，让 Tomcat 重新解压。

6.2 访问路径与 context path

war 包的名字决定了访问路径。myapp.war部署后，访问路径是http://host:port/myapp/。如果想让它作为根应用访问（直接http://host:port/），需要把 war 包改名为ROOT.war。这是很多新手不知道的技巧。

6.3 部署失败的常见原因清单

7. 我踩过的那些 war 包坑与经验总结

7.1 依赖 scope 的坑

Maven 的providedscope 表示"编译时需要，运行时由容器提供"。典型的是servlet-api，Tomcat 自带，所以打成provided。但如果你把某个业务依赖也误设成provided，打包时它不会进WEB-INF/lib，运行时就会ClassNotFoundException。我的习惯是：打包后一定unzip -l检查WEB-INF/lib里的 jar 数量，和mvn dependency:list的输出对一下。

7.2 重复依赖的坑

有时候WEB-INF/lib里会出现同一个库的多个版本，比如spring-core-5.2.jar和spring-core-5.3.jar同时存在。这通常是依赖传递导致的。虽然不一定会立刻报错，但可能引发诡异的行为。用mvn dependency:tree可以排查，发现冲突后用<exclusions>排除。

7.3 配置文件外置的坑

很多项目希望配置文件不打进 war，而是放在外部目录，方便改配置不用重新打包。做法是在pom.xml里用maven-war-plugin的<packagingExcludes>排除配置文件，然后在启动时通过-D参数或环境变量指定外部配置路径。这个方案在生产环境很常见，但要注意排除的路径写对，否则会把不该排除的也排掉。

7.4 手工改包后忘记验证的坑

这是最不该犯但最常犯的。手工解压、改配置、重新压缩之后，一定要做两件事：一是unzip -l确认结构，二是本地起一个容器跑一下。我见过太多人改完直接扔生产，结果因为多了一层目录或者漏了文件，导致线上事故。

7.5 关于压缩工具的选择

图形化压缩工具（各种归档管理器）在打 war 包时经常"自作聪明"，比如自动添加__MACOSX目录、自动改变目录层级。我的建议是：打 war 包一律用命令行，jar或zip都行，可控性远高于图形工具。如果非要用图形工具，压缩前务必确认"不包含父目录"这个选项。

8. 把 war 包操作固化进日常流程

聊了这么多命令和坑，最后说点实操层面的建议。war 包的打包、解压、压缩这些操作，不应该靠记忆和手敲，而应该固化进脚本和流程里。

对于日常开发，把mvn clean package写进 Makefile 或者 shell 脚本，统一包名和输出路径。对于 CI/CD，把打包命令写进流水线配置，并且在打包后加一步自动校验——用unzip -l检查根目录是否有WEB-INF，没有就直接让流水线失败。这一步能拦住绝大多数低级错误。

对于需要手工改包的应急场景，我的习惯是准备一个repack.sh脚本，内容就是解压到临时目录、改文件、重新压缩、校验结构这一套，避免每次手敲命令时漏掉关键步骤。脚本里那行unzip -l | grep WEB-INF的校验，救过我至少三次。

war 这个格式看起来简单，但它的每一个细节都和部署结果直接挂钩。把打包、解压、压缩这三件事的底层逻辑搞清楚，再配合几个校验习惯，你就能避开绝大多数部署事故。这些经验不是从文档里抄来的，而是一次次 404 和 500 换来的，希望对你有用。