踩坑分享IntelliJ IDEA 打包 Web 项目 WAR 包（含 Tomcat 部署 + 常见问题解决）

在 Java Web 开发中，“本地能跑”只是第一步，真正让很多人头疼的是后续这条链路：
项目打包 → 生成 WAR → 部署 Tomcat → 启动验证 → 排查报错。

尤其是刚从 Spring Boot 内嵌容器模式转向传统 WAR 部署、或者接手老项目时，常常会遇到：

• 明明 Maven 构建成功，但 Tomcat 启动 404；
• WAR 包里缺少依赖，运行时报 ClassNotFoundException；
• IDEA 能运行，独立 Tomcat 却报编码、路径、JDK 版本问题；
• 发布后静态资源丢失、上下文路径错误、JSP 无法访问。

这篇文章就按“可落地实战”的方式，带你完整走一遍：

1. IDEA 中正确配置并打包 WAR；
2. 在 Tomcat 中标准部署与验证；
3. 高频问题逐类定位与解决。

你可以把它当作一份“从开发机到可部署产物”的操作手册。

一、先理解 WAR 是什么，为什么还需要它？

WAR（Web Application Archive）本质是 Java Web 应用的标准发布格式。
它通常包含：

• WEB-INF/classes：编译后的 class 文件
• WEB-INF/lib：运行依赖 jar
• WEB-INF/web.xml（可选，取决于项目）
• 页面资源（JSP/HTML）
• 静态资源（css/js/images）

在现代 Spring Boot 项目里，很多场景直接打可执行 JAR 就够了；
但在这些情况下，WAR 仍很常见：

• 公司统一使用外置 Tomcat/JBoss/WebLogic
• 老系统是 Servlet/JSP 架构
• 多应用共享容器运维体系
• 交付规范要求 WAR

二、准备工作：版本与环境对齐

正式打包前，先做四项检查，能避免 80% 的坑。

1）JDK 版本一致

• IDEA Project SDK
• Maven/Gradle 使用的 JDK
• Tomcat 运行 JDK

三者尽量一致。例如都用 JDK 8 或都用 JDK 17。
不一致常导致：类版本错误（UnsupportedClassVersionError）。

2）Tomcat 版本匹配

• Servlet 3.x/4.x/5.x 与 Tomcat 版本要对应
• Jakarta 命名空间（jakarta.*）与旧 javax.* 不可混用

3）构建工具配置正确

确认 pom.xml 或 build.gradle 的 packaging 为 war。

Maven 示例（核心）：

xml

<packaging>war</packaging>

4）项目目录规范

标准 Maven Web 项目通常是：

• src/main/java
• src/main/resources
• src/main/webapp

如果你是非标准目录，需在构建配置里显式声明资源路径。

三、使用 Maven 在 IDEA 中打 WAR（推荐）

虽然 IDEA 也能用 Artifact 打包，但生产环境更建议以 Maven/Gradle 为准，可复现、可 CI。

步骤1：配置 pom.xml

一个典型 Maven Web 项目核心配置如下（示意）：

xml

<project> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>demo-web</artifactId> <version>1.0.0</version> <packaging>war</packaging> <dependencies><!-- Servlet API 由容器提供 --><dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> <scope>provided</scope> </dependency> </dependencies> <build> <finalName>demo-web</finalName> <plugins> <plugin> <artifactId>maven-war-plugin</artifactId> <version>3.4.0</version> </plugin> </plugins> </build> </project>

关键点：

• packaging 必须是 war
• 容器已提供的 API 建议 provided，避免冲突

步骤2：在 IDEA 执行打包

方式 A：右侧 Maven 面板执行 Lifecycle -> package
方式 B：终端执行：

bash

mvn clean package -DskipTests

成功后在 target/ 下得到：

• demo-web.war（可部署）
• 或展开目录（取决于配置）

四、使用 IDEA Artifact 打 WAR（可选）

如果你需要快速本地验证，也可以用 IDEA 自带打包：

1. File -> Project Structure -> Artifacts
2. + -> Web Application: Archive -> From modules...
3. 选择模块与输出目录
4. Build -> Build Artifacts -> Build

注意：
Artifact 方式依赖 IDE 配置，团队一致性不如 Maven。
建议作为补充，不作为唯一交付方式。

五、Tomcat 部署 WAR 的三种方式

方式1：直接拷贝到 webapps/

把 demo-web.war 复制到 Tomcat 的 webapps/ 目录，启动 Tomcat 自动解压部署。
访问路径通常是：

text

http://localhost:8080/demo-web/

方式2：Tomcat Manager 部署

启用 Manager 后，通过网页上传 WAR 部署，适合远程环境和运维协作。

方式3：IDEA 配置本地 Tomcat Run/Debug

1. Run -> Edit Configurations
2. 添加 Tomcat Server -> Local
3. 配置 Tomcat Home、JRE
4. 在 Deployment 里添加 Artifact: demo-web:war
5. 启动后可直接调试断点

六、上下文路径（Context Path）一定要搞清楚

很多 404 都是路径问题。常见规则：

• WAR 名称是 demo-web.war，默认 context path 是 /demo-web
• 如果你想根路径访问，可命名为 ROOT.war
• 也可以在 Tomcat conf/Catalina/localhost/*.xml 单独配置 context

示例：
ROOT.war 部署后访问：

text

http://localhost:8080/

七、Spring Boot 项目打 WAR 的额外配置

如果是 Spring Boot 改 WAR，需要额外处理：

1. packaging 改为 war
2. 内嵌 Tomcat 依赖改 provided
3. 启动类继承 SpringBootServletInitializer

示例（核心）：

java

@SpringBootApplication public class App extends SpringBootServletInitializer { @Override protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) { return builder.sources(App.class); } }

否则常见现象是：
JAR 模式能跑，WAR 部署外置 Tomcat 启动失败。

八、常见问题与解决方案（高频故障清单）

问题1：部署后 404

排查：

• 访问 URL 是否带正确 context path
• webapps 是否已解压出同名目录
• 日志是否显示应用启动成功
• Controller 路径或 servlet mapping 是否正确

问题2：ClassNotFoundException

原因：依赖未打进 WEB-INF/lib 或 scope 配错。
解决：

• 检查依赖 scope，非容器提供依赖不要写 provided
• 查看 WAR 内容是否包含缺失 jar

问题3：UnsupportedClassVersionError

原因：编译 JDK 高于运行 JDK。
解决：

• 统一 IDEA/Maven/Tomcat JDK 版本
• 配置 maven-compiler-plugin 指定 source/target

问题4：端口冲突，Tomcat 启动失败

现象：Address already in use
解决：

• 修改 conf/server.xml 的 Connector port
• 或结束占用 8080 的进程

问题5：中文乱码（请求或页面）

解决组合：

• Tomcat server.xml 设置 URIEncoding
• 过滤器统一 UTF-8
• JSP 页面声明 UTF-8
• 数据库连接串加编码参数

问题6：静态资源 404

排查：

• 资源是否打入 WAR
• Spring MVC 资源映射是否正确
• 前端构建产物目录是否复制到 webapp 或 static

问题7：JSP 无法编译或访问

排查：

• 是否引入 JSTL、JSP 相关依赖
• Tomcat 版本与 JSP/Servlet 规范匹配
• 视图解析器配置是否正确

问题8：启动很慢或卡死

排查：

• 是否扫描了过多无关包
• 数据源连接超时
• 第三方服务初始化阻塞
• 打开 JVM 启动参数与 GC 日志分析

九、日志排查建议：先看哪里？

出现部署问题时，优先看三类日志：

1. catalina.out（Linux）或控制台输出
2. 应用日志（logback/log4j）
3. IDEA Run 窗口启动日志

重点关键词：

• SEVERE
• Exception
• Caused by

经验法则：
先找第一个根因异常，不要被后续连锁报错干扰。

十、生产部署建议（避免“本地好好的”）

1. 用 Maven/Gradle 标准化打包，不依赖个人 IDE Artifact
2. 固化 JDK 与 Tomcat 版本（写进部署文档）
3. 配置分环境参数（dev/test/prod）
4. 健康检查接口与启动探针要有
5. 发布前做一次“干净环境”部署验证
6. 保留回滚包与版本号，不覆盖式发布
7. 监控 JVM、线程池、连接池、错误率

IntelliJ IDEA 打包 WAR 并部署 Tomcat，本质上不是一个“点按钮”动作，而是一条完整工程链路。
当你把以下四件事做好，成功率会大幅提升：

• 构建标准化（Maven/Gradle）
• 环境一致性（JDK/Tomcat/依赖）
• 路径与资源清晰（context、静态文件、web.xml/注解）
• 日志驱动排错（先根因、后现象）

如果你是个人开发者，这套流程能让你少走很多弯路；
如果你是团队负责人，这套规范能显著降低“部署靠玄学”的风险。

一句话总结：
WAR 部署并不难，难的是细节不统一。把细节标准化，Tomcat 部署就会变成稳定、可复制的日常操作。