Maven管理下无Servlet的JSF项目：如何配置web.xml与glassfish-web.xml？

阿华AIGC实验室

2026-5-22

配置无自定义Servlet的JSF项目：web.xml与glassfish-web.xml指南

你说的这种场景太常见了——用Maven管理、没有自己写Servlet，但有JSF的JavaBean和xhtml页面，核心就是把JSF的核心组件配置到位，让GlassFish能正确识别并处理JSF请求。下面我给你详细梳理配置细节：

一、web.xml 完整配置

你当前的web.xml基于Java EE 4.0，咱们需要补充JSF必需的配置项，因为JSF依赖自带的FacesServlet来处理所有JSF页面请求。完整的配置示例如下：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">

    <!-- JSF核心Servlet：处理所有JSF请求 -->
    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup> <!-- 启动时加载，提升首次访问速度 -->
    </servlet>
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.xhtml</url-pattern> <!-- 只处理xhtml页面请求，更精准 -->
        <!-- 也可以用/*，但会拦截所有请求，包括静态资源，按需选择 -->
    </servlet-mapping>

    <!-- JSF上下文参数 -->
    <context-param>
        <param-name>javax.faces.PROJECT_STAGE</param-name>
        <param-value>Development</param-value> <!-- 开发阶段，开启调试功能 -->
    </context-param>
    <context-param>
        <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
        <param-value>.xhtml</param-value> <!-- 指定默认视图后缀 -->
    </context-param>
    <context-param>
        <param-name>javax.faces.VIEW_STATE_ENCRYPTION</param-name>
        <param-value>false</param-value> <!-- 开发阶段关闭视图状态加密，方便调试 -->
    </context-param>

    <!-- 欢迎页面配置 -->
    <welcome-file-list>
        <welcome-file>index.xhtml</welcome-file>
    </welcome-file-list>

</web-app>

关键配置说明：

FacesServlet是JSF的核心控制器，必须配置，没有它GlassFish不知道怎么处理JSF请求
<load-on-startup>1</load-on-startup>让服务器启动时就加载这个Servlet，避免首次访问的延迟
映射路径选*.xhtml比/*更合理，不会拦截CSS、JS这类静态资源的请求
PROJECT_STAGE设为Development会开启JSF的调试模式，比如详细的错误提示，上线时改成Production就行

二、glassfish-web.xml 配置

这个是GlassFish服务器专属的部署描述符，用来做容器级的自定义配置，你的简单项目只需要基础配置就够了：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN"
        "http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
<glassfish-web-app error-url="">

    <!-- 设置项目的上下文根：访问路径就是http://localhost:8080/my-jsf-app -->
    <context-root>/my-jsf-app</context-root>

    <!-- 可选：启用CDI支持（如果你的JavaBean用@Named注解的话，GlassFish默认已开启） -->
    <class-loader delegate="false"/>

    <!-- 可选：配置JSF的状态保存方式，默认是服务器端，开发时可以设为客户端方便调试 -->
    <property name="com.sun.faces.enableClientStateSaving" value="false"/>

</glassfish-web-app>

关键配置说明：

<context-root>：指定项目的访问路径，你可以改成自己想要的名称，比如/jsf-demo
class-loader delegate="false"：让项目优先加载自己的依赖，避免容器自带库和项目库冲突
如果你的JavaBean用的是JSF原生的@ManagedBean，不需要额外配置CDI；如果用CDI的@Named，GlassFish默认会自动启用CDI支持，不用额外配置