Qt 5.15.2编译MySQL驱动完整指南：解决QMYSQL driver not loaded错误

1. 项目概述与核心痛点

最近在折腾一个用Qt开发的数据管理桌面应用，后端数据库选型毫无悬念地定了MySQL。本以为在Qt Creator里配一下数据库连接字符串就能轻松搞定，结果在Qt 5.15.2这个版本上，直接给我来了个下马威：QSqlDatabase: QMYSQL driver not loaded。这个错误对于刚接触Qt数据库编程的朋友来说，简直是当头一棒。问题的根源在于，Qt官方发布的二进制安装包，无论是离线安装器还是在线安装工具，默认都没有包含MySQL的驱动插件（qsqlmysql.dll或qsqlmysql.so）。这背后有许可证兼容性、二进制依赖等复杂原因。所以，想要在Qt 5.15.2中使用MySQL，我们必须自己动手，从Qt的源代码中编译出这个关键的驱动插件。这个过程涉及到Qt源码、MySQL客户端库、正确的编译环境配置等一系列环节，任何一个步骤出错都会导致编译失败。网上教程虽多，但要么环境对不上，要么步骤缺失关键细节，踩坑无数后，我决定把这次从零开始成功编译Qt 5.15.2 MySQL驱动的完整过程、原理和避坑指南系统地记录下来。

2. 环境准备与工具链解析

编译数据库驱动不是简单的make && make install，它依赖于一个完整且版本匹配的工具链。这里的环境准备是成功的第一步，也是最容易出错的一步。

2.1 核心组件版本锁定与获取

版本匹配是重中之重，不匹配的版本组合几乎必然导致编译失败或运行时崩溃。

1. Qt 5.15.2 源代码：这是我们的基础。绝对不能使用Qt安装目录下的include和lib文件夹，那只是二进制运行时库。我们必须获取完整的Qt源码。

   • 获取方式：前往Qt官方存档网站（例如 archive.qt.io），找到Qt 5.15.2的“single”打包的源代码压缩包（如qt-everywhere-src-5.15.2.tar.xz）。这是最推荐的方式，包含了所有模块。
   • 为什么不用Git？虽然Qt项目也在GitHub上，但对于特定版本（尤其是5.15系列，已进入仅限商业授权的LTS阶段），从官方存档获取源码包更直接、版本更清晰。

2. MySQL Connector/C 库：Qt的MySQL驱动本质上是一个“胶水”层，它调用MySQL官方的C语言客户端库（libmysql.dll或libmysqlclient.so）来实现所有数据库操作。因此，我们必须先安装这个库。

   • 版本选择：建议选择MySQL 5.7或8.0系列对应的Connector/C。对于Qt 5.15.2，我实测MySQL 8.0.33的Connector/C 8.0可以正常工作。尽量避免使用太老或太新的预览版。
   • 获取方式：从MySQL官网下载对应你操作系统的Connector/C安装包或压缩包。Windows下推荐下载ZIP Archive版本（如mysql-connector-c-8.0.33-winx64.zip），解压即用，干净无干扰。Linux系统通常可以通过包管理器安装（如sudo apt install libmysqlclient-dev）。

3. 编译工具链：

   • Windows：必须使用MSVC编译器，而不是MinGW。这是因为MySQL官方提供的Windows版libmysql.dll是使用MSVC编译的，与MinGW的ABI不兼容。你需要安装Visual Studio 2017或2019，并确保“Desktop development with C++”工作负载被选中。编译时将使用其附带的nmake命令和MSVC编译器环境。
   • Linux/macOS：使用系统自带的GCC/Clang即可。确保已安装make和g++等基础开发工具。

2.2 目录结构规划

清晰的目录结构能避免路径混乱。建议按如下方式组织：

D:\Dev\QtBuild\ ├── qt-src\ # 解压Qt源码到此，路径不要有中文和空格 │ └── qtbase\src\plugins\sqldrivers\mysql # 这是我们主要工作的目录 ├── mysql-connector\ │ ├── include\ # MySQL头文件 │ └── lib\ # MySQL库文件 (libmysql.lib, libmysql.dll) └── build-output\ # 可选，存放编译生成的驱动文件

注意：很多教程让你编译整个Qt源码，那太耗时了。Qt的模块化做得很好，我们完全可以只编译qtbase模块下的sqldrivers插件，这正是高效的做法。

3. 编译原理与配置详解

理解了“为什么”要这么做，才能灵活应对各种环境差异。

3.1 Qt插件编译机制

Qt的数据库驱动是以插件（Plugin）形式存在的。插件是动态库，在运行时被应用程序按需加载。编译插件需要三样东西：

1. 插件的源代码：位于qtbase/src/plugins/sqldrivers/mysql/。
2. Qt的构建系统（qmake）：它根据.pro项目文件生成平台特定的Makefile。
3. 目标依赖库：即MySQL的客户端库和头文件。

编译驱动的过程，就是使用Qt的qmake，读取mysql.pro文件，并告知它MySQL库的位置，最终生成一个可以被Qt SQL模块识别的插件动态库。

3.2 关键配置步骤实操

假设你的Qt 5.15.2源码解压路径为D:\Dev\QtBuild\qt-src，MySQL Connector/C解压路径为D:\Dev\QtBuild\mysql-connector。

1. 打开正确的命令行环境（Windows关键步骤）：

   • 在开始菜单中找到“Visual Studio 2019”文件夹，运行“x64 Native Tools Command Prompt for VS 2019”。这将打开一个命令行窗口，其中所有环境变量（如cl,nmake,PATH）都已设置为64位MSVC编译环境。这是编译成功的前提。

2. 进入驱动源码目录：

   cd D:\Dev\QtBuild\qt-src\qtbase\src\plugins\sqldrivers

3. 执行qmake生成Makefile：

   • 这里需要使用你已安装的Qt二进制版本中的qmake，而不是源码里的。假设你的Qt 5.15.2 MSVC安装路径是C:\Qt\5.15.2\msvc2019_64。

   C:\Qt\5.15.2\msvc2019_64\bin\qmake.exe -- MYSQL_INCDIR="D:\Dev\QtBuild\mysql-connector\include" MYSQL_LIBDIR="D:\Dev\QtBuild\mysql-connector\lib"

   • 参数解析：
     • --：这是qmake的分隔符，表示后面的参数是传递给.pro文件内部CONFIG使用的。
     • MYSQL_INCDIR：告诉qmake MySQL头文件的位置。
     • MYSQL_LIBDIR：告诉qmake MySQL库文件的位置。
   • 执行成功标志：命令行没有报错，并在当前目录生成Makefile、Makefile.Debug、Makefile.Release等文件。

4. 执行编译命令：

   nmake

   • 如果你只需要发布版本的驱动，可以运行nmake release。这个过程会编译mysql.pro项目，并在plugins\sqldrivers\目录下生成qsqlmysql.dll和qsqlmysqld.dll（调试版）。

5. Linux/macOS下的对应操作：

   • 环境变量和工具链配置通常更简单。命令类似，但使用make。

   cd /path/to/qt-src/qtbase/src/plugins/sqldrivers /path/to/qt-install-dir/bin/qmake -- MYSQL_INCDIR=/usr/include/mysql MYSQL_LIBDIR=/usr/lib/x86_64-linux-gnu make

   • 在Linux上，使用包管理器安装libmysqlclient-dev后，头文件和库路径通常是标准路径，上述命令可能无需指定MYSQL_INCDIR和MYSQL_LIBDIR，直接qmake && make即可。

4. 编译过程中的典型问题与解决方案

即使步骤正确，你也可能会遇到以下问题。这里记录了我踩过的坑和解决方案。

4.1 错误：Cannot find -lmysql

• 现象：在Linux下执行make时，提示找不到-lmysql。
• 原因：qmake没有正确找到MySQL的客户端库。在Linux下，库文件通常是libmysqlclient.so，而链接器标志是-lmysqlclient，有时简写查找会有问题。
• 解决：
  1. 确认libmysqlclient.so文件确实存在（例如在/usr/lib/x86_64-linux-gnu/下）。
  2. 更精确地指定库路径和库名。可以尝试修改调用qmake的方式：

     /path/to/qmake "LIBS+=-L/usr/lib/x86_64-linux-gnu -lmysqlclient" "INCLUDEPATH+=/usr/include/mysql"

     或者，创建一个简单的mysql_config脚本来提供路径（如果系统没有安装mysql_config）。

4.2 错误：fatal error C1083: Cannot open include file: 'mysql.h'

• 现象：Windows下执行nmake时，编译报错找不到mysql.h。
• 原因：MYSQL_INCDIR参数设置错误，或者路径中包含空格、中文没有用引号括起来。
• 解决：
  1. 检查D:\Dev\QtBuild\mysql-connector\include目录下是否存在mysql.h文件。
  2. 确保qmake命令中路径使用双引号，特别是路径有空格时：

     qmake.exe -- MYSQL_INCDIR=\"D:\Program Files\MySQL\Connector C 8.0\include\" MYSQL_LIBDIR=\"D:\Program Files\MySQL\Connector C 8.0\lib\vs14\"

  3. 使用反斜杠\转义空格也是一种方法，但引号更可靠。

4.3 错误：LNK2019: unresolved external symbol _mysql_xxx**

• 现象：Windows下链接阶段报错，提示一堆mysql_开头的函数无法解析。
• 原因：这是最经典的问题。MYSQL_LIBDIR指向的目录里没有找到正确的.lib导入库文件。MySQL Connector/C的ZIP包中，lib文件夹里可能有libmysql.lib、libmysql.dll，也可能只有mysqlclient.lib。Qt的.pro文件默认寻找libmysql.lib。
• 解决：
  1. 打开mysql-connector\lib文件夹，确认库文件名。
  2. 如果文件是mysqlclient.lib，你有两个选择：
     • 方案A（推荐）：将其复制一份并重命名为libmysql.lib。
     • 方案B：修改Qt源码中的mysql.pro文件。找到LIBS += $$QMAKE_LIBS_MYSQL这一行，在其前面手动指定库文件：

       win32: LIBS += -L"$$MYSQL_LIBDIR" -lmysqlclient

       然后重新执行qmake和nmake。
  3. 确保你运行的命令行是x64 Native Tools Command Prompt，并且你下载的MySQL Connector/C也是64位的。32位和64位的库不能混用。

4.4 编译成功但运行时驱动未加载

• 现象：将编译好的qsqlmysql.dll放到了Qt安装目录\plugins\sqldrivers\下，程序运行时依然提示驱动未加载。
• 原因：
  1. 依赖缺失：qsqlmysql.dll依赖于libmysql.dll。你必须将MySQL Connector/C的bin目录（或lib目录中）的libmysql.dll复制到你的应用程序可执行文件同级目录，或者放到系统PATH包含的目录中。
  2. 版本不匹配：你的应用程序是使用MinGW编译的，却使用了MSVC编译的Qt插件和MySQL库，或者反之。必须保证三者（你的App、Qt插件、MySQL库）使用相同的编译器运行时（MSVC版本）和架构（x64/x86）。
  3. 插件路径问题：Qt应用程序默认在几个固定路径搜索插件。你可以通过调用QCoreApplication::addLibraryPath()来添加自定义插件路径，或者在发布时确保插件在applicationDirPath()/plugins/sqldrivers/下。
• 诊断方法：在调用QCoreApplication a(argc, argv);之后，立即添加以下代码，查看驱动列表和插件加载错误：

  qDebug() << "Available drivers:" << QSqlDatabase::drivers(); qDebug() << "Library paths:" << QCoreApplication::libraryPaths();

  如果qsqlmysql不在驱动列表中，说明插件根本未被加载。检查插件文件是否完整、依赖是否满足。

5. 驱动部署与项目集成实战

编译出.dll或.so文件只是成功了一半，如何将它集成到你的开发和部署流程中，才是最终目标。

5.1 开发环境配置

1. 放置驱动插件：

   • 将编译生成的qsqlmysql.dll（Release版）复制到你的Qt安装目录下的插件文件夹：C:\Qt\5.15.2\msvc2019_64\plugins\sqldrivers\。
   • 同时，将libmysql.dll也复制到C:\Qt\5.15.2\msvc2019_64\bin\目录下。这样，Qt Creator在运行和调试你的项目时就能找到它们。

2. 在Qt Creator中验证：创建一个新的Qt Console Application或Widgets Application，在main.cpp或某个按钮事件中添加测试代码：

   #include <QCoreApplication> #include <QSqlDatabase> #include <QDebug> #include <QSqlError> int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); qDebug() << "Available drivers:" << QSqlDatabase::drivers(); QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL"); db.setHostName("localhost"); db.setPort(3306); db.setDatabaseName("testdb"); db.setUserName("root"); db.setPassword("yourpassword"); if (!db.open()) { qDebug() << "Failed to connect:" << db.lastError().text(); return -1; } else { qDebug() << "Connected successfully!"; db.close(); } return a.exec(); }

   运行程序，如果输出中包含QMYSQL并且连接成功，则开发环境配置完成。

5.2 应用程序发布部署

发布用Qt编写的应用程序时，你需要将运行时依赖一起打包。

1. 收集依赖文件：为你的发布版可执行文件准备一个文件夹（例如MyAppRelease），里面需要包含：

   • MyApp.exe（你的程序）
   • Qt5Core.dll,Qt5Gui.dll,Qt5Widgets.dll,Qt5Sql.dll等你的程序用到的Qt核心库（位于Qt安装目录\bin）。
   • platforms\qwindows.dll等必要的Qt插件（使用windeployqt.exe工具可以自动完成这部分，命令：windeployqt MyApp.exe）。
   • plugins\sqldrivers\qsqlmysql.dll（关键：必须保持这个目录结构）。
   • libmysql.dll（放在与MyApp.exe同级目录，或者与qsqlmysql.dll同目录，建议放同级目录更保险）。

2. 使用windeployqt自动化：windeployqt是Qt自带的部署工具，但它不会自动打包你自己编译的第三方插件（如MySQL驱动）。

   • 先运行windeployqt MyApp.exe打包基本的Qt依赖。
   • 然后手动创建plugins\sqldrivers目录，并将qsqlmysql.dll和libmysql.dll复制进去（或者将libmysql.dll放到根目录）。
   • 一个更稳妥的脚本思路是，在windeployqt之后，再手动复制这些文件。

3. Linux/macOS部署：原理类似。需要将编译好的libqsqlmysql.so插件放入指定位置（如应用内的plugins/sqldrivers/），并确保系统动态链接器能找到libmysqlclient.so。通常可以通过设置LD_LIBRARY_PATH环境变量或将库安装到系统路径来解决。

6. 高级话题：源码编译与静态链接

对于需要极致控制或发布单一可执行文件的场景，你可能需要静态链接。

6.1 编译静态版本驱动

静态编译意味着将数据库驱动代码直接链接进你的可执行文件，而不是作为一个单独的插件.dll。

1. 配置Qt的静态编译：这需要在编译整个Qt源码时，使用-static参数。这是一个非常耗时的过程（数小时）。命令大致如下：

   configure.bat -static -static-runtime -prefix "C:\Qt\5.15.2-static" -opensource -confirm-license -opengl desktop -sql-mysql -plugin-sql-mysql -I "D:\mysql-connector\include" -L "D:\mysql-connector\lib"

   注意-sql-mysql和-plugin-sql-mysql参数，它们会促使MySQL驱动被编译并静态链接到Qt的SQL模块中。

2. 在项目中使用静态Qt：在你的项目.pro文件中，需要明确链接静态库，并且因为驱动已内建，你不再需要QTPLUGIN += qsqlmysql这样的语句，直接使用QSqlDatabase::addDatabase("QMYSQL")即可。

6.2 处理静态链接的依赖

即使静态链接了Qt和其MySQL驱动，你的程序仍然动态依赖于libmysql.dll。要实现真正的“单文件”，必须将MySQL客户端库也静态链接进来。但这非常复杂，因为MySQL Connector/C的官方发行版通常不提供静态库（libmysql.lib是动态库的导入库）。你需要自己用源码编译出静态的MySQL客户端库，这涉及到另一个庞大的编译工程，通常不推荐普通项目这样做。更务实的做法是，将libmysql.dll作为外部依赖随你的程序一起分发。

折腾完这一整套，最大的体会是：在Windows平台用Qt连接MySQL，环境配置的复杂度远高于数据库操作本身。核心诀窍就是保持一致性：编译器（MSVC）、架构（x64）、运行时库版本必须完全匹配。一旦编译通过并成功运行一次，之后的项目就会非常顺畅。建议将编译好的qsqlmysql.dll和对应的libmysql.dll妥善备份，它们就是你在Qt世界里通往MySQL数据库的钥匙。