Maven SpringMVC ClassNotFoundException 完整排查指南

錯誤堆疊分析

SEVERE: Error configuring application listener of class org.springframework.web.context.ContextLoaderListener
java.lang.ClassNotFoundException: org.springframework.web.context.ContextLoaderListener
...
SEVERE: Error configuring application listener of class org.springframework.web.util.Log4jConfigListener
java.lang.ClassNotFoundException: org.springframework.web.util.Log4jConfigListener

核心原因

Spring 相關 JAR 包未正確打包進 WAR 檔案的 WEB-INF/lib 目錄。Tomcat 啟動時找不到 spring-web、spring-context 等核心類別。

排查步驟

1. 檢查 pom.xml 依賴範圍

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>5.3.21</version>
    <!-- 請勿設定 scope 為 provided 或 test -->
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>5.3.21</version>
</dependency>

確保無 <scope>provided</scope>，否則 Maven 不會打包進 WAR。

2. 驗證 Maven 打包結果

mvn clean package
# 檢查 target/your-war/WEB-INF/lib/ 是否包含 spring-web-*.jar
jar -tf target/your-war.war | grep spring-web

3. 檢查 Maven War Plugin 設定

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>3.3.2</version>
    <configuration>
        <failOnMissingWebXml>false</failOnMissingWebXml>
        <!-- 確保不排除任何依賴 -->
        <packagingExcludes>WEB-INF/lib/servlet-api*.jar</packagingExcludes>
    </configuration>
</plugin>

4. IDE 專案設定同步

• IntelliJ IDEA：Maven 面板 → Reload All Maven Projects → Build → Rebuild Project
• Eclipse：Maven → Update Project → Force Update of Snapshots/Releases

常見錯誤模式

進階診斷

# 查看完整依賴樹
mvn dependency:tree -Dverbose

# 檢查特定類別來自哪個 JAR
mvn dependency:build-classpath -DincludeScope=compile | tr ':' '\n' | xargs -I {} sh -c 'jar -tf {} | grep ContextLoaderListener && echo {}'

最佳實踐建議

1. 統一使用 Spring Boot 避免手動配置鬧劇
2. 鎖定 Spring 版本：<spring.version>5.3.21</spring.version>
3. CI/CD 流程加入 mvn dependency:analyze 檢查未使用/未宣告依賴
4. 使用 maven-enforcer-plugin 強制依賴收斂

ClassNotFoundException 本質是部署產物缺失，系統化檢查打包流程即可根治。