JDBC 連線 MySQL 常見錯誤排查：驅動版本不匹配導致 Communication Failure

錯誤現象

Communication failure during handshake. Is there a server running on localhost:3306?

MySQL 服務正常運行、埠 3306 監聽中，但連線失敗。

根本原因：驅動版本與 MySQL 伺服器版本不相容

mm.mysql 是早期第三方驅動，不支援 MySQL 4.1+ 引入的新認證協定 (SHA-1 密碼雜湊)、字元集協商、SSL 等特性，導致握手階段失敗。

解決方案：升級官方驅動

1. 下載 mysql-connector-java-5.x.x-bin.jar (對應 MySQL 5.x) 或 8.x (對應 MySQL 8.0+)
2. 替換 Classpath 中舊 jar
3. 更新驅動類別名稱：com.mysql.jdbc.Driver (5.x) / com.mysql.cj.jdbc.Driver (8.x)
4. 連線字串加入編碼參數：?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Taipei

正確配置範例

# jdbc.properties
driver=com.mysql.jdbc.Driver
url=jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf8&useSSL=false
username=root
password=your_password

驅動演進時間軸

其他常見連線問題快速檢查

• Communications link failure：防火牆阻擋、bind-address 非 0.0.0.0、SSL 強制但客戶端未配置
• Public Key Retrieval is not allowed：MySQL 8 預設 caching_sha2_password，需加 allowPublicKeyRetrieval=true 或改用 mysql_native_password
• Server timezone value '...' is unrecognized：加 serverTimezone=Asia/Taipei 或 MySQL 設定 default_time_zone
• 中文亂碼：確認資料庫/表/欄位 CHARSET=utf8mb4、連線字串 characterEncoding=utf8

結語

JDBC 連線失敗 80% 是驅動版本與伺服器版本不匹配。牢記：MySQL 版本升級，驅動必須同步升級。使用 Maven/Gradle 管理依賴，鎖定穩定版本，避免手動複製 jar 導致版本漂移。