Qt6实战：从源码编译MySQL数据库驱动，打通数据库连接最后一公里

1. 为什么Qt6不给你现成的MySQL驱动？这事儿得从根儿上聊起

很多刚接触Qt6做数据库开发的朋友，估计都踩过这个坑：兴冲冲地打开Qt Creator，准备连接MySQL大干一场，结果在QSqlDatabase::drivers()返回的列表里，死活找不到那个心心念念的“QMYSQL”。去安装目录下的plugins/sqldrivers文件夹里一看，空空如也，或者只有个qsqlodbc.dll在那儿躺着。这时候你可能会有点懵，甚至怀疑自己是不是装了个假的Qt。

这事儿真不怪你。从Qt5的某个版本开始，尤其是到了Qt6，官方出于一些现实的考虑，确实不再为MySQL和Oracle这类数据库提供预编译好的驱动插件了。他们只把驱动插件的源代码打包在Qt的源码包里。你想想看，MySQL的客户端库（就是那个libmysql.dll或libmysqlclient.so）本身版本众多，授权协议（GPL）也比较特殊，而且不同平台、不同编译器的二进制兼容性是个大麻烦。Qt官方如果预编译一个，很可能跟你本地安装的MySQL客户端库对不上，反而会导致更多连接失败的问题。所以，他们干脆把选择权交还给开发者：“源码在这儿，您根据自己的环境，自己动手，丰衣足食吧。”

这听起来有点麻烦，但其实换个角度想，这也是件好事。自己编译出来的驱动，跟你本地MySQL的版本、位数（32位还是64位）是百分百匹配的，稳定性反而更有保障。这个过程就像是给你的Qt“定制”一把专属的、能打开你家MySQL大门的钥匙，虽然制作过程需要点手艺，但做好了就一劳永逸。我刚开始也觉得很折腾，但成功编译一次之后，以后再换环境、换版本，心里就特别有底，因为你知道每一步是怎么回事，出了问题也知道该往哪儿排查。

所以，今天咱们就抛开那些复杂的理论，我手把手带你走一遍在Windows上，用Qt 6.2.4和MySQL 8.0，从源码编译出属于你自己的MySQL驱动的完整过程。我会把我在这个过程中踩过的所有“坑”，以及怎么填平它们的经验，都毫无保留地分享给你。目标就一个：让你能稳稳当当地打通Qt6连接MySQL的这“最后一公里”。

2. 开工前的“弹药”检查：环境与源码准备

磨刀不误砍柴工，编译驱动前，我们必须把几样关键的东西准备好，并且确认它们之间是“兼容”的。这里任何一个环节出问题，都可能导致后续编译失败或者驱动无法使用。

### 2.1 核心三件套：Qt、MySQL与编译器

首先，你得明确知道你电脑上这三样东西的具体版本和位数。这是整个操作的基石。

1. Qt版本：打开你的Qt Creator，在“帮助”菜单里选择“关于Qt Creator”，或者在“项目”模式下的Kit设置里，都能看到你使用的Qt套件版本，比如我这次用的就是 Qt 6.2.4。更重要的是，你必须确认你安装Qt时，勾选了源码（Source）组件。这是编译驱动的前提！如果你当初在线安装时没选，可以重新运行Qt的维护工具（MaintenanceTool），把源码包给加上。

2. MySQL版本：打开你的MySQL命令行客户端或者Shell，输入 SELECT VERSION(); 命令，就能看到详细的版本信息。比如我的是 8.0.31。同时，你必须知道你的MySQL安装是32位还是64位的。一个简单的判断方法是，去MySQL的安装目录（比如C:\Program Files\MySQL\MySQL Server 8.0\bin）看看，如果里面有libmysql.dll，并且你用资源管理器查看该文件的属性，在“详细信息”里能看到“64位”字样，那就是64位的。

3. 编译器位数：这里有个铁律必须遵守：你的Qt编译套件的位数，必须和你的MySQL客户端库的位数一致！ 如果你用64位的MySQL，那么就必须用64位的MinGW或MSVC来编译Qt和这个驱动。混用32位和64位是绝对行不通的。在Qt Creator的“项目”设置里，你可以看到你当前Kit使用的是哪种编译器，务必确认其位数。

### 2.2 定位驱动源码：宝藏藏在哪儿

Qt的驱动源码就藏在它的源码目录里。假设你的Qt安装在D:\Qt，那么源码路径通常就是D:\Qt\6.2.4\Src。我们需要关注的宝藏位置是： D:\Qt\6.2.4\Src\qtbase\src\plugins\sqldrivers

进入这个目录，你会发现几个子文件夹，比如mysql、psql（PostgreSQL）、odbc等。这个mysql文件夹，就是我们今天要主攻的阵地。打开它，你会发现里面主要是.cpp、.h和.json文件，并没有旧版本Qt中常见的.pro项目文件。这是因为Qt6全面转向了CMake构建系统，所以我们需要用CMake的方式来编译它。

### 2.3 处理MySQL安装路径的“隐形杀手”：空格

这是一个非常经典，又很容易被忽略的坑。很多朋友的MySQL默认安装在C:\Program Files\MySQL\...这个路径下。“Program Files”中间那个空格，对于很多命令行工具和构建系统来说，是个需要特殊处理的字符，有时候处理不好就会导致路径被错误分割，编译时找不到头文件或库文件。

为了避免这个麻烦，我强烈建议采用一个“迂回”但非常稳妥的策略：不直接引用带空格的原始MySQL安装路径，而是将必要的文件复制到一个干净的、无空格的临时目录中。 具体来说，我们需要从MySQL的安装目录里，找到两个关键的文件夹：

• include：里面包含了mysql.h等所有连接MySQL所需的头文件。
• lib：里面包含了libmysql.lib（用于链接）和libmysql.dll（运行时需要）等库文件。

你可以在MySQL安装目录的根目录下，或者在其子目录（如MySQL Server 8.0）下找到它们。把它们整个复制到一个你自己新建的、路径简单无空格的文件夹里，比如我习惯放在D:\Dev\mysql_for_qt。这样，后续我们配置时，就指向这个干净路径，能省去一大堆因路径问题导致的编译错误。

3. 核心攻坚：配置与编译驱动项目

环境准备好，源码也找到了，接下来就是最核心的编译环节。这个过程我们主要在Qt Creator里完成，但需要手动进行一些关键的配置。

### 3.1 创建并配置CMake项目

首先，我们不在原始的源码目录里直接编译。好的习惯是建立一个独立的构建目录（build directory）。我在D:\Dev下新建了一个文件夹叫build-mysql-driver。然后打开Qt Creator，选择“打开文件或项目”，导航到我们之前找到的驱动源码目录（...\sqldrivers），但注意，不是打开mysql子文件夹，而是打开它上一级的sqldrivers目录。在这个目录下，你会找到一个名为CMakeLists.txt的文件，选择它打开。

Qt Creator会把它识别为一个CMake项目。它会让你选择一个构建目录，你就选择刚才新建的D:\Dev\build-mysql-driver。接着，它会让你选择Kit，这里一定要选对！选择那个与你MySQL位数一致的Kit（例如，64位的MySQL就选“Desktop Qt 6.2.4 MinGW 64-bit”）。

### 3.2 修改关键配置文件：.cmake.conf

项目打开后，Qt Creator会开始自动配置。但默认配置并不知道我们的MySQL在哪里。这时候就需要修改一个关键的配置文件。在Qt Creator左侧的项目文件列表中，展开sqldrivers目录，找到名为 .cmake.conf 的文件。这个文件就是用来配置各个数据库驱动开关和路径的。

双击打开它，我们需要在文件末尾添加几行配置。找到文件末尾，添加如下内容（请根据你的实际路径修改）：

# 启用MySQL驱动特性
SET(FEATURE_sql_mysql ON)

# 设置MySQL头文件目录（指向你之前复制的无空格路径下的include文件夹）
SET(MySQL_INCLUDE_DIR "D:/Dev/mysql_for_qt/include")

# 设置MySQL库文件（指向你之前复制的无空格路径下的lib文件夹中的.lib文件）
SET(MySQL_LIBRARY "D:/Dev/mysql_for_qt/lib/libmysql.lib")

这里有几个细节要注意：

1. D:/Dev/mysql_for_qt 要换成你自己创建的、无空格的那个临时目录路径。
2. 路径使用正斜杠/或双反斜杠\\，CMake都能识别，但正斜杠更简洁。
3. MySQL_LIBRARY 指向的是 .lib 文件（静态导入库），不是 .dll 文件。

### 3.3 解决编译过程中的“拦路虎”

配置好后，点击Qt Creator左下角的“构建”按钮（那个小锤子）。但事情往往不会一帆风顺，我们很可能会遇到一两个常见的错误。

• 错误一：CMake缓存冲突 如果你之前尝试编译过，或者打开项目的位置不对，可能会报一些奇怪的CMake错误。这时候，最干脆的解决办法就是清理构建目录。直接去文件管理器，把你创建的D:\Dev\build-mysql-driver文件夹整个删掉。然后在Qt Creator里，关闭当前项目，重新从第一步“打开文件或项目”开始，让CMake重新生成一遍缓存。这能解决90%的配置缓存问题。

• 错误二：源码兼容性问题（MySQL 8.0+特有） 这是一个非常典型的坑。MySQL 8.0开始，其客户端库中某些函数的签名（参数类型）发生了变化，而Qt源码中的驱动代码可能还没有及时更新。具体错误信息通常会指向 qsql_mysql.cpp 文件中的某个函数，比如 my_bool 类型未定义。 解决方法需要修改一行源码。找到你的Qt源码目录下的这个文件： D:\Qt\6.2.4\Src\qtbase\src\plugins\sqldrivers\mysql\qsql_mysql.cpp 用文本编辑器（如Notepad++或VSCode）打开它，搜索 my_bool。在较新的Qt版本（如6.2.4）中，这个问题可能已被修复。如果没修复，你会看到类似 my_bool foo = 0; 的代码。你需要将 my_bool 替换成 bool。因为MySQL 8.0的mysql.h中，my_bool已经被bool或char替代了。通常修改这一处即可。注意：修改的是Qt源码目录下的文件，不是你构建目录里的。

解决完这些错误后，再次点击构建。如果一切顺利，你会在Qt Creator的“编译输出”窗口看到成功的提示。编译生成的驱动文件（qsqlmysql.dll 和 qsqlmysqld.dll，后者是调试版）位于你的构建目录中，具体路径类似于： D:\Dev\build-mysql-driver\plugins\sqldrivers

4. 部署与测试：让驱动真正工作起来

编译成功只是第一步，我们还得把生成的驱动“安装”到正确的位置，并配置好运行时环境，它才能真正被Qt程序加载和使用。

### 4.1 安置驱动插件

找到上一步编译生成的 qsqlmysql.dll 文件（如果你需要调试，可能也会用到带d后缀的调试版）。我们需要把它复制到你的Qt编译器的插件目录下。这个目录的路径通常是： D:\Qt\6.2.4\mingw_64\plugins\sqldrivers （注意，这里是 mingw_64，是你Qt的编译器安装目录，不是源码目录 Src）。把 qsqlmysql.dll 复制到这个 sqldrivers 文件夹里。现在，你的Qt运行时环境就认识MySQL驱动了。

### 4.2 提供运行时依赖：libmysql.dll

光有Qt的驱动插件还不够，这个插件在运行时需要调用MySQL官方的客户端库。所以，我们需要把之前从MySQL安装目录复制出来的 lib 文件夹里的 libmysql.dll 文件，放到一个系统或应用程序能找到的地方。通常有三个选择：

1. 放到你的应用程序的生成目录（即你的exe文件所在文件夹）。这是最直接、最推荐的方式，便于程序打包分发。
2. 放到Qt编译器的 bin 目录下（D:\Qt\6.2.4\mingw_64\bin）。
3. 放到系统的 PATH 环境变量包含的目录中（如 C:\Windows\System32，但不推荐，容易造成版本冲突）。

为了简单起见，我们测试时可以先用第二种方法。

### 4.3 编写代码进行终极测试

现在，让我们写一段最简单的代码来验证一切是否就绪。新建一个Qt Widgets Application项目，在项目的 .pro 文件中，确保已经添加了 sql 模块：

QT += core gui sql

然后，在你的主窗口构造函数或一个按钮的槽函数里，添加以下测试代码：

#include <QSqlDatabase>
#include <QSqlError>
#include <QDebug>
#include <QMessageBox>

// 1. 首先，打印出当前可用的所有数据库驱动，看看QMYSQL在不在里面
QStringList drivers = QSqlDatabase::drivers();
qDebug() << "Available drivers:" << drivers;

// 2. 尝试添加一个MySQL数据库连接
QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL");
if (!db.isValid()) {
    QMessageBox::critical(this, "错误", "无法创建QMYSQL数据库连接！");
    return;
}

// 3. 配置数据库连接参数（请根据你的MySQL设置修改）
db.setHostName("localhost"); // 或 "127.0.0.1"
db.setPort(3306);
db.setUserName("root"); // 你的MySQL用户名
db.setPassword("your_password"); // 你的MySQL密码
db.setDatabaseName("test"); // 一个你已存在的数据库名，比如 `test`

// 4. 尝试打开连接
if (db.open()) {
    QMessageBox::information(this, "成功", "恭喜！数据库连接成功！");
    // 连接成功，可以在这里执行一些简单的SQL查询，比如 db.exec("SELECT 1;");
    db.close();
} else {
    QString error = db.lastError().text();
    QMessageBox::critical(this, "连接失败", "无法连接到数据库。错误信息：\n" + error);
}

运行这个程序。如果一切完美，你会先看到控制台输出中包含 "QMYSQL"，然后弹窗提示连接成功。如果 drivers() 列表里没有 QMYSQL，说明驱动插件没有放对位置。如果创建连接无效，可能是驱动插件本身编译有问题。如果能创建但无法打开，错误信息通常会非常明确，比如“无法连接到MySQL服务器”（检查主机、端口、MySQL服务是否启动）、“Access denied”（用户名密码错误）、“Unknown database”（数据库名不存在），根据提示排查即可。

当你看到“连接成功”的提示时，那份成就感是实实在在的。这意味着你不仅解决了一个具体的技术问题，更深入理解了Qt插件机制和本地编译的流程。以后再遇到其他数据库驱动，或者需要为特定平台编译，你都有了可以复用的经验。自己动手编译驱动，虽然前期多花些时间，但换来的是对项目依赖更清晰的掌控和更强的环境适配能力，这在复杂的项目开发和部署中，是非常宝贵的。