Qt 6.7.3连接远程MySQL数据库（保姆级教程）

Qt 6.7.3 开发环境下的远程 MySQL 数据库连接深度指南

在嵌入式开发与桌面应用开发领域，Qt 框架凭借其强大的跨平台能力和丰富的模块支持，占据了重要的地位。在涉及到数据持久化存储的应用场景中，MySQL 作为一款成熟、开源的关系型数据库管理系统，是 Qt 应用程序后端的常见选择。然而，由于 Qt 6 版本在许可证及模块架构上的调整，默认安装包中通常不再直接包含预编译好的 MySQL 驱动（QMYSQL），这导致开发者在初次尝试连接 MySQL 时常遭遇"Driver not loaded"的错误。

本文将以 Qt 6.7.3 (MinGW 64-bit) 环境为例，详细阐述如何获取第三方编译驱动、正确配置动态链接库路径，并通过 C++ 代码实现对远程 MySQL 数据库的连接与增删改查操作。我们将深入剖析每一个步骤背后的技术原理，确保开发环境配置的准确性与稳定性。

一、驱动获取与环境匹配

Qt 的 SQL 模块通过插件机制（Plugin System）来加载不同的数据库驱动。要让 QSqlDatabase 识别 MySQL，必须在 Qt 的插件目录下存在 qsqlmysql.dll，且该文件必须与当前的 Qt 版本（6.7.3）、编译器版本（MinGW 64-bit）以及构建模式严格匹配。此外，该插件依赖 MySQL 的 C 语言客户端库（libmysql.dll）来进行底层的网络通信。

由于手动编译驱动涉及复杂的环境配置（如安装 Perl、Python、OpenSSL 以及 MySQL Connector/C 开发包），直接使用社区提供的预编译二进制文件是更为高效的解决方案。

1. 定位并下载驱动

GitHub 上的 thecodemonkey86/qt_mysql_driver 仓库提供了针对不同 Qt 版本的预编译驱动。访问该仓库的 Release 页面，可以找到适配 Qt 6.7.3 的版本。

在下载列表中，选择与本地开发环境相匹配的压缩包。由于本地使用的是 Qt 6.7.3 以及 MinGW 64-bit 编译器，应当选择标记为 qsqlmysql-6.7.3-mingw_64.zip 的文件。

图 1：GitHub 驱动下载页面，红框选中了适配 Qt 6.7.3 MinGW 64位版本的驱动压缩包。

下载完成后，对压缩包进行解压操作。解压后的目录结构通常包含两个部分：直接用于 Qt SQL 驱动加载的插件文件，以及 MySQL 自身运行所需的依赖库。

图 2：压缩包解压过程，准备提取内部的核心动态链接库文件。

2. 驱动文件组件解析

解压后的文件夹中包含了一系列 .dll（动态链接库）文件和 .debug（调试符号）文件。理解这些文件的作用对于后续的正确部署至关重要：

qsqlmysql.dll: 这是 Qt 的 SQL 模块插件，封装了 Qt SQL 接口与 MySQL C API 之间的调用逻辑。Qt 程序通过加载这个文件来"理解"如何操作 MySQL。
libmysql.dll : 这是 MySQL 的官方 C 客户端库。qsqlmysql.dll 内部会调用这个库中的函数来建立 TCP 连接、发送 SQL 语句。如果没有这个文件，插件虽然能被 Qt 找到，但无法初始化。
libcrypto-3-x64.dll & libssl-3-x64.dll : 这是 OpenSSL 的加密库。现代 MySQL 连接（尤其是远程连接）通常默认要求 SSL 加密，或者验证身份时需要加密算法支持。这些是 libmysql.dll 的依赖项。

图 3：解压后的文件列表，展示了驱动插件、MySQL 客户端库以及 SSL 加密库。

二、驱动部署与动态库路径配置

Windows 操作系统加载动态链接库遵循特定的搜索顺序。为了让 Qt Creator 在运行程序时能正确加载这些库，需要将它们分别放置在 Qt 安装目录下的特定位置。

1. 部署 Qt SQL 插件

首先处理 qsqlmysql.dll。Qt 应用程序在启动时，会扫描其安装目录下的 plugins 文件夹来加载扩展功能。对于 SQL 驱动，目标路径通常是 .../plugins/sqldrivers。

找到 Qt 6.7.3 MinGW 64位的安装路径，例如 D:\Qt673\6.7.3\mingw_64\plugins\sqldrivers。将解压包中的 qsqlmysql.dll 和对应的调试文件 qsqlmysql.debug 复制到此目录下。

注意：在复制过程中，需确保复制的是 qsqlmysql.dll 。虽然目录下可能存在其他数据库（如 Mimer SQL 对应的 qsqlmimer.dll）的驱动，但针对 MySQL 的连接，必须使用 qsqlmysql 开头的文件。

图 4：将 qsqlmysql.dll 和 qsqlmysql.debug 文件复制到 Qt 的 plugins/sqldrivers 目录下。

2. 部署 MySQL 依赖库

接下来处理 libmysql.dll 及其依赖的 SSL 库。由于 qsqlmysql.dll 是在运行时动态链接到 libmysql.dll 的，操作系统需要在系统的 PATH 环境变量或者应用程序的可执行文件目录中找到它。对于 Qt 开发环境，最直接的方法是将这些依赖库放入 Qt 的二进制执行目录 bin 中，因为该目录已被添加到 Qt Creator 的运行环境变量中。

目标路径为 D:\Qt673\6.7.3\mingw_64\bin。将剩余的三个核心文件：libmysql.dll、libcrypto-3-x64.dll 以及 libssl-3-x64.dll 移动或复制到该目录下。

图 5：准备将 MySQL 客户端库和 SSL 加密库移动到 Qt 的 bin 目录下。

图 6：文件移动完成，确保 libmysql.dll 等文件位于 bin 目录中，以便系统运行时加载。

至此，驱动安装层面的物理部署已经完成。

三、驱动加载验证

在进行复杂的数据库连接编程之前，首先需要验证 Qt 是否已经成功识别了新安装的 MySQL 驱动。可以通过打印 QSqlDatabase::drivers() 的返回值来进行诊断。

创建一个新的 Qt Console 或 Widgets 项目，在 main.cpp 中加入以下测试代码：

cpp 复制代码

#include <QCoreApplication>
#include <QSqlDatabase>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);
    qDebug() << "可用驱动：" << QSqlDatabase::drivers();
    return 0;
}

运行程序，观察"应用程序输出"窗口。如果配置正确，输出列表中应当包含字符串 "QMYSQL"。

图 7：成功的驱动加载输出，控制台显示 ("QSQLITE", "QMARIADB", "QMYSQL", "QODBC"...)，证明 QMYSQL 驱动已就绪。

相反，如果输出列表中没有 "QMYSQL"，或者出现如下的错误提示，则说明驱动部署存在问题。

图 8：失败的驱动加载示例，列表中缺失 QMYSQL，表明插件未被加载或依赖库缺失。

常见失败原因分析：

位数不匹配：下载了 32 位的 DLL 但使用了 64 位的 Qt 编译器（或反之）。
依赖缺失 ：libmysql.dll 没有正确放入 bin 目录，导致 qsqlmysql.dll 加载失败。
编译器版本不兼容：使用了 MSVC 编译的 DLL 用于 MinGW 环境。

四、远程数据库连接代码实现

驱动验证通过后，即可编写代码连接远程 MySQL 服务器。连接过程主要涉及 QSqlDatabase 类的参数配置，包括主机地址、端口、数据库名、用户名和密码。

1. 核心代码解析

以下是一个完整的示例代码，展示了如何初始化连接、处理连接错误以及执行简单的 SQL 查询。

cpp 复制代码

#include "widget.h"
#include <QApplication>
#include <QSqlDatabase>
#include <QSqlQuery>
#include <QSqlError>
#include <QDebug>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    // 这里为了演示方便，不显示主窗口，仅在控制台输出
    Widget w; 
    w.show();

    // 1. 添加数据库驱动
    // 使用 addDatabase 静态方法，指定驱动类型为 QMYSQL
    QSqlDatabase data_base = QSqlDatabase::addDatabase("QMYSQL");

    // 2. 配置连接参数
    data_base.setHostName("host");      // 替换为远程服务器的IP地址或域名
    data_base.setPort(3306);            // MySQL 默认端口为 3306
    data_base.setDatabaseName("bookstore"); // 目标数据库名称
    data_base.setUserName("user_name"); // 具有访问权限的用户名
    data_base.setPassword("passwd");    // 用户对应的密码
    
    // 3. 设置连接选项
    // "SSL=false" 显式关闭 SSL 连接。
    // 在开发环境中，如果服务器未配置 SSL 证书，开启 SSL 可能导致握手失败。
    data_base.setConnectOptions("SSL=false");

    // 4. 打开数据库连接
    if(!data_base.open())
    {
        // 连接失败处理
        qDebug() << "connect failed";
        // 输出详细的错误信息，这是排查网络问题或权限问题的关键
        qDebug() << data_base.lastError().text(); 
    }
    else
    {
        qDebug() << "success";

        // 5. 执行 SQL 查询
        // QSqlQuery 对象构造时若不指定 db，默认使用最后一次打开的连接
        QSqlQuery query;  

        // 执行 SELECT 语句，查询 books 表的所有数据
        if (query.exec("SELECT * FROM books"))  
        {
            // query.next() 用于遍历结果集，每次调用移动到下一行
            while (query.next())
            {
                // 6. 获取字段值
                // 使用 value() 方法根据字段名或索引获取数据
                // 并转换为对应的 C++ 类型
                int id = query.value("id").toInt();           
                QString title = query.value("title").toString(); 
                QString author = query.value("author").toString();
                double price = query.value("price").toDouble();   

                // 输出结果
                qDebug() << "id:" << id
                         << ", title:" << title
                         << ", author:" << author
                         << ", price:" << price;
            }
        }
        else
        {
            // SQL 语法错误或执行错误处理
            qDebug() << "查询失败：" << query.lastError().text();
        }

        // 7. 关闭连接
        // 在实际项目中，连接通常在程序退出时关闭，或使用连接池管理
        data_base.close();  
    }
    
    // 再次确认驱动情况
    qDebug() << "可用驱动：" << QSqlDatabase::drivers();
    
    return a.exec();
}

2. 代码执行效果

当上述代码正确配置了远程服务器的 IP、账号和密码后，点击运行。控制台将首先输出 "success"，随后打印出从数据库表中检索到的每一行数据。

图 9：Qt Creator 控制台输出连接成功信息，并遍历显示了 books 表中的 id、title、author 和 price 字段数据。

3. 数据库端验证

为了确保数据的准确性，可以通过 MySQL 图形化管理工具（如 Navicat、MySQL Workbench 或命令行）连接到同一个数据库查看原始数据。对比 Qt 程序的输出与数据库中的实际内容，可以确认 CRUD（增删改查）操作的有效性。

图 10：在 MySQL 数据库管理工具中查看到的 books 表数据，与 Qt 程序输出的结果完全一致，验证了连接和查询逻辑的正确性。

五、远程连接的关键注意事项

实现代码逻辑只是第一步，远程连接 MySQL 往往受到网络环境和服务器配置的影响。如果代码提示 QSqlError 连接超时或拒绝连接，通常需要检查以下配置：

MySQL 用户权限 ：

MySQL 默认的 root 用户通常只允许 localhost 访问。若要远程连接，必须在服务器端授予用户远程访问权限。例如，将用户的 Host 字段从 localhost 改为 %（代表任意 IP）。

SQL 指令示例：
sql 复制代码
```
CREATE USER 'user_name'@'%' IDENTIFIED BY 'passwd';
GRANT ALL PRIVILEGES ON bookstore.* TO 'user_name'@'%';
FLUSH PRIVILEGES;
```
绑定地址 (Bind Address) ：

MySQL 服务器配置文件（my.cnf 或 my.ini）中可能存在 bind-address = 127.0.0.1 的设置，这会强制 MySQL 只监听本地回环接口。需要将其注释掉或改为 bind-address = 0.0.0.0 以监听所有网络接口。
防火墙设置 ：

服务器所在的操作系统防火墙，以及云服务器（如阿里云、AWS）的安全组规则，必须放行 3306 端口的入站流量。

六、总结

通过在 Qt 6.7.3 环境下手动部署 qsqlmysql 驱动及相关依赖库，可以解决 Qt 6 默认缺失 MySQL 驱动的问题。整个过程涵盖了从 GitHub 获取特定版本的预编译驱动，到正确放置 plugins/sqldrivers 和 bin 目录下的动态链接库，再到编写 C++ 代码实现数据库连接与查询的全流程。

掌握这一配置流程，不仅解决了单一的连接问题，也加深了对 Qt 插件加载机制和动态链接库依赖关系的理解。在实际开发中，建议始终检查 lastError() 的返回值，以便在出现网络波动或配置错误时能够快速定位问题根源。通过合理的配置与代码实现，Qt 能够与 MySQL 构建出高效、稳定的数据驱动型应用程序。