Ubuntu 24.04下Qt 5.15.0 MySQL驱动缺失修复指南

每次在Linux下看到QSqlDatabase: QMYSQL driver not loaded这行报错心里都咯噔一下。这次是在Ubuntu 24.04上升级开发环境装好Qt 5.15.0后打开数据库连接向导驱动列表里只有QSQLITE、QODBC、QPSQL唯独少了MySQL。程序一跑起来直接抛QSqlDatabase: available drivers: QSQLITE QODBC QPSQL QSQLITE2后面跟着那句要命的driver not loaded。这个问题的成因很简单Qt 5.15.0在Linux上默认不会编译MySQL数据库驱动插件不管是官方安装包、apt源还是源码编译绝大部分人都要手动处理一次。文章会把这次在Ubuntu 24.04上的完整解决过程拆开讲覆盖三种安装方式以及装好之后连MySQL 8.0的认证兼容坑你可以对着自己的实际情况直接抄作业。1. 先确认问题你的Qt到底缺了什么1.1 三种典型报错分别说明什么很多人一看到driver not loaded就以为是MySQL没装好其实不是。Qt的SQL驱动是插件机制运行时按需加载sqldrivers目录下的动态库比如libqsqlmysql.so。这个驱动文件不存在、存在但依赖库缺失、或者与Qt版本不匹配都会表现为驱动未加载。我这次遇到的是最典型的一种程序输出QSqlDatabase: available drivers: QSQLITE QODBC QPSQL QSQLITE2 QSqlDatabase: QMYSQL driver not loadedavailable drivers里没有QMYSQL说明编译Qt的时候就没生成MySQL插件。如果你的诊断栏输出重复两遍Driver not loaded那多半是插件文件在但动态库依赖有问题比如libmysqlclient.so找不到。还有一种情况是编译后驱动列表里有QMYSQL但连接时弹Unable to execute statement这通常不是驱动缺失而是认证协议或字符集的问题后面会专门讲。总之先定位问题类型再去动手能省下大量盲目重装Qt的时间。1.2 一条命令看清当前已装驱动在终端里用Qt自带的qmake可以直接拿到插件目录不用写任何测试程序# 系统Qtapt安装 qmake -query QT_INSTALL_PLUGINS # 输出类似/usr/lib/x86_64-linux-gnu/qt5/plugins # 官方Qt安装包 /opt/Qt/5.15.0/gcc_64/bin/qmake -query QT_INSTALL_PLUGINS # 输出类似/opt/Qt/5.15.0/gcc_64/plugins拿到插件目录后列一下sqldrivers子目录ls /opt/Qt/5.15.0/gcc_64/plugins/sqldrivers/正常只有libqsqlite.so、libqodbc.so、libqpsql.so这些看不到libqsqlmysql.so就实锤了MySQL驱动压根没编译。这个命令在排查中非常高频我几乎每次处理Qt数据库问题都会先用它比打开Qt Creator的向导快得多。1.3 为什么Ubuntu 24.04下Qt默认不带MySQL驱动Linux发行版里Qt对MySQL的支持通常是作为独立包分发的。Ubuntu的libqt5sql5-mysql单独装Qt官方Linux安装包也不内置MySQL驱动原因有两方面一是MySQL客户端库存在GPL/LGPL协议的兼容性考量二进制发行往往选择不捆绑二是不同发行版的libmysqlclient版本差异太大预编译插件很容易因为依赖库版本对不上而崩溃。所以在Ubuntu 24.04上无论你从哪个渠道拿到Qt 5.15.0都要把补MySQL驱动当成一个常规安装步骤来规划。想省事看第2节的apt方案想稳妥看第3节的源码编译方案如果你是从源码构建整个Qt直接看第4节。2. 最快方案apt直接装驱动插件5分钟收工2.1 动手前先确认Qt来源决定能不能用aptapt方案只对系统Qt有效也就是通过/usr/bin/qmake查到路径是/usr/lib/x86_64-linux-gnu/qt5的情况。Ubuntu 24.04自带的Qt Base是5.15.13和你的Qt 5.15.0同属5.15系列插件ABI兼容性很好。如果你用的是官方安装包装好的插件可以手动拷贝过去也能正常工作。但如果你是自己用源码编译的Qt比如装到了/usr/local/Qt-5.15.0那建议跳过这一节直接看第3节因为系统Qt插件不会考虑你自定义编译路径。判断方法很简单which qmake qmake -v输出/usr/bin/qmake加上类似Qt version 5.15.13的版本号就是系统Qt。输出/opt/Qt/5.15.0/gcc_64/bin/qmake这类路径就是官方安装包。2.2 安装libqt5sql5-mysqlUbuntu仓库早就把MySQL驱动做成了独立包一条命令解决sudo apt update sudo apt install libqt5sql5-mysql装完检查插件目录ls /usr/lib/x86_64-linux-gnu/qt5/plugins/sqldrivers/看到libqsqlmysql.so驱动就位了。如果你用的是系统Qt到这里已经结束重新编译运行程序available drivers里就会多出QMYSQL。这里插一句经验Ubuntu的Qt包名很容易混淆libqt5sql5是QtSQL模块本体libqt5sql5-mysql才是MySQL插件少装后面这个驱动永远出不来的。如果系统里原本装了libqt5sql5-tds、libqt5sql5-odbc那只是一堆其他数据库插件跟MySQL没半点关系。2.3 官方安装包用户把插件拷进Qt目录官方Qt安装包的插件目录路径通常是/opt/Qt/5.15.0/gcc_64/plugins/sqldrivers或~/Qt/5.15.0/gcc_64/plugins/sqldrivers。把apt装好的插件复制过去sudo cp /usr/lib/x86_64-linux-gnu/qt5/plugins/sqldrivers/libqsqlmysql.so /opt/Qt/5.15.0/gcc_64/plugins/sqldrivers/复制后建议用ldd验证一下依赖是否能全部找到ldd /opt/Qt/5.15.0/gcc_64/plugins/sqldrivers/libqsqlmysql.so只要没有not found的项就能跑起来。这里有个小坑官方Qt 5.15.0的系统库比较老而Ubuntu 24.04的libmysqlclient是MySQL 8.0系依赖库通常没问题但如果系统里同时装了MariaDB的客户端库可能会把libmariadb.so错链过来。遇到这种情况优先检查/usr/lib/x86_64-linux-gnu/libmysqlclient.so是否存在确认后再重新编译驱动见第3节。3. 通用方案用qmake从源码编译MySQL驱动3.1 编译前需要装齐的依赖apt方案解决不了自定义路径的Qt就得手动编译驱动插件。这个过程不复杂核心依赖只有三样编译器、MySQL客户端头文件、Qt的qmake工具。sudo apt update sudo apt install build-essential libmysqlclient-dev libssl-devlibmysqlclient-dev提供编译需要的mysql.h头文件和libmysqlclient.so链接库。装完后确认路径不同版本位置有差异ls /usr/include/mysql/mysql.h ls /usr/lib/x86_64-linux-gnu/libmysqlclient.soUbuntu 24.04上这两个路径是标准位置。如果头文件不在/usr/include/mysql后面qmake参数里的INCLUDEPATH要对应改一下。另外libssl-dev不是必需但Ubuntu上缺了它MySQL客户端库的某些插件链接会出问题顺手装上能少踩坑。3.2 拿到与Qt 5.15.0对应的qtbase源码Qt的SQL驱动插件源码在qtbase模块里。这里有个关键点插件源码版本不需要和运行时的Qt版本完全一致5.15.x系列内部接口稳定但为了减少诡异问题我建议直接用5.15.0的源码。下载地址在Qt官方archivewget https://download.qt.io/archive/qt/5.15/5.15.0/submodules/qtbase-everywhere-src-5.15.0.tar.xz tar -xf qtbase-everywhere-src-5.15.0.tar.xz cd qtbase-everywhere-src-5.15.0/src/plugins/sqldrivers如果你下载慢可以换镜像站文件名不变。这一节的目标只编译mysql子工程不需要整个qtbase构建所以不用等太久。3.3 编译mysql插件的三条命令进入sqldrivers/mysql目录用Qt自己的qmake生成Makefile关键是通过命令行追加两个参数MySQL头文件目录和客户端库。cd mysql /opt/Qt/5.15.0/gcc_64/bin/qmake INCLUDEPATH/usr/include/mysql LIBS-L/usr/lib/x86_64-linux-gnu -lmysqlclient mysql.pro make -j$(nproc)如果qmake命令不在PATH里就写完整路径比如/opt/Qt/5.15.0/gcc_64/bin/qmake。针对自定义源码编译的Qt找到对应的qmake绝对路径填进去即可。编译完成后插件文件会生成到mysql子目录或上层构建目录用find搜一下最可靠find . -name libqsqlmysql.so我实测的输出路径通常是../../../../plugins/sqldrivers/libqsqlmysql.so这种不同环境略有差异直接拿find结果来用。3.4 安装到正确目录并验证结果拷贝插件到Qt插件目录sudo cp $(find . -name libqsqlmysql.so) /opt/Qt/5.15.0/gcc_64/plugins/sqldrivers/这里的路径同样是qmake -query QT_INSTALL_PLUGINS拿到的结果。拷贝完成后验证一下ls /opt/Qt/5.15.0/gcc_64/plugins/sqldrivers/ ldd /opt/Qt/5.15.0/gcc_64/plugins/sqldrivers/libqsqlmysql.so只要ldd输出里没有not found就可以启动一个最小的Qt程序打印QSqlDatabase::drivers()这次QMYSQL应该出现在列表中。3.5 编译参数背后的原理很多人直接抄命令但不知道为什么导致换台机器就编译失败。INCLUDEPATH/usr/include/mysql是告诉编译器和Qt的make系统MySQL头文件在哪个目录。这个目录下能找到mysql.h而Qt的mysql插件源码里会#include mysql.h。头文件路径不对编译会直接报mysql.h: No such file or directory。LIBS-L/usr/lib/x86_64-linux-gnu -lmysqlclient是链接参数的补全。-L指定动态库搜索路径-lmysqlclient让链接器去找libmysqlclient.so。为什么不直接写路径因为-l是标准链接方式编译器会自动补全lib前缀和.so后缀还能和Qt生成的Makefile里原有参数更好兼容。理解这两个参数后遇到非标准安装路径就知道怎么改了。比如MySQL客户端装到了/usr/local/mysql就要写成INCLUDEPATH/usr/local/mysql/include和LIBS-L/usr/local/mysql/lib -lmysqlclient。这就是源码编译方案比apt方案灵活的地方。4. 进阶方案源码编译整个Qt时把MySQL带上4.1 configure参数怎么填如果你本来就是从源码编译Qt 5.15.0那就不要在事后补丁了直接在configure阶段就把MySQL驱动打开一步到位。进入qtbase源码根目录后执行./configure -opensource -confirm-license -release -shared \ -prefix /usr/local/Qt-5.15.0 \ -sql-mysql \ -mysql_config /usr/bin/mysql_config关键参数是-sql-mysql它让configure去检测MySQL客户端库。-mysql_config指定了MySQL的配置脚本路径这个脚本是安装libmysqlclient-dev时生成的里面包含了头文件、库路径、链接标志等全部信息Qt用它来自动设置编译参数。configure过程中重点关注输出里这一段MySQL ......... yes看到yes就说明驱动被正确识别了。如果显示no后面make出来的Qt依然没有MySQL插件排查方向看4.2节。4.2 最容易踩的configure坑第一个坑是mysql_config路径不对。Ubuntu 24.04上它可能在/usr/bin/mysql_config也可能在/usr/local/bin/mysql_config。实在找不到用which mysql_config定位或者用find /usr -name mysql_config。第二个坑是只加了-sql-mysql但没装libmysqlclient-dev。configure检测时会报找不到mysql.h直接跳过去你甚至不会发现哪里出错。所以configure之前务必先装好依赖。第三个坑是configure缓存。源码目录如果在之前已经执行过一次configure再次执行时新的参数可能不生效。稳妥做法是清掉缓存文件make distclean或者用git clean -fdx源码是git克隆时然后再跑configure。很多人在这一步被坑改了半天参数实际编译还是旧配置。整个Qt 5.15.0从源码构建耗时很长所以我更推荐日常开发用第3节的方法单独编译插件只有当你需要完整定制Qt特性时才值得付出整个configure加make的时间成本。5. 装上驱动之后连接与兼容性细节5.1 最基础的QMYSQL连接代码驱动装好只是第一步连接MySQL时还有一个容易栽跟头的点数据库连接选项。下面这段代码是我测试驱动是否生效时最常用的#include QSqlDatabase #include QSqlError #include QDebug int main() { QSqlDatabase db QSqlDatabase::addDatabase(QMYSQL); db.setHostName(127.0.0.1); db.setPort(3306); db.setDatabaseName(test); db.setUserName(root); db.setPassword(你的密码); if (!db.open()) { qDebug() 连接失败: db.lastError().text(); return 1; } qDebug() 连接成功; return 0; }编译时别忘记链接QtSql模块g -o testdb testdb.cpp -I/usr/include/x86_64-linux-gnu/qt5 -I/usr/include/x86_64-linux-gnu/qt5/QtSql -I/usr/include/x86_64-linux-gnu/qt5/QtCore -lQt5Sql -lQt5Core这个最小程序能跑通说明驱动和连接参数都没问题。后续再往工程里加业务逻辑。5.2 MySQL 8.0认证插件与Qt 5.15.0的兼容问题MySQL 8.0默认的认证插件是caching_sha2_password而Qt 5.15.0时代的MySQL驱动在早期libmysqlclient版本上对这个认证协议支持得并不好。如果你连接时遇到QMYSQL: Unable to execute statement Authentication plugin caching_sha2_password cannot be loaded别慌这在Ubuntu 24.04 Qt 5.15.0 MySQL 8.0的组合里很典型。处理思路有三个第一升级系统的libmysqlclient到MySQL 8.0配套版本。Ubuntu 24.04默认仓库的libmysqlclient-dev已经对应MySQL 8.0通常能识别caching_sha2_password所以遇到这个报错概率反而比旧系统低。第二在MySQL服务器端把用户认证插件改回mysql_native_password这是最通用的临时绕过方案ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;第三连接时开启SSL模式。caching_sha2_password在加密链路下能正常完成认证交换Qt侧可以这样设置db.setConnectOptions(MYSQL_OPT_SSL_MODESSL_PREFERRED);如果MySQL服务端没配SSL证书SSL_PREFERRED会降级不强制校验。这个选项在不同Qt版本中行为略有差异建议实际测试后再用到生产环境。5.3 常见连接失败与排查速查表我在Ubuntu 24.04上反复测试后整理了一份高频问题对照表遇到问题可以先对照定位现象可能原因解决办法驱动列表无QMYSQL驱动插件未编译第2节或第3节方案安装Driver not loaded重复出现插件存在但依赖库缺失ldd检查安装libmysqlclient21Unknown database test数据库名不存在先建库或改连接库名Access denied for user root...密码错误或权限不足重设MySQL用户密码并授权Cant connect to local MySQL server through socket /tmp/mysql.sock默认Unix socket路径不符改用TCP连接setHostName(127.0.0.1)中文乱码charset未设置连接后执行db.exec(SET NAMES utf8mb4)其中socket问题在Ubuntu 24.04尤其要留意新版MySQL默认socket路径可能是/run/mysqld/mysqld.sockQt默认找/tmp/mysql.sock经常对不上。最简单的办法是强制走TCP填localhost或127.0.0.1都能规避。6. 我实际踩过坑后想说的几句经验这次处理Ubuntu 24.04 Qt 5.15.0缺失MySQL驱动我前后折腾了两天最后发现核心套路就那么几条先用qmake -query QT_INSTALL_PLUGINS定位插件目录再列sqldrivers确认驱动是否存在如果存在但不加载立刻上ldd看依赖不要急着重装Qt如果列表里压根没有就按Qt来源选apt或源码编译。我个人最常用的其实是第3节的源码编译方案虽然比apt多几条命令但它不挑Qt来源官方安装包、自定义编译目录、甚至嵌入式交叉编译环境都能用。把INCLUDEPATH和LIBS两个参数理解透之后遇到换一个MySQL客户端版本、换一套Qt目录都能十分钟内解决。还有个小建议编译出来的libqsqlmysql.so体积不大编译成功后拷贝到项目工程的3rdparty目录里备份一份。以后换电脑、换CI机器直接拷过去就能解决问题省得每次都要重新下载源码编译。这个习惯让我后面在另一台Ubuntu 24.04新机器上不到两分钟就完成了驱动部署。