Ubuntu下Qt连接MySQL提示QMYSQL driver not loaded该如何解决？

在 Ubuntu 系统下使用 Qt 框架开发应用程序并尝试连接 MySQL 数据库时，开发者经常会遇到棘手的报错问题，这类问题通常表现为程序运行时输出 “Driver not loaded” 或 “QMYSQL driver not loaded” 等错误信息，导致数据库连接失败，本文旨在深入剖析这一问题的根源，并提供一套系统化、结构清晰的解决方案，帮助开发者顺利搭建 Qt 与 MySQL 的通信桥梁。

根本原因分析：为何驱动无法加载？

Qt 的数据库功能基于其强大的 SQL 模块，该模块采用了一种分层架构，上层提供统一的数据库访问接口（如 QSqlDatabase、QSqlQuery），而下层则依赖于具体的数据库驱动插件来与不同类型的数据库进行通信，对于 MySQL 而言，这个关键的驱动插件就是 QMYSQL，其动态链接库文件通常名为 libqsqlmysql.so。

问题的核心在于,Qt 官方提供的开源版本或通过标准包管理器（如 apt）安装的 Qt 库，通常并不默认包含 QMYSQL 驱动，这主要是出于以下几个原因：

1. 依赖复杂性：编译 QMYSQL 驱动需要 MySQL 的客户端开发库（libmysqlclient-dev），强制包含该驱动会使 Qt 的安装过程变得复杂，并引入额外的外部依赖。
2. 版本兼容性：MySQL 客户端库版本众多，预编译的驱动可能无法与用户系统上安装的 MySQL 服务器版本完美兼容，从而引发潜在的运行时错误。
3. 安装体积：为了保持 Qt 基础安装包的轻量化，非核心功能（如特定数据库驱动）通常作为可选组件，需要用户按需编译和安装。

当你的 Qt 应用程序尝试建立 MySQL 连接时，Qt 的插件系统会在指定的路径下搜索 libqsqlmysql.so 文件，如果找不到，或者找到的文件因依赖缺失而无法加载，就会抛出 “Driver not loaded” 错误。

解决方案：从编译到配置的全流程指南

解决此问题的根本方法就是亲手编译 QMYSQL 驱动，并将其安装到 Qt 能够识别的插件目录中，以下是详细的操作步骤。

第一步：准备必要的开发环境和依赖

在开始编译之前,请确保你的系统已经安装了所有必要的工具和库，打开终端，执行以下命令：

# 更新包列表
sudo apt update
# 安装编译工具链、Qt5 开发库和 MySQL 客户端开发库
sudo apt install build-essential qtbase5-dev qt5-qmake libmysqlclient-dev

• build-essential: 提供了 C/C++ 编译器（如 gcc、g++）和 make 等基础开发工具。
• qtbase5-dev 和 qt5-qmake: 包含了 Qt5 的核心开发头文件、库以及 qmake 构建工具，这是编译 Qt 插件的前提。
• libmysqlclient-dev: 提供了编译 MySQL 驱动所需的 C API 头文件和链接库。

第二步：定位 Qt 源码中的 MySQL 驱动项目

Qt 的所有插件源码都包含在 Qt 的源码包中，如果你是通过 apt 安装的 Qt，这些源码通常位于系统的 /usr/src/ 目录下，我们需要找到 mysql 驱动的源码目录。

# 查找 qtbase 的源码目录，通常包含 sql 驱动
find /usr/src -name "mysql.pro" -type f 2>/dev/null

这个命令会输出类似 /usr/src/qtbase5-opensource-src-5.12.8/src/plugins/sqldrivers/mysql/mysql.pro 的路径，请记录下这个路径，然后进入该目录的上一级，即 sqldrivers/mysql 目录。

# 根据上一步找到的路径，进入编译目录
# 请将下面的路径替换为你系统中实际找到的路径
cd /usr/src/qtbase5-opensource-src-5.12.8/src/plugins/sqldrivers/mysql

第三步：使用 qmake 生成 Makefile 并编译

在正确的目录下,我们使用 qmake 来生成 Makefile，然后使用 make 命令进行编译。

# 生成 Makefile
# qmake 会自动检测系统的 MySQL 安装路径
qmake
# 开始编译
make

编译过程如果没有任何错误,你会在当前目录或其子目录（如 .obj 或 ../../plugins/sqldrivers/）下找到新生成的 libqsqlmysql.so 文件。

第四步：安装编译好的驱动插件

最后一步,将编译好的动态库文件复制到 Qt 的插件目录中，这个目录是 Qt 运行时搜索驱动的标准位置。

# 查找 Qt5 的 sqldrivers 插件目录
qmake -query QT_INSTALL_PLUGINS

该命令会输出一个路径,/usr/lib/x86_64-linux-gnu/qt5/plugins。QMYSQL 驱动需要被放置在这个路径下的 sqldrivers 子目录中。

# 将编译好的驱动文件复制到目标目录
# 请将源文件路径和目标路径替换为你自己的实际路径
sudo cp /path/to/your/compiled/libqsqlmysql.so /usr/lib/x86_64-linux-gnu/qt5/plugins/sqldrivers/

至此,驱动安装完成，你可以通过运行一个简单的 Qt 程序来验证驱动是否可用。

验证与常见问题排查

为了确认驱动是否成功加载,可以编写一个简单的测试程序，以下是一个 C++ 代码片段，用于列出所有可用的数据库驱动：

#include <QCoreApplication>
#include <QtSql>
#include <QDebug>
int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);
    qDebug() << "Available drivers:";
    QStringList drivers = QSqlDatabase::drivers();
    foreach(QString driver, drivers) {
        qDebug() << "-" << driver;
    }
    // 检查 "QMYSQL" 是否在列表中
    if (drivers.contains("QMYSQL")) {
        qDebug() << "QMYSQL driver is successfully loaded!";
    } else {
        qDebug() << "QMYSQL driver is NOT loaded.";
    }
    return 0;
}

编译并运行此程序,如果输出中包含 QMYSQL，则说明安装成功。

常见问题排查：

• 问题：编译成功但运行时仍报错。

  

  • 原因1：依赖库缺失。 使用 ldd 命令检查 libqsqlmysql.so 的依赖项是否都能找到。

    ldd /usr/lib/x86_64-linux-gnu/qt5/plugins/sqldrivers/libqsqlmysql.so

    如果发现 libmysqlclient.so => not found，说明系统找不到 MySQL 客户端库，通常通过安装 libmysqlclient21 (或对应版本) 即可解决。

  • 原因2：Qt 版本不匹配。 确保你编译驱动时使用的 Qt 开发库版本与运行应用程序时使用的 Qt 库版本完全一致。

• 问题：使用包管理器安装的替代方案。
  对于不想手动编译的用户，可以尝试直接安装预编译的驱动包，在 Ubuntu/Debian 系统上，可以尝试：

  sudo apt install libqt5sql5-mysql

  这种方法简单快捷,但缺点是驱动的版本可能比较旧，且可能不适用于所有自定义的 Qt 安装场景。

方法对比	手动编译	包管理器安装
优点	版本匹配度高，灵活可控，兼容性好	简单、快速，无需编译环境
缺点	过程繁琐，需要安装编译工具和依赖	版本可能滞后，可能不匹配非标准Qt安装
适用场景	自定义Qt版本、需要最新驱动、解决复杂依赖	标准Qt安装、追求快速部署、对版本要求不高

相关问答FAQs

问题1：我按照步骤编译了驱动，为什么运行时还是报 “Driver not loaded” 错误？
解答： 这个问题通常由三个常见原因导致，请确认你将 libqsqlmysql.so 文件复制到了正确的插件目录，你可以使用 qmake -query QT_INSTALL_PLUGINS 命令来获取确切的路径，使用 ldd 命令检查该驱动文件的依赖库是否都已满足，特别是 libmysqlclient.so，如果缺失，请安装对应的库包（如 libmysqlclient21），确保编译驱动时使用的 Qt 版本与你运行应用程序时链接的 Qt 库版本完全一致，版本不匹配会导致插件加载失败。

问题2：除了 MySQL，Qt 还支持哪些其他数据库？如何连接？
解答： Qt 的 SQL 模块设计得非常灵活，支持多种主流数据库，除了 MySQL (QMYSQL)，还内置了对 SQLite (QSQLITE)、PostgreSQL (QPSQL) 的支持，并提供了通过 ODBC (QODBC) 连接各种数据库的能力，连接方式与 MySQL 非常相似，主要区别在于调用 QSqlDatabase::addDatabase() 时传入的驱动名称不同，以及连接字符串（主机名、端口、数据库名、用户名、密码等）的格式，连接 SQLite 只需指定数据库文件路径，因为它是一个文件型数据库，无需服务器。