JDBC 連接 SQL Server 報「No suitable driver」：六大常見原因與排查清單

錯誤現場

java.sql.SQLException: No suitable driver found for jdbc:microsoft://127.0.0.1433;databaseName=spdb1

代碼已加載 com.microsoft.jdbc.sqlserver.SQLServerDriver，JAR 亦已導入。

六大常見原因

1. JAR 包損壞/不完整：重新下載官方 sqljdbc4.jar（或 mssql-jdbc 新版）。
2. 驅動版本與數據庫不匹配：SQL Server 2005/2008/2012/2016+ 需對應驅動主版本。
3. 類路徑未生效：IDE 中加入 Library ≠ 運行時 Classpath。檢查 java -cp .;sqljdbc4.jar MyClass 或 Manifest Class-Path。
4. 路徑包含中文/空格：JAR 放在 D:\我的項目\lib\ 導致 ClassLoader 解析失敗。移至純 ASCII 路徑。
5. 多版本 JAR 衝突：項目依賴傳遞引入舊版 sqljdbc.jar，導致 DriverManager 註冊錯誤驅動。用 mvn dependency:tree 或 IDE 依賴分析排查。
6. JDBC URL 格式錯誤：示例中 127.0.0.1433 缺少冒號，正確為 jdbc:sqlserver://127.0.0.1:1433;databaseName=spdb1（新驅動）或 jdbc:microsoft:sqlserver://127.0.0.1:1433;DatabaseName=spdb1（舊驅動）。

排查步驟

// 1. 驗證驅動類可被加載
Class.forName("com.microsoft.sqlserver.jdbc.SQLServerDriver"); // 新驅動類名
System.out.println("Driver loaded");

// 2. 打印已註冊驅動
Enumeration<Driver> drivers = DriverManager.getDrivers();
while (drivers.hasMoreElements()) {
    System.out.println(drivers.nextElement().getClass().getName());
}

// 3. 測試連接
try (Connection c = DriverManager.getConnection(url, user, pwd)) {
    System.out.println("Connected: " + c.getMetaData().getURL());
}

最佳實踐

• 使用 Maven/Gradle 管理依賴：com.microsoft.sqlserver:mssql-jdbc:12.2.0.jre11。
• 採用 HikariCP 連接池，配置 driverClassName 顯式指定驅動。
• 生產環境啟用 SSL 加密連接：encrypt=true;trustServerCertificate=false。