告别‘QMYSQL driver not loaded’：用Qt Creator快速编译MySQL插件（Qt 5.15.2 + MinGW 64）
Qt Creator全流程编译MySQL驱动指南：告别"QMYSQL driver not loaded"错误
当你满怀期待地在Qt项目中写下QSqlDatabase::addDatabase("QMYSQL")，却遭遇冰冷的"driver not loaded"提示时，这种挫败感我深有体会。作为长期使用Qt开发数据库应用的工程师，我发现许多开发者卡在这一步的原因不是技术难度，而是缺乏一个完整的IDE内解决方案。本文将带你完全在Qt Creator环境中完成从源码编译到驱动部署的全过程，无需切换命令行或其他工具。
1. 环境准备与源码验证
在开始编译之前，我们需要确认几个关键要素是否就位。打开你的Qt Creator，首先检查安装的Qt版本是否包含源码。默认情况下，在线安装器可能只安装了二进制文件，这时需要通过Qt Maintenance Tool补充安装源码组件。
验证源码是否存在的最快方法是在Qt Creator中按下Ctrl+K打开全局搜索，输入路径qtbase/src/plugins/sqldrivers/mysql。如果能看到mysql.pro和一系列.cpp文件，说明你已经具备编译基础。否则，需要重新运行安装程序勾选"Sources"组件。
提示：建议使用Qt 5.15.2 LTS版本进行编译，这是目前企业环境中使用最广泛的稳定版本，与MySQL 8.0的兼容性也经过充分验证。
所需工具链确认：
- Qt Creator 4.11以上版本
- MinGW 8.1.0 64位工具链
- MySQL Connector/C 8.0开发库
2. MySQL开发库的获取与配置
MySQL驱动的编译需要链接官方的C客户端库。这里有个常见的误区：直接从MySQL Server安装目录获取lib文件可能导致版本不匹配。正确做法是从MySQL官网单独下载Connector/C开发包。
在Qt Creator中新建一个临时项目，用以下代码片段快速验证库文件兼容性：
#include <mysql.h> int main() { qDebug() << "MySQL client version:" << mysql_get_client_info(); return 0; }如果这段代码能正常编译运行并输出版本号，说明你的开发环境配置正确。否则需要按照以下步骤配置：
- 从MySQL官网下载Connector/C 8.0 ZIP包
- 解压到不含中文和空格的路径（如
C:/dev/mysql-connector） - 在Qt Creator的Projects设置中添加包含路径：
mysql-connector/includemysql-connector/lib
3. Qt Creator中的驱动编译流程
3.1 项目配置调整
在Qt Creator中直接打开mysql.pro文件时，你会发现项目默认配置可能不完整。这时需要手动调整几个关键设置：
- 在
mysql.pro中添加库引用：
LIBS += -L"$$PWD/../../../../../mysql-connector/lib" -lmysql INCLUDEPATH += "$$PWD/../../../../../mysql-connector/include"- 修改
qsqldriverbase.pri配置：
# 替换原有配置 include(./configure.pri) QT += sql3.2 构建套件选择
在Projects视图中，确保选择了正确的构建套件：
- 使用MinGW 64-bit工具链
- 构建类型选择Release（开发阶段也可用Debug）
- 影子构建（Shadow build）建议禁用，避免输出路径混乱
3.3 常见构建问题解决
当点击构建按钮后，可能会遇到以下典型错误及解决方案：
| 错误类型 | 表现特征 | 解决方案 |
|---|---|---|
| 链接错误 | undefined reference tomysql_xxx | 检查库路径是否正确，确认libmysql.dll.a存在 |
| 头文件缺失 | mysql.h not found | 验证INCLUDEPATH设置，确保路径不含中文 |
| 版本冲突 | client plugin does not support | 使用MySQL Connector/C 8.0而非Server的库 |
4. 驱动部署与测试
构建成功后，Qt Creator会在编译输出目录生成qsqlmysql.dll文件。但直接使用可能仍然报错，这是因为：
- 驱动DLL需要复制到正确位置：
# 将生成的驱动复制到Qt插件目录 cp release/qsqlmysql.dll %Qt_DIR%/plugins/sqldrivers/- MySQL运行时库需要能被找到：
- 将
libmysql.dll从Connector/C的bin目录复制到：- Qt的bin目录
- 或系统PATH包含的目录
- 或你的应用程序输出目录
- 将
在Qt Creator中新建一个测试项目，使用以下代码验证驱动是否正常工作：
#include <QCoreApplication> #include <QSqlDatabase> #include <QDebug> int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); qDebug() << "Available drivers:"; qDebug() << QSqlDatabase::drivers(); QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL"); db.setHostName("localhost"); db.setDatabaseName("test"); db.setUserName("root"); if (!db.open()) { qDebug() << "Failed to connect:" << db.lastError().text(); } else { qDebug() << "Connected successfully!"; db.close(); } return a.exec(); }5. 高级配置与性能优化
当驱动基本功能可用后，你可能还需要考虑以下进阶配置：
连接池设置：
// 在应用启动时初始化连接池 QSqlDatabase::addDatabase("QMYSQL", "pool_connection1"); QSqlDatabase::addDatabase("QMYSQL", "pool_connection2");SSL加密连接： 在连接字符串中添加：
db.setConnectOptions("SSL_KEY=client-key.pem;SSL_CERT=client-cert.pem;SSL_CA=ca.pem");性能调优参数：
// 设置预处理语句缓存大小 db.setConnectOptions("PREPARE_CACHE_SIZE=25"); // 设置连接超时为5秒 db.setConnectOptions("CONNECT_TIMEOUT=5");在实际项目部署时，建议将MySQL驱动和依赖库打包到应用程序目录下的sqldrivers子文件夹中，这样可以实现绿色部署。同时，通过QCoreApplication::addLibraryPath()动态添加插件搜索路径，增加部署灵活性。
遇到连接问题时，可以在MySQL配置文件中增加以下调试选项：
[client] log=mysql_client.log最后提醒一点：当你的应用需要分发给最终用户时，记得在安装包中包含libmysql.dll和qsqlmysql.dll，并确保它们的架构（32/64位）与你的应用程序一致。