IntelliJ中Gradle项目报java.sql.SQLException：找不到jdbc:mariadb合适驱动求助

作为Gradle新手遇到这个问题太正常了，本质就是JVM找不到MariaDB的JDBC驱动类，咱们从依赖配置和代码/配置文件两个核心方向排查：

1. 先检查build.gradle的依赖配置是否正确 #

这是新手最容易踩坑的地方，核心要确保驱动依赖加对、作用域没错：

正确的Groovy DSL配置 #

如果你的build.gradle是Groovy格式，添加驱动依赖时注意作用域：

dependencies {
    // 推荐用runtimeOnly，因为驱动只在运行时需要
    runtimeOnly 'org.mariadb.jdbc:mariadb-java-client:3.3.3'
    // 如果你需要在编译时直接引用驱动类，就换成implementation
    // implementation 'org.mariadb.jdbc:mariadb-java-client:3.3.3'
}

正确的Kotlin DSL配置 #

如果是Kotlin格式的build.gradle.kts：

dependencies {
    runtimeOnly("org.mariadb.jdbc:mariadb-java-client:3.3.3")
    // 或者 implementation("org.mariadb.jdbc:mariadb-java-client:3.3.3")
}

常见错误点：

• 依赖坐标写错：比如把org.mariadb.jdbc写成mysql（虽然兼容，但官方推荐用MariaDB自己的驱动）
• 作用域用错：比如用了compileOnly，这会导致编译时能找到驱动，但运行时驱动包不在classpath里，必然报错
• 没同步Gradle：添加依赖后一定要点击IntelliJ右上角的「Sync Project with Gradle Files」按钮，确保驱动包下载到本地

2. 检查jdbc.properties的URL格式是否正确 #

MariaDB的JDBC URL有严格的格式要求，别在细节上出错：

# 基础格式（替换成你的数据库名）
jdbc.url=jdbc:mariadb://localhost:3306/your_database_name
# 带参数的格式（比如指定字符集）
jdbc.url=jdbc:mariadb://localhost:3306/your_database_name?useUnicode=true&characterEncoding=utf8

常见错误点：

• 拼写错误：比如把mariadb写成mysql或者漏写字母
• 端口号错误：默认是3306，如果你的MariaDB改了端口要对应修改
• 数据库名称写错：确保URL里的库名是你已经在MariaDB中创建好的

3. 代码中驱动加载是否到位 #

虽然JDBC 4.0之后驱动会自动通过SPI加载，但偶尔还是需要手动触发（尤其是老版本驱动），可以在获取数据库连接前加一行：

Class.forName("org.mariadb.jdbc.Driver");

⚠️ 注意：别把驱动类名写错！MariaDB的驱动类是org.mariadb.jdbc.Driver，不是MySQL的com.mysql.cj.jdbc.Driver。

4. 验证驱动是否真的在运行时classpath里 #

在IntelliJ里可以快速确认：

• 打开File -> Project Structure -> Modules，选中你的模块，切换到Dependencies标签，看看mariadb-java-client是否在列表里，且作用域是Runtime或Compile
• 或者运行时添加VM参数-verbose:class，控制台会打印所有加载的类，搜索org.mariadb.jdbc.Driver看看是否存在

最后一招：清理缓存重新构建 #

有时候Gradle缓存会搞事情，试试：

1. 点击Build -> Clean Project
2. 再点击Build -> Rebuild Project
3. 重新运行程序

内容的提问来源于stack exchange，提问作者Thomas Crowley