解决 Spring Boot 异常：“Cannot Load Driver Class: com.mysql.jdbc.driver”

2025-05-07

1、简介

在 Spring Boot 中整合 MySQL 时，我们通常依赖 Spring Boot 的自动配置和 JDBC 支持来连接数据库。不过，遇到配置问题的情况并不少见，尤其是在使用 过时的依赖 时。其中一个异常就是：

Cannot load driver class: com.mysql.jdbc.Driver

本文将带你了解出现 “Cannot load driver class: com.mysql.jdbc.Driver” 异常的原因以及解决办法。

2、理解原因

这个问题的根源在于使用了过时的 MySQL 驱动程序类。在早期版本的 MySQL JDBC 驱动程序（Connector/J）中，通常使用以下驱动程序类：

spring.datasource.driver-class-name=com.mysql.jdbc.Driver

不过，从 MySQL Connector/J 8.0 开始，该类已被弃用并删除。更新后的驱动程序类是

com.mysql.cj.jdbc.Driver

如果在新版本的 MySQL 驱动程序中继续使用旧的类名，应用将无法启动，并出现 ClassNotFoundException 异常。

3、处理问题

要解决这个问题，需要更新 Spring Boot 配置和项目中使用的依赖。

3.1、使用正确的依赖

第一步是在 application.properties 或 application.yml 文件中新的驱动程序类替换旧的驱动程序类。

spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=secret
# 新的驱动类
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

或者 application.yml 文件：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: secret
    driver-class-name: com.mysql.cj.jdbc.Driver

另外，Spring Boot 还能从 classpath 自动检测驱动程类。如果存在正确版本的 MySQL 驱动程序，我们就可以完全省略 driver-class-name 属性。

3.2、更新依赖

然后，确保项目使用最新稳定版本的 MySQL JDBC 驱动程序。

Maven：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>9.2.0</version>
</dependency>

Gradle：

implementation("com.mysql:mysql-connector-j:9.2.0")

使用过时的驱动程序可能会导致不兼容，尤其是在使用最新版本的 Spring Boot 或 Java 时。

4、测试

更新配置和依赖后，来测试应用程序是否能连接到数据库，以检验修复的效果。

以编写一个简单的集成测试，以确保数据源按预期运行：

@SpringBootTest
class LoadDriverLiveTest {
    @Autowired
    private DataSource dataSource;

    @Test
    void whenConnectingToDatabase_thenConnectionShouldBeValid() throws Exception {
        try (Connection connection = dataSource.getConnection()) {
            assertNotNull(connection);
        }
    }
}

如果测试通过，则确认 Spring Boot 已成功加载驱动程序类并建立了与 MySQL 数据库的连接。

5、总结

本文介绍了 Spring Boot 中出现 “Cannot load driver class: com.mysql.jdbc.Driver” 异常的原因以及解决办法。

在 Spring Boot 中使用 JDBC 时，确保依赖和配置之间的兼容性是关键。要了解这方面的详细信息，可以参考 Spring Boot 官方文档和 MySQL Connector/J 发布说明。

Ref：https://www.baeldung.com/fix-mysql-can-not-find-driver-exception