Eclipse Tomcat 啟動失敗「Server at localhost failed to start」根因與解決方案

Eclipse Tomcat 啟動失敗「Server at localhost failed to start」根因與解決方案

在 Eclipse 開發 Servlet 時，常遇到 Tomcat 無法啟動的錯誤：Server Tomcat v7.0 Server at localhost failed to start。網路上流傳許多方案（刪除 .snap 檔、增加啟動逾時、重開機），但實際專案中最常見的真兇是：**web.xml 配置與 @WebServlet 註解衝突**。

問題重現場景

1. 在 Eclipse 建立新 Servlet，自動產生註解：@WebServlet("/ServletDemo")
2. 同時在 web.xml 手動配置相同的 Servlet 映射
3. 啟動 Tomcat 即報錯

錯誤堆疊關鍵資訊

Caused by: java.lang.IllegalArgumentException: 
The servlets named [ServletDemo] and [com.vivizhang.servlet.ServletDemo] 
are both mapped to the url-pattern [/ServletDemo] which is not permitted

明確指出：兩個 Servlet 名稱映射到相同的 URL 模式，違反 Servlet 規範。

根本原因分析

Servlet 3.0+ 支援兩種映射方式：

當兩者同時存在且映射衝突時，容器啟動失敗。

解決方案（二選一）

方案一：移除 web.xml 映射（推薦現代專案）

保留 @WebServlet 註解，刪除 web.xml 中對應的 <servlet> 與 <servlet-mapping> 區塊。優點：程式碼與配置合一、維護性佳。

方案二：註解掉 @WebServlet（傳統專案相容）

// @WebServlet("/ServletDemo")
public class ServletDemo extends HttpServlet { ... }

保留 web.xml 配置。適用於舊專案遷移或需集中管理映射的場景。

其他可能原因排查清單

• 埠號佔用：netstat -ano | findstr 8080 檢查並終止佔用進程
• 啟動逾時過短：Server 編輯器將「Start timeout」調大（如 120 秒）
• 工作空間鎖定：刪除 .metadata/.plugins/org.eclipse.core.resources/.snap
• 專案建置錯誤：Clean 專案、確認無編譯錯誤
• JRE/JDK 不匹配：確認 Tomcat 使用 JDK 而非 JRE

最佳實踐建議

1. 專案統一採用單一映射方式（推薦純註解）
2. 使用 Servlet 3.0+ 專案結構，移除 web.xml 或設定 metadata-complete="true" 停用註解掃描
3. 遇到啟動失敗優先查看 Console 完整堆疊，而非盲目嘗試網路方案

總結

Tomcat 啟動失敗 90% 為配置衝突。註解與 web.xml 雙重映射衝突是 Servlet 入門最常見坑。理解 Servlet 3.0 註解掃描機制，堅持單一配置來源，即可徹底避免此類問題。