JSF 在 web.xml 中啟動異常排查與解決方案

問題現象

JSF 專案部署啟動時拋出 NullPointerException at javax.faces.webapp.FacesServlet 或 Cannot find FacesContext，首頁為 index.jsp 且包含 JSF 元件時常見。

根本原因

1. 缺少 ConfigureListener：JSF 需 com.sun.faces.config.ConfigureListener 初始化設定，否則 FacesServlet 無法正確建構。
2. 歡迎檔案衝突：容器預設歡迎檔 index.jsp 直接由 JSP 引擎處理，繞過 FacesServlet，導致 FacesContext 未建立。

解決方案

1. 必須在 web.xml 註冊 ConfigureListener

<listener>
    <listener-class>com.sun.faces.config.ConfigureListener</listener-class>
</listener>

2. 三種修正歡迎檔案衝突的方法

方法 A：修改 welcome-file 為 FacesServlet 對應路徑

<welcome-file-list>
    <welcome-file>index.faces</welcome-file> <!-- 對應 *.faces mapping -->
</welcome-file-list>

方法 B：將首頁改名並用轉發

1. 將原 index.jsp 改為 home.jsp。
2. 新建 index.jsp 僅含轉發：<jsp:forward page="home.faces"/>。

方法 C：首頁不使用 JSF 元件

保留 index.jsp 為純靜態/非 JSF 頁面，JSF 頁面另行命名 (如 home.jsp) 並透過 *.faces 存取。

完整 web.xml 範例

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         version="2.4"
         xsi:schemaLocation="https://java.sun.com/xml/ns/j2ee
         https://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <display-name>JSF Demo</display-name>

    <context-param>
        <param-name>javax.faces.CONFIG_FILES</param-name>
        <param-value>/WEB-INF/faces-config.xml</param-value>
    </context-param>

    <servlet>
        <servlet-name>FacesServlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>FacesServlet</servlet-name>
        <url-pattern>*.faces</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>com.sun.faces.config.ConfigureListener</listener-class>
    </listener>

    <welcome-file-list>
        <welcome-file>index.faces</welcome-file>
    </welcome-file-list>
</web-app>

faces-config.xml 關鍵片段

<navigation-rule>
    <from-view-id>/home.jsp</from-view-id>
    <navigation-case>
        <from-outcome>login</from-outcome>
        <to-view-id>/welcome.jsp</to-view-id>
    </navigation-case>
</navigation-rule>

<managed-bean>
    <managed-bean-name>user</managed-bean-name>
    <managed-bean-class>com.UserBean</managed-bean-class>
    <managed-bean-scope>session</managed-bean-scope>
</managed-bean>

總結

加上 ConfigureListener 並調整歡迎檔案策略，即可消除啟動異常，確保 JSF 生命週期正確啟動。