Spring MVC + Hibernate + Jetty 啟動失敗：NoClassDefFoundError javax.servlet.Servlet 根因與修復

錯誤堆疊核心信息

java.lang.NoClassDefFoundError: javax/servlet/Servlet
at org.eclipse.jetty.webapp.WebDescriptor.newParser(WebDescriptor.java:91)
at org.eclipse.jetty.webapp.WebAppContext.preConfigure(WebAppContext.java:457)
at org.eclipse.jetty.webapp.WebAppContext.doStart(WebAppContext.java:493)
...

根因分析

直接原因：運行時類路徑缺少 javax.servlet.Servlet 接口類。

深層原因：

• Jetty 9+ 將 Servlet API 從內核分離，需顯式依賴
• Maven 依賴範圍配置錯誤（如 provided 導致打包不包含）
• 嵌入式 Jetty 啟動方式與 WAR 部署不同，類加載機制差異

解決方案

方案一：添加 Servlet API 依賴（Maven）⭐ 標準修復

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>  <!-- Jetty 9 对应 Servlet 3.1 -->
    <scope>compile</scope>  <!-- 關鍵：compile 確保打包包含，provided 僅編譯時 -->
</dependency>

方案二：使用 Jetty 提供的 Servlet API 包

<dependency>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-servlet</artifactId>
    <version>9.4.48.v20220622</version>  <!-- 與 Jetty 版本一致 -->
</dependency>

方案三：Spring Boot 內嵌 Jetty 自動配置（推薦）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <!-- 自動包含 spring-boot-starter-jetty，內含 Servlet API -->
</dependency>

<!-- 若需排除 Tomcat -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

依賴範圍陷阱詳解

關鍵點：嵌入式 Jetty 屬於「運行期容器」，必須使用 compile 範圍，否則打包後無 Servlet API 類。

驗證步驟

1. 修改 pom.xml 添加依賴
2. mvn clean compile dependency:tree 確認 javax.servlet-api 存在於 compile 範圍
3. mvn package 打包
4. 檢查生成 JAR/WAR 內 BOOT-INF/lib/ 或 WEB-INF/lib/ 包含 javax.servlet-api-3.1.0.jar
5. 啟動應用驗證無 NoClassDefFoundError

版本兼容性矩陣

避坑指南

• ❌ 不要同時引入 javax.servlet-api 和 jakarta.servlet-api（除非遷移 Jakarta EE）
• ❌ 不要手動複製 JAR 到 lib 目錄，破壞依賴管理
• ✅ 使用 mvn dependency:analyze 檢測未聲明/未使用依賴
• ✅ 多模塊項目在父 POM dependencyManagement 統一版本