Eclipse 错误：web.xml is missing and failOnMissingWebXml is set to true

1. 引言

在使用 Eclipse 创建 Java Web 项目时，经常会遇到这样一个报错：

web.xml is missing and is set to true

这个错误提示虽然看起来简单，但如果不熟悉 Maven 和 Java Web 的工作机制，很容易踩坑。这篇文章我们就来深入分析这个问题的根源，并提供几种实用的解决方案。

2. 错误解析

在传统的 Java Web 应用中，web.xml 是部署描述符（Deployment Descriptor）的标准文件名，位于 WEB-INF/ 目录下，用于配置 Servlet、Filter、Listener 等组件。

不过从 Java EE 6 开始，官方开始推荐使用注解（Annotation）来替代 web.xml 配置，所以很多现代项目其实已经不再需要它了。

而报错中的 <failOnMissingWebXml> 是 Maven WAR Plugin 的一个配置项：

在 3.1.0 之前版本中，默认值是 true：如果找不到 web.xml，打包就会失败 ❌
在 3.1.0 及之后版本中，默认值是 false：即使没有 web.xml 也可以正常打包 ✅

所以这个错误本质上是 Maven 插件在“提醒”你：你还没配置好是否允许没有 web.xml。

3. 保留 web.xml 的做法

如果你的项目确实需要 web.xml，比如使用了老式的 XML 配置方式，或者项目依赖它来注册某些组件，那就可以简单粗暴地在 Eclipse 中生成一个：

✅ 操作步骤如下：

在项目上右键
选择 Java EE Tools
点击 Generate Deployment Descriptor Stub

这样就会自动生成一个默认的 web.xml 文件在 WEB-INF/ 下，问题也就迎刃而解了。

4. 干掉 web.xml 的做法

如果你的项目是基于注解的现代 Web 项目，根本不需要 web.xml，那就可以通过配置 Maven 插件来跳过检查。

4.1. Maven WAR Plugin 版本 < 3.1.0

这种情况下，必须手动设置 <failOnMissingWebXml> 为 false：

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.4</version>
    <configuration>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </configuration>
</plugin>

⚠️ 注意：如果你不设置这个值，Maven 打包时会直接报错 ❌

4.2. Maven WAR Plugin 版本 ≥ 3.1.0

那就简单了，啥都不用干，插件默认就允许没有 web.xml：

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <version>3.1.0</version>
</plugin>

5. 总结

这个错误虽然看起来 low，但其实背后牵扯到了 Java Web 配置方式的演进和 Maven 插件的默认行为。解决方法也很明确：

✅ 要 web.xml？ 用 Eclipse 一键生成
✅ 不要 web.xml？ 升级插件版本或手动关闭检查

📘 示例代码已上传至 GitHub：https://github.com/eugenp/tutorials/tree/master/maven-modules/maven-war-plugin

Persistence

REST

Security