web.xml是什么 如何用它来配置Java Web应用

web.xml是Java Web应用的部署描述文件，属于Servlet规范的一部分，通常存放在Web应用的WEB-INF目录下。它的作用是告诉Servlet容器（比如Tomcat）当前Web应用包含哪些组件、各个组件的初始化参数、请求映射规则、全局配置信息等，是传统Java Web应用配置的核心文件。

web.xml的核心作用

web.xml主要承担以下几类配置工作：

• 注册和配置Servlet组件，指定Servlet的处理类、访问路径和初始化参数
• 配置过滤器Filter，定义请求拦截规则和过滤逻辑的执行顺序
• 注册监听器Listener，监听应用生命周期、会话状态等事件
• 配置全局的上下文参数，供整个应用的组件读取使用
• 定义错误页面，指定不同错误码或异常类型对应的跳转页面
• 配置欢迎页面，设置应用访问根路径时的默认展示页面

web.xml的基础结构

一个标准的web.xml文件需要遵循Servlet规范的XML格式，根元素是<web-app>，不同版本的Servlet规范对应不同的<web-app>命名空间和版本号。以下是Servlet 3.0版本的web.xml基础结构示例：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
         http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">
    <!-- 配置内容写在这里 -->
</web-app>

常用配置场景与示例

1. 配置Servlet

配置Servlet需要指定Servlet的名称、处理类，以及对应的访问路径，还可以添加初始化参数。示例如下：

<web-app>
    <!-- 配置Servlet -->
    <servlet>
        <servlet-name>userServlet</servlet-name>
        <servlet-class>com.example.web.UserServlet</servlet-class>
        <!-- 初始化参数 -->
        <init-param>
            <param-name>encoding</param-name>
            <param-value>UTF-8</param-value>
        </init-param>
        <!-- 启动优先级，数字越小优先级越高，负数或不配置则首次访问时初始化 -->
        <load-on-startup>1</load-on-startup>
    </servlet>
    <!-- 映射Servlet访问路径 -->
    <servlet-mapping>
        <servlet-name>userServlet</servlet-name>
        <url-pattern>/user/*</url-pattern>
    </servlet-mapping>
</web-app>

对应的Servlet处理类示例：

package com.example.web;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class UserServlet extends HttpServlet {
    private String encoding;

    @Override
    public void init() throws ServletException {
        // 读取web.xml中配置的初始化参数
        encoding = getInitParameter("encoding");
    }

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        req.setCharacterEncoding(encoding);
        resp.setContentType("text/html;charset=" + encoding);
        resp.getWriter().write("用户模块GET请求处理");
    }

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        doGet(req, resp);
    }
}

2. 配置过滤器Filter

过滤器可以拦截指定的请求，在请求到达Servlet之前或响应返回客户端之前执行额外逻辑，比如编码处理、登录校验等。配置示例如下：

<web-app>
    <!-- 配置编码过滤器 -->
    <filter>
        <filter-name>encodingFilter</filter-name>
        <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
        <init-param>
            <param-name>encoding</param-name>
            <param-value>UTF-8</param-value>
        </init-param>
        <init-param>
            <param-name>forceEncoding</param-name>
            <param-value>true</param-value>
        </init-param>
    </filter>
    <!-- 过滤器映射，拦截所有请求 -->
    <filter-mapping>
        <filter-name>encodingFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

3. 配置监听器Listener

监听器用于监听ServletContext、HttpSession、ServletRequest等域对象的创建、销毁或属性变化事件。常用的比如监听应用启动的ServletContextListener，示例如下：

<web-app>
    <!-- 配置应用上下文监听器 -->
    <listener>
        <listener-class>com.example.listener.AppContextListener</listener-class>
    </listener>
</web-app>

对应的监听器实现类示例：

package com.example.listener;

import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class AppContextListener implements ServletContextListener {
    @Override
    public void contextInitialized(ServletContextEvent sce) {
        // 应用启动时执行的逻辑，比如加载全局配置
        System.out.println("Web应用启动完成");
    }

    @Override
    public void contextDestroyed(ServletContextEvent sce) {
        // 应用销毁时执行的逻辑，比如释放资源
        System.out.println("Web应用销毁");
    }
}

4. 配置上下文参数

全局上下文参数可以被整个Web应用的组件读取，配置方式如下：

<web-app>
    <!-- 全局上下文参数 -->
    <context-param>
        <param-name>appName</param-name>
        <param-value>用户管理系统</param-value>
    </context-param>
</web-app>

在Servlet中读取该参数的代码：

String appName = getServletContext().getInitParameter("appName");

5. 配置错误页面

可以指定不同的HTTP错误码或异常类型对应的跳转页面，提升用户体验：

<web-app>
    <!-- 配置404错误页面 -->
    <error-page>
        <error-code>404</error-code>
        <location>/error/404.jsp</location>
    </error-page>
    <!-- 配置空指针异常对应的错误页面 -->
    <error-page>
        <exception-type>java.lang.NullPointerException</exception-type>
        <location>/error/500.jsp</location>
    </error-page>
</web-app>

6. 配置欢迎页面

当用户访问应用根路径时，会按照配置的顺序查找对应的页面展示：

<web-app>
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
        <welcome-file>index.html</welcome-file>
        <welcome-file>default.jsp</welcome-file>
    </welcome-file-list>
</web-app>

web.xml的版本兼容说明

Servlet 3.0及之后的版本支持注解配置，开发者可以通过@WebServlet、@WebFilter、@WebListener等注解替代web.xml中的部分配置，提升开发效率。但web.xml仍然可以保留，用于配置注解无法覆盖的场景，或者需要集中管理配置的场景。如果web.xml和注解同时配置了同一个组件，web.xml中的配置优先级更高。

需要注意的是，如果使用Servlet 3.0以上的规范，web.xml的<web-app>标签需要对应正确的版本号，否则容器可能无法识别新的配置特性。如果不需要web.xml，也可以在项目中不创建该文件，完全使用注解完成配置。

web.xmlJava_WebServletFilterListener修改时间：2026-06-21 14:36:22