JSP 連接 MySQL 出現 UnknownHostException：主機名稱解析失敗排查

錯誤訊息

java.net.UnknownHostException: hostname

直接原因

JDBC 連線字串中的 hostname 無法被 DNS 解析為 IP 位址。常見情況：

• 拼寫錯誤：jdbc:mysql://localhst:3306/db（少 o）。
• 使用主機名稱但 /etc/hosts 或 DNS 未設定。
• Docker/容器環境下服務名稱未在同一網路。

解決步驟

1. 改用 IP 位址（最快驗證）：
   jdbc:mysql://127.0.0.1:3306/db 或實際伺服器 IP。
2. 檢查連線字串：確認 hostname 拼寫、埠號、資料庫名稱。
3. 測試網路連通：
   ping hostname
telnet hostname 3306
4. 容器環境：確保應用容器與 MySQL 容器在同一 docker network，並使用服務名稱作為 hostname。

正確連線字串範例

String url = "jdbc:mysql://127.0.0.1:3306/mydb?useSSL=false&serverTimezone=UTC&characterEncoding=utf8";
String user = "root";
String pass = "password";
Class.forName("com.mysql.cj.jdbc.Driver"); // MySQL 8.0+ 驅動類別
Connection conn = DriverManager.getConnection(url, user, pass);

總結

UnknownHostException 純粹是網路層主機名稱解析失敗。優先改用 IP 位址驗證連線，再逐步排查 DNS/hosts/容器網路設定。