Tomcat 7 啟動報錯 NoSuchMethodError: ServletContext.getSessionCookieConfig 解決方案：Servlet API 版本衝突排查

Tomcat 7 啟動報錯 NoSuchMethodError: ServletContext.getSessionCookieConfig 解決方案：Servlet API 版本衝突排查

經典的 **Jar 包地獄** 案例：Tomcat 7 啟動拋出 `java.lang.NoSuchMethodError: javax.servlet.ServletContext.getSessionCookieConfig()Ljavax/servlet/SessionCookieConfig`。本文從**異常本質、版本對應關係、三種解決方案、避坑原則**四個維度徹底解決此類版本衝突問題。

一、異常本質剖析

java.lang.NoSuchMethodError: javax.servlet.ServletContext.getSessionCookieConfig()Ljavax/servlet/SessionCookieConfig

• NoSuchMethodError：**運行時**鏈接失敗，編譯通過但運行找不到方法 — **經典版本不匹配信號**。
• ServletContext.getSessionCookieConfig()： **Servlet 3.0 (Java EE 6)** 新增方法，用於程序化配置 Session Cookie (HttpOnly、Secure、Domain、Path、MaxAge)。
• Tomcat 7：實現 **Servlet 3.0** 規範，**內置** `servlet-api.jar` (3.0 版) 於 `$CATALINA_HOME/lib`。

衝突根因： 應用 `WEB-INF/lib` 下攜帶了**低版本 Servlet API Jar (如 2.5 版)**，類加載器**優先加載 WebApp 類加載器**中的類 (雙親委派模型被打破)，導致運行時看到的是舊版 `ServletContext` 接口，**缺少 3.0 新增方法**。

二、Servlet API 版本與容器對應表

三、三種解決方案 (按推薦度排序)

方案一：Maven 依賴範圍設為 provided (標準解法) ⭐⭐⭐⭐⭐

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.0.1</version>  <!-- 與 Tomcat 7 匹配 -->
    <scope>provided</scope>  <!-- 關鍵：編譯用，打包不進 WEB-INF/lib -->
</dependency>

原理： `provided` 範圍表示**「由容器運行時提供」**，Maven 打包 WAR 時**不會將該 Jar 放入 `WEB-INF/lib`**，運行時直接使用 Tomcat `lib` 目錄下的版本，**徹底消除衝突**。

方案二：排除傳遞依賴中的舊版 Servlet API

<dependency>
    <groupId>some.third.party</groupId>
    <artifactId>some-lib</artifactId>
    <version>x.y.z</version>
    <exclusions>
        <exclusion>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

適用於**無法控制第三方庫傳遞依賴**的情況，配合方案一使用。

方案三：手動複製容器 Jar 到 JRE 擴展目錄 (臨時應急，不推薦生產) ⭐

原文方案： 把 tomcat 目錄下的 lib/servlet-api.jar 文件拷貝到 $JAVA_HOME/jre/lib/ext 目錄下，再啟動 tomcat 問題解決

缺陷：

• 污染 JRE 全局環境，影響同機器其他應用。
• JDK 9+ 移除了 `jre/lib/ext` 機制 (模塊系統)，**方案失效**。
• 版本鎖定死，升級 Tomcat 需手動同步。

四、排查工具與最佳實踐

1. mvn dependency:tree：查看完整依賴樹，搜索 `servlet-api` 發現衝突版本。
2. mvn dependency:analyze：檢測未聲明依賴與無用依賴。
3. IDE 依賴圖：IDEA `Maven → Dependencies → Show Dependencies` 可視化衝突路徑。
4. 統一版本管理 (BOM)：

   <dependencyManagement>
               <dependencies>
                   <dependency>
                       <groupId>javax.servlet</groupId>
                       <artifactId>javax.servlet-api</artifactId>
                       <version>3.0.1</version>
                       <scope>provided</scope>
                   </dependency>
               </dependencies>
           </dependencyManagement>

5. 嚴禁手動放 Jar 到 WEB-INF/lib：所有依賴**必須通過 Maven/Gradle 管理**。

五、總結

NoSuchMethodError = 編譯版本 ≠ 運行版本。
Servlet API **必須設為 provided 範圍**，讓容器統一提供運行時實現。
Tomcat 7 對應 Servlet 3.0，Maven 坐標 `javax.servlet:javax.servlet-api:3.0.1`。
**拒絕手動複製 Jar 到 JRE ext 目錄**，擁抱依賴管理工具，才是專業態度。