您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Tomcat 無法啟動完整排查手冊：從 JAVA_HOME 陷阱到端口衝突全解析

編輯：Java 相關知識

現象分類與快速定位

現象	典型原因	核心檢查點
雙擊 startup.bat 視窗一閃而過	JAVA_HOME 錯誤、缺少 pause、啟動腳本錯誤	cmd 下執行、檢查錯誤輸出
命令行啟動仍閃退	腳本未加 pause、錯誤導致直接退出	在 startup.bat 末尾加 pause
The JAVA_HOME environment variable is not defined correctly	JAVA_HOME 結尾含分號、指向 JRE 非 JDK、路徑有空格未加引號	echo %JAVA_HOME%、檢查 bin/java.exe 存在性
端口被佔用 (8080/8009/8005)	舊進程未死、其他程式佔用、IPv6/IPv4 綁定衝突	netstat -ano \\| findstr :8080、taskkill /PID
載入 Servlet 報 ClassNotFound/UnsupportedClassVersionError	編譯版本不匹配、類路徑缺失、Webapp 結構錯誤	檢查 WEB-INF/classes、lib、JDK 版本
啟動後自動關閉、無錯誤日誌	標準輸出被重導向、Logger 配置靜默、JVM Crash	檢查 catalina.out、hs_err_pid*.log

核心陷阱：JAVA_HOME 尾隨分號導致路徑拼接錯誤

錯誤設定： JAVA_HOME=C:\Program Files\Java\jdk1.8.0_202; (結尾有分號)

Tomcat 內部拼接邏輯： %JAVA_HOME%\bin\java.exe → C:\Program Files\Java\jdk1.8.0_202;\bin\java.exe → 路徑無效

正確設定： JAVA_HOME=C:\Program Files\Java\jdk1.8.0_202 (無分號、無尾斜線)

驗證指令：

echo %JAVA_HOME%
"%JAVA_HOME%\bin\java.exe" -version

startup.bat / catalina.bat 核心邏輯解析

@echo off
rem 1. 判斷 OS 類型，啟用 setlocal 延遲環境變數擴展
if "%OS%" == "Windows_NT" setlocal

rem 2. 推導 CATALINA_HOME
set CURRENT_DIR=%cd%
if not "%CATALINA_HOME%" == "" goto gotHome
set CATALINA_HOME=%CURRENT_DIR%
if exist "%CATALINA_HOME%\bin\catalina.bat" goto okHome
cd ..
set CATALINA_HOME=%cd%
cd %CURRENT_DIR%

:gotHome
if exist "%CATALINA_HOME%\bin\catalina.bat" goto okHome
echo The CATALINA_HOME environment variable is not defined correctly
goto end

:okHome
set EXECUTABLE=%CATALINA_HOME%\bin\catalina.bat
if not exist "%EXECUTABLE%" goto end

rem 3. 收集命令列參數
set CMD_LINE_ARGS=
:setArgs
if ""%1""=="" "" goto doneSetArgs
set CMD_LINE_ARGS=%CMD_LINE_ARGS% %1
shift
goto setArgs
:doneSetArgs

rem 4. 執行 catalina.bat start
call "%EXECUTABLE%" start %CMD_LINE_ARGS%
:end

關鍵點：

支援相對路徑啟動（從 bin 目錄或安裝根目錄均可）
參數透傳給 catalina.bat start
若需調試，將最後一行改為 echo "%EXECUTABLE%" start %CMD_LINE_ARGS% 觀察實際命令

常見問題解決方案速查

1. 「無法從『開始』選單啟動，但 cmd 可啟動」

開始選單捷徑屬性 → 目標："C:\Tomcat\bin\startup.bat" → 起始位置 設為 C:\Tomcat\bin
或修改捷徑目標為 cmd /k "C:\Tomcat\bin\startup.bat" 保留視窗

2. 「啟動介面停留幾秒消失，應用自動關閉」

server.xml 缺少 <Context> 配置或路徑錯誤
檢查 webapps/ROOT 是否存在、docBase 指向正確

3. 「端口被佔用」

# Windows 查詢佔用 8080 的 PID
netstat -ano | findstr :8080
# 輸出範例：TCP 0.0.0.0:8080 0.0.0.0:0 LISTENING 1234
taskkill /F /PID 1234

# 或修改 server.xml 變更端口
<Connector port="8088" protocol="HTTP/1.1" ... />
<Server port="8005" shutdown="SHUTDOWN">  <-- 關閉端口也可改 -->

4. 「Tomcat 能啟動、登入頁面正常，但登入失敗」

瀏覽器 Cookie/快取問題 → 清除、嘗試無痕模式
IE/Edge 信任站點設定、彈出視窗攔截器干擾
應用層面：Session 超時、CSRF Token 驗證失敗、資料庫連線池耗盡

5. 「JDK 版本過低導致啟動失敗」

Tomcat 9+ 需 JDK 8+；Tomcat 10.1+ (Jakarta EE 9) 需 JDK 11+
檢查 RUNNING.txt 確認版本需求

進階診斷技巧

啟用遠端除錯：set JPDA_ADDRESS=8000 + catalina.bat jpda start
輸出 JVM 參數驗證：catalina.bat run (前景模式) 觀察控制台完整輸出
檢查類載入衝突：-verbose:class 加入 JAVA_OPTS 追蹤類載入來源
分析 Thread Dump：jstack <pid> > threaddump.txt 排查啟動卡住執行緒
HSERR 崩潰日誌：hs_err_pid<pid>.log 由 JVM 生成，含致命錯誤堆疊

生產環境啟動腳本最佳實踐

# setenv.sh (Linux) / setenv.bat (Windows)
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
export CATALINA_PID=$CATALINA_HOME/tomcat.pid
export JAVA_OPTS="-server -Xms2g -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=$CATALINA_HOME/logs \
-Dfile.encoding=UTF-8 -Duser.timezone=Asia/Taipei \
-Djava.security.egd=file:/dev/./urandom"

# Windows 版
set JAVA_HOME=C:\Java\jdk-11
set CATALINA_PID=%CATALINA_HOME%\tomcat.pid
set JAVA_OPTS=-server -Xms2g -Xmx2g -XX:+UseG1GC ...