您现在的位置：程式碼之家 >> 編程語言 > >> 更多程式語言 >> 程式設計疑難解答

Tomcat 啟動 Web 專案報 ClassNotFoundException: com.zlh.common.api.RedirectApi 解決方案

編輯：程式設計疑難解答

Tomcat 啟動報 `java.lang.ClassNotFoundException: com.zlh.common.api.RedirectApi`，進一步引發 `NoClassDefFoundError` 導致 Spring `ContextLoaderListener` 初始化失敗。根本原因是 **WAR 包 / 專案建構輸出缺少該類別的 `.class` 檔案**，常見於 Maven 依賴範圍錯誤、Eclipse 部署組件未勾選、或 `target/classes` 未編譯。

錯誤堆疊關鍵點

Caused by: java.lang.ClassNotFoundException: com.zlh.common.api.RedirectApi
    at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1858)
    ... 39 more

排查清單（按可能性排序）

#	檢查項目	操作步驟	預期結果
1	Maven 依賴範圍	`pom.xml` 找到 `com.zlh.common` 依賴，確認 `compile`（預設），非 `provided`/`test`	依賴會打包進 `WEB-INF/lib`
2	Eclipse Deployment Assembly	專案右鍵 → `Properties` → `Deployment Assembly` → `Add` → `Java Build Path Entries` → 選 `Maven Dependencies`	發布到伺服器時自動複製 JAR
3	專案建構輸出	專案右鍵 → `Build Project` → 檢查 `target/classes/com/zlh/common/api/RedirectApi.class` 存在	自有程式碼編譯產出 class
4	伺服器發布目錄	伺服器視圖 → 右鍵 Tomcat → `Open` → `Modules` → `Path` 指向專案 `WebContent`/`webapp`，`Deploy Path` 正確	發布路徑包含 `WEB-INF/classes` 與 `WEB-INF/lib`
5	Maven 重新導入	`Maven` → `Update Project` → 勾選 `Force Update of Snapshots/Releases`	依賴樹修正、JAR 下載完成
6	清理重建	`Project` → `Clean` → `Maven` → `Update Project` → `Server` → `Clean Tomcat Work Directory` → 重新啟動	消除舊快取/殘留檔案

快速驗證指令

# 1. 檢查 WAR 內容
jar tf yourproject.war | grep RedirectApi
# 應輸出：WEB-INF/classes/com/zlh/common/api/RedirectApi.class
# 或：WEB-INF/lib/common-api-x.x.jar (若為獨立模組)

# 2. 檢查 Tomcat 發布目錄
ls -la $CATALINA_BASE/wtpwebapps/yourproject/WEB-INF/classes/com/zlh/common/api/
# 應看到 RedirectApi.class

常見場景對應解法

**多模組專案**：`common-api` 模組 `install` 到本地倉庫後，主模組 `dependency` 範圍為 `compile`，但 Eclipse 未同步 → 執行 `Maven → Update Project` 並勾選 `Deployment Assembly` 包含 `Maven Dependencies`
**手動加入 JAR**：將 JAR 放入 `WebContent/WEB-INF/lib` 並加入 Build Path，**不推薦**，易遺漏升級
**Spring Boot 打包**：`spring-boot-maven-plugin` 會自動解壓依賴 JAR 到 `BOOT-INF/classes`，若用傳統 WAR 部署需改用 `war` 打包並配置 `providedRuntime`

一鍵修復腳本（Eclipse + Maven 專案）

# 在專案根目錄執行
mvn clean install -DskipTests
# Eclipse 中：
# 1. 專案右鍵 → Maven → Update Project → Force Update
# 2. 專案右鍵 → Properties → Deployment Assembly → 確認 Maven Dependencies 在列表中
# 3. Server 視圖 → Tomcat → Clean → Clean Work Directory
# 4. 重新啟動 Tomcat

核心原則：**`ClassNotFoundException` = 運行時類別路徑缺少 `.class`/`.jar`**。依序驗證「編譯產出 → 打包輸出 → 發布路徑 → 類別載入器」，即可精準定位並解決。