Tomcat 錯誤「Servlet xxx is not available」與 StandardWrapperValve 解析

Tomcat 錯誤「Servlet xxx is not available」與 StandardWrapperValve 解析

瀏覽器訪問 Servlet 返回 HTTP 404，控制台輸出：

HTTP Status 404 - Servlet xxx is not available
...
org.apache.catalina.core.StandardWrapperValve invoke
INFO: Servlet xxx is currently unavailable

原因分析

StandardWrapperValve 是 Tomcat 內部負責調用 Servlet service() 的閥門。Servlet xxx is currently unavailable 表明：

1. Servlet 類加載失敗（ClassNotFoundException、NoClassDefFoundError、靜態初始化拋異常）。
2. Servlet init() 方法拋出異常，導致初始化失敗，標記為不可用。
3. web.xml 中 <load-on-startup> 為正數但初始化失敗。

排查步驟

1. 查看完整堆疊跡：控制台向上翻滾，找到根因異常（Caused by 鏈）。
2. 檢查 Servlet init() 代碼：數據庫連接、配置文件讀取、第三方客戶端初始化等是否拋出未捕獲異常。
3. 確認類依賴：WEB-INF/lib 是否缺少 Servlet 依賴的 JAR 包。
4. 清理工作目錄：刪除 work/Catalina/localhost/專案名，重新部署。

常見具體案例

• JDBC 驅動類未找到：Class.forName("com.mysql.jdbc.Driver") 拋 CNFE。
• 配置文件路徑錯誤：getResourceAsStream("/config.properties") 返回 null 導致 NPE。
• 端口衝突：ServerSocket 初始化失敗。

解決模板

@Override
public void init() throws ServletException {
    try {
        // 1. 載入配置
        // 2. 初始化連接池/客戶端
    } catch (Exception e) {
        log.error("Servlet 初始化失敗", e);
        throw new ServletException("初始化失敗", e); // 拋出 ServletException 讓容器標記 unavailable
    }
}

核心原則：Servlet init() 絕不允許吞噬異常，必須拋出 ServletException 讓容器正確標記狀態，否則後續請求只會看到模糊的 404。