MySQL连接驱动未正确加载会导致WorkBuddy静默跳过数据源初始化，需确认lib/下存在≥8.0.23的mysql-connector-j-*.jar、application.yml中driver-class-name为com.mysql.cj.jdbc.Driver、无classpath冲突、沙盒权限正常且JVM参数未破坏模块化服务发现。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
确认 MySQL 连接驱动是否已正确加载
WorkBuddy 启动时若找不到 mysql-connector-j 或对应 JDBC 驱动类，会静默跳过 MySQL 数据源初始化，导致「数据库管理」页为空或报错 java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver。这不是配置问题，而是驱动未就位。
- Windows/macOS/Linux 用户均需检查 WorkBuddy 安装目录下的
lib/子目录，确认存在形如mysql-connector-j-8.0.33.jar的文件（版本需 ≥ 8.0.23） - 若缺失：前往 MySQL 官方下载页 获取最新 GA 版本的 ZIP 包，解压后将
mysql-connector-j-*.jar复制到lib/目录下 - 禁止使用
mysql-connector-java（旧命名），WorkBuddy 仅识别新命名规范；也禁止混用多个版本 jar 文件，否则类加载器可能冲突
验证 application.yml 中 driver-class-name 配置是否匹配
即使驱动 JAR 已存在，若配置项写错，WorkBuddy 仍会初始化失败。常见错误是沿用旧版写法或大小写不一致。
- 打开
application.yml（路径通常为%APPDATA%\CodeBuddy\workbuddy\config\application.yml或~/Library/Application Support/CodeBuddy/workbuddy/config/application.yml） - 检查
spring.datasource.driver-class-name的值必须为：com.mysql.cj.jdbc.Driver（注意cj，不是jdbc或driver） - 若使用 MySQL 5.7 且无法升级驱动，可临时降级为
com.mysql.jdbc.Driver，但该类在 8.0+ 驱动中已被移除，仅限兼容场景 - 确保 YAML 缩进正确——
driver-class-name必须与url、username同级，且前面是两个空格，不可用 Tab
排查 classpath 冲突与沙盒限制（macOS/Linux）
macOS 和部分 Linux 发行版上，WorkBuddy 运行在受限沙盒环境，若系统级 Java 环境变量污染了 classpath，或存在全局 CLASSPATH，会导致驱动加载失败或版本错乱。
- 终端执行
echo $CLASSPATH，若输出非空，说明有外部干扰；临时清空它：unset CLASSPATH，再启动 WorkBuddy - macOS 用户需确认「完全磁盘访问」权限已授予
WorkBuddy.app，否则其无法读取自身lib/下的 jar 文件（表现为日志中出现Unable to load resource from lib/） - Linux 用户若使用 Snap 或 Flatpak 安装包，其自带沙盒机制会拦截本地 jar 加载——必须使用官方提供的
.deb或.AppImage安装方式
检查 JVM 启动参数是否禁用了模块化类加载
WorkBuddy 桌面版基于 Java 17+ 构建，默认启用模块系统。若用户手动修改了 JVM 参数（如添加 --illegal-access=deny 或 --add-modules=ALL-SYSTEM），可能破坏 JDBC 驱动的自动服务发现机制。
- 查看启动日志（
logs/workbuddy.log）中是否含Failed to load service: java.sql.Driver - 若存在，编辑启动脚本（Windows 为
workbuddy.bat，macOS/Linux 为workbuddyshell 脚本），删除所有自定义-XX:或--add-类参数 - 不要强行添加
--add-opens，WorkBuddy 自身已预设必要模块开放策略；额外添加反而触发模块冲突
WorkBuddy 不会主动下载或热替换 JDBC 驱动，所有依赖必须由用户显式提供并保持路径稳定。一旦驱动加载失败，后续所有数据库功能（包括连接测试、表结构分析、SQL 执行）都会被绕过，而不是报错提示——这是最容易被忽略的“静默失效”点。
