DolphinScheduler 报错 Cannot load driver class？MySQL 驱动路径完整指南

关注

原创 2026-09-05 21:52:29 399 阅读 AI 写同款· GEO 优化 ›

CentOS 7 使用 Docker 部署 DolphinScheduler 3.2.2 完整教程本文档详细记录了在 CentOS 7 虚拟机环境下使用 Docker Compose 部署 Apache DolphinScheduler 3.2.2 的完整流程。主要内容包括：虚拟机配置建议（推荐4核8GB）、VMware NAT网络配置与端口转发设置、CentOS 7系统初始化（替换阿里云yum源、安装基础工具、关闭防火墙/SELinux）、Docker及Docker Compose的安装配置、最终通过多容器部署包含MySQL 8.0、Zookeeper 3.8和DolphinScheduler全组件阅读详情

【导航台账】制造业数据与AI践行者老蒋的技术博客全系列文章汇总（持续更新）

📌 文章摘要

DolphinScheduler 创建 MySQL 数据源时报错 Cannot load driver class: com.mysql.cj.jdbc.Driver？根本原因是官方因协议兼容问题未内置 MySQL 驱动，且需同时放置到所有模块的 libs 目录才能生效。本文拆解驱动加载的底层逻辑，覆盖版本选择、多目录部署、配置校验全流程，解决类名不匹配、目录遗漏两大高频坑，照着操作即可成功连接。

问题现象

根因分析

第一层：DolphinScheduler默认不带MySQL驱动

第二层：Standalone模式下的目录迷宫

第三层：版本陷阱——驱动类名的“新旧之争”

问题现象

兄弟们，上一篇我们成功把DolphinScheduler的元数据库从H2切换到了MySQL，重启不丢数据了，心里踏实多了。

然后我开始在Web UI里配置数据源，准备连接Doris。

填好IP、端口、用户名、数据库名，信心满满地点击“测试连接”——

结果弹了个大红叉：

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

我当时的第一反应是：这不科学啊……

我明明记得已经把MySQL驱动放到standalone-server/libs目录下了啊。怎么还是找不到驱动？

后来我才发现，DolphinScheduler的驱动加载机制，不是“放一个地方就行”，而是“每个模块都要放”。

📋 快速自检：你是不是也遇到了这些问题？ ▢ 测试连接报错：Cannot load driver class: com.mysql.cj.jdbc.Driver ▢ 明明放了驱动还是报错，找不到原因 ▢ 元数据库切换成功，新建数据源却连不上本文一次性解决以上所有问题。

根因分析

第一层：DolphinScheduler默认不带MySQL驱动

DolphinScheduler的官方发行包中，默认不包含MySQL的JDBC驱动-。

为什么？因为MySQL的JDBC驱动使用的是GPL协议，和DolphinScheduler的Apache License 2.0存在协议兼容性问题。所以官方选择不打包进去，让用户自己下载添加-。

官方的安装文档明确写着：

如果使用MySQL需要手动下载mysql-connector-java驱动并移动到DolphinScheduler的每个模块的libs目录下，其中包括api-server/libs和alert-server/libs和master-server/libs和worker-server/libs-。

“每个模块” 这四个字是关键。

第二层：Standalone模式下的目录迷宫

很多人（包括我）想当然地以为：Standalone模式只有一个进程，驱动放到standalone-server/libs目录就够了。

但这个理解是错的。

即使在Standalone模式下，DolphinScheduler内部仍然会启动多个子服务（API、Master、Worker、Alert等），每个子服务都有自己独立的类加载器，各自加载各自libs目录下的JAR包。

当你通过Web UI创建数据源时，是API Server在加载驱动，而不是Standalone Server。

所以，驱动必须放到每个子模块的libs目录下，具体包括：

├── api-server/libs/
├── alert-server/libs/
├── master-server/libs/
├── worker-server/libs/
└── tools/libs/

少一个目录都不行。

有人试过只漏掉tools/libs目录，结果在执行upgrade-schema.sh时直接报错退出，提示找不到驱动，而其他服务却启动正常-3。漏掉任何一个，都会在某个环节报错。

第三层：版本陷阱——驱动类名的“新旧之争”

另一个常见的坑是驱动版本与类名不匹配。

DolphinScheduler 3.x的application.yaml里默认配置的驱动类是com.mysql.cj.jdbc.Driver。

如果你用的是老版本的驱动包（如mysql-connector-java-5.1.xx.jar），它的驱动类名是com.mysql.jdbc.Driver（注意少了.cj）。

类名不匹配，驱动加载必然失败。

从MySQL Connector/J 8.0开始，官方推荐的驱动包名变成了mysql-connector-j-8.x.x.jar，核心驱动类名是com.mysql.cj.jdbc.Driver。

所以：要么用mysql-connector-java-8.0.16+版本（推荐8.0.16），要么用mysql-connector-j-8.0.33+版本，核心类名都是com.mysql.cj.jdbc.Driver。

解决方案

前置准备

项目	说明
下载驱动	从Maven中央仓库下载，推荐版本8.0.16或8.0.33
文件格式	`.jar`文件，约2.4MB
核心类名	`com.mysql.cj.jdbc.Driver`

下载命令（以8.0.33为例）：

wget https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.0.33/mysql-connector-j-8.0.33.jar

将驱动复制到所有模块的libs目录

1. 确认DolphinScheduler安装目录下的模块结构：

cd /opt/dolphinscheduler
ls -la

应该能看到api-server、alert-server、master-server、worker-server、tools等目录。

2. 将驱动复制到所有模块的libs目录：

# 切换到dolphinscheduler用户
su - dolphinscheduler

# 复制驱动到所有模块
cp mysql-connector-j-8.0.33.jar /opt/dolphinscheduler/api-server/libs/
cp mysql-connector-j-8.0.33.jar /opt/dolphinscheduler/alert-server/libs/
cp mysql-connector-j-8.0.33.jar /opt/dolphinscheduler/master-server/libs/
cp mysql-connector-j-8.0.33.jar /opt/dolphinscheduler/worker-server/libs/
cp mysql-connector-j-8.0.33.jar /opt/dolphinscheduler/tools/libs/

# 如果是Standalone模式，也要放到standalone-server目录
cp mysql-connector-j-8.0.33.jar /opt/dolphinscheduler/standalone-server/libs/

⚠️ 注意：驱动必须同时放到所有模块的libs目录，少一个都不行--3。

3. 验证驱动文件完整性：

# 检查每个目录下是否有驱动文件
ls -la /opt/dolphinscheduler/*/libs/mysql-connector-*.jar

# 校验驱动包完整性，确认驱动类存在
jar tf /opt/dolphinscheduler/api-server/libs/mysql-connector-j-8.0.33.jar | grep cj.jdbc.Driver

修改配置文件中的驱动类名

确保配置文件中的驱动类名是com.mysql.cj.jdbc.Driver。

检查application.yaml：

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver  # 必须是这个

检查dolphinscheduler_env.sh：

# 查看环境变量
cat /opt/dolphinscheduler/bin/env/dolphinscheduler_env.sh | grep -i driver

如果有SPRING_DATASOURCE_DRIVER_CLASS_NAME变量，确保其值为com.mysql.cj.jdbc.Driver。

重启服务

cd /opt/dolphinscheduler

# 停止服务
./bin/dolphinscheduler-daemon.sh stop standalone-server

# 等待5秒
sleep 5

# 启动服务
./bin/dolphinscheduler-daemon.sh start standalone-server

# 查看日志确认启动正常
tail -100 standalone-server/logs/dolphinscheduler-standalone.log

验证结果

登录DolphinScheduler Web UI
进入 安全中心 → 数据源中心
创建或编辑MySQL类型的数据源
点击 “测试连接”

✅ 成功判定标准

✅ Web UI 数据源测试连接显示 “连接成功”
✅ 服务启动日志无 ClassNotFoundException、NoClassDefFoundError 报错
✅ 执行 SQL 任务可正常查询 MySQL/Doris 数据

预期结果：显示 “连接成功”，不再报Cannot load driver class。

💡 补充坑：目录权限不足导致驱动加载失败不注意会怎样：驱动文件已放置，但启动日志仍报找不到类，大概率是 dolphinscheduler 用户对 libs 目录或驱动文件没有读取权限。正确做法：执行 chown -R dolphinscheduler:dolphinscheduler /opt/dolphinscheduler 统一目录权限，确保所有子模块都能读取驱动文件。

经验总结

怕你忘了，我再啰嗦一遍：DolphinScheduler不包含MySQL驱动，必须手动添加。而且不是放一个地方就行，是每个模块的libs目录都要放。

落到具体操作上就是四条：

下载MySQL驱动（8.0.16+版本）：推荐使用mysql-connector-j-8.0.33.jar，类名是com.mysql.cj.jdbc.Driver。不要用5.x版本，类名不对。
复制到所有模块的libs目录：包括api-server/libs、alert-server/libs、master-server/libs、worker-server/libs、tools/libs，以及Standalone模式下的standalone-server/libs-。少一个目录，就会在某个模块报错找不到驱动。
验证驱动已加载：如果仍有问题，可以用jar tf mysql-connector-j-8.0.33.jar | grep Driver.class确认驱动类存在于JAR包中。
重启服务：驱动生效的前提是服务完全重启，不是刷新页面就能解决的。