Java JDBC 連接 MySQL 失敗：Classpath 與 JAR 包配置錯誤

Java 專案無法連接 MySQL，報錯通常為 ClassNotFoundException: com.mysql.jdbc.Driver 或 No suitable driver found。本文釐清 classpath、JAR 包、模塊路徑的區別與正確配置。

常見錯誤原因

1. MySQL Connector/J JAR 包未放入項目構建路徑
2. 將 JAR 放在了項目目錄但未加入 Classpath（編譯/運行時類路徑）
3. Maven/Gradle 依賴聲明錯誤或未刷新
4. 模塊化項目 (Java 9+) 未在 module-info.java 中 requires

正確配置步驟

非構建工具項目

1. 下載 mysql-connector-java-x.x.x.jar
2. 放入項目 lib/ 目錄
3. IDE 中：右鍵 JAR → Add to Build Path / Classpath
4. 或命令行編譯/運行時：-cp ".;lib/mysql-connector-java-x.x.x.jar"

Maven 項目

<dependency>
  <groupId>com.mysql</groupId>
  <artifactId>mysql-connector-j</artifactId> <!-- 8.0+ 新坐標 -->
  <version>8.0.33</version>
</dependency>

刷新 Maven 專案（mvn dependency:resolve 或 IDE 刷新）。

Gradle 項目

implementation 'com.mysql:mysql-connector-j:8.0.33'

驅動類名變更注意 (8.0+)

• 舊版：com.mysql.jdbc.Driver
• 新版：com.mysql.cj.jdbc.Driver（自動註冊，通常無需手動 Class.forName）

驗證連接代碼

String url = "jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC";
String user = "root";
String pwd = "123456";
try (Connection conn = DriverManager.getConnection(url, user, pwd)) {
  System.out.println("連接成功：" + conn.getMetaData().getURL());
} catch (SQLException e) {
  e.printStackTrace();
}

關鍵點：JAR 必須在 Classpath 中，而非僅在硬盤某目錄。Maven/Gradle 管理依賴最省心。