很多刚开始用Qt连MySQL的朋友第一反应都是“不就是装个数据库、加个驱动、写两行代码嘛”真到自己上手才发现光一个配置环节就能卡住半天。有的报QMYSQL driver not loaded有的报SSL connection error还有的在Linux下折腾半天连/tmp/mysql.sock都找不到。这篇教程不讲虚的就围绕“Qt MySQL”这条线先把最基础也最容易出问题的“配置MySQL”这一步彻底捋清楚。学完之后你能把本地的MySQL服务跑起来让Qt项目正确加载驱动并稳稳连上数据库。适合刚接触Qt开发、还没成功跑通数据库连接的初学者也适合被各种连接报错折腾到头疼的老哥参考。1. 整体思路先理清Qt连MySQL要过哪三关Qt开发要连上MySQL本质上要解决三件事MySQL服务端能正常监听并提供连接、Qt这边能加载对应数据库驱动、两者之间的网络与认证参数完全对齐。这三件事任何一环出问题都会以不同形式的报错暴露出来。为什么很多教程一上来就教你怎么在Qt里写连接代码因为对于已经在用MySQL的人来说服务端这一关早就过了自然觉得理所当然。但不少新手其实是先装了Qt后装MySQL甚至MySQL和Qt的位数都不一样那问题就多了。就我实际接触过的案例来看90%的连接失败都可以归结到下面几个原因MySQL服务没有启动或者只监听在localhost客户端连的却是别的地址Qt编译出来的程序加载不到qsqlmysql.dll或libqsqlmysql.so也就是驱动缺位MySQL 8.0默认的caching_sha2_password认证插件和Qt自带的旧版驱动不兼容Windows下Qt是MinGW版本却配了一套MSVC编译的驱动运行时直接崩溃所以这一篇的配置思路就按顺序来先把MySQL服务端和客户端工具装好、把库跑起来再确认Qt侧驱动可用最后用一个最简单的工程把连接打通。每一步都给你可以直接抄的检查命令尽量把坑都踩平了。1.1 用哪个版本组合最省心版本选择这件事直接影响你要不要自己编译驱动。先说结论我自己长期在用的组合是Qt 5.15.2 MySQL 8.0Windows和Linux都在用。这个搭配在稳定性和驱动兼容性上比较平衡。如果你用的是Qt 5.12以后的版本官方安装包里已经自带了MySQL驱动但分编译器。mingw目录下对应MinGW的驱动msvc目录下对应MSVC的驱动。如果你下载的是qt-opensource-windows-x86-64-5.15.2.exe展开后能找到D:\Qt\5.15.2\mingw81_64\plugins\sqldrivers\qsqlmysql.dll这样一个文件说明驱动是有的。MySQL这边官方下载页提供MySQL Community Server 8.0.x安装包区分32位和64位和Qt的位数必须对上。我见过有人Qt装64位、MySQL装32位结果驱动文件拷贝到哪都加载不了查了半天才发现位数不匹配。另外MySQL Adviser那个包只是连接工具不是服务端别装错。另外如果你在Linux下开发建议直接用系统包管理器装libqt5sql5-mysql或者qtbase5-dev对应的驱动包省去手工拷贝的麻烦。1.2 配置前需要确认的几个基础点在你开始动手前先在命令行里确认三件事。第一MySQL服务是否已经在运行Windows下打开服务管理器看MySQL80这个服务Linux下执行systemctl status mysqld或者service mysql status。第二确认Qt版本和构建套件打开Qt Creator在“工具 → Kits”里看当前Kit的编译器类型和Qt版本路径。第三确认连接MySQL时要用的账号和权限root账号本地连接一般没问题但如果要远程连就需要额外授权。这三个点确认完了再往下走就不会出现那种“驱动已经放了但还没生效”的乌龙情况。2. 核心环节一MySQL服务端的安装与基础配置MySQL的安装方式多种多样Windows下通常是图形化安装器Linux下则常用apt、yum或自带离线包。无论哪种方式安装完必须做对几件基础配置root密码、字符集、服务端口和允许连接的地址。Windows安装时安装器会让你选Developer Default还是Server only。我建议选Server only避免装一堆用不上的组件。配置类型选Development Computer端口默认3306认证方式如果用了MySQL 8.0会让你选Use Legacy Authentication还是Use Strong Password Encryption。这里先剧透一个坑如果驱动版本较老或者走ODBC连线选Legacy Authentication会更稳否则后面大概率遇到认证协议不识别的问题。但也不是说必须选旧认证Qt自带的较新驱动是支持caching_sha2_password的这个我们后面验证。root密码设置要记牢如果你是从学习机或测试环境开始密码设得再简单都行但别在项目里硬编码到正式环境。为了后面方便命令行操作建议勾选Create MySQL Router之外的全部默认选项但不需要安装MySQL Router。Linux下用apt安装的MySQL 8.0默认root密码不是空的而是安装时生成的一个临时密码或者需要通过socket peer credentials认证。所以你第一件事是执行sudo mysql进入MySQL命令行然后把root密码改成自己习惯的。命令也很直白ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;字符集配置是很容易被忽略的细节。Windows安装器有个步骤叫Accounts and Roles后面还有Apply Configuration但字符集不会直接让你选。安装完成后找到my.ini配置文件加上这么一段[mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_unicode_ci port3306 bind-address127.0.0.1utf8mb4可以完整存放emoji和生僻字现在的项目基本都用它别再用老旧的utf8。bind-address决定了MySQL要不要接受外部连接如果只是本机Qt开发连库保持127.0.0.1就够了既安全又省心。改完配置记得重启MySQL服务Windows在服务管理器里重启Linux执行systemctl restart mysql或service mysql restart。2.1 创建专用账号并验证连接这一步很多人直接跳过用root账号开发测试图省事。但真正规范的做法是给应用建一个专用账号只授予它需要的权限。这样万一证书泄露风险也可控。我自己的习惯是CREATE USER qt_devlocalhost IDENTIFIED BY 123456; GRANT ALL PRIVILEGES ON testdb.* TO qt_devlocalhost; FLUSH PRIVILEGES;这里的testdb是你要用的数据库名字如果你还没创建就先执行CREATE DATABASE testdb CHARACTER SET utf8mb4;。然后验证一下能否用新账号登录mysql -u qt_dev -p testdb如果这里能顺利进入MySQL命令行说明服务端这边已经通了问题就集中在Qt侧。如果不能登录优先检查账号授权语法和bind-address。2.2 图形化工具Navicat装不装很多教程会顺手推荐Navicat说方便查看数据。实话讲Navicat确实好用但它是收费软件。如果是为了学习Qt开发未必非要装它。DBeaver Community和MySQL Workbench都是免费替代品。MySQL Workbench是官方出品既能连接管理数据库还能做ER图功能很全。工具的作用是帮你直观确认“数据库本身没毛病”别让它反过来干扰你的主任务。我自己在终端环境里还会用mysql命令行完成大部分操作图形工具更多是查数据、看表结构时用。你用什么都行核心是能正常读写数据。3. 核心环节二Qt侧MySQL驱动验证与连接准备MySQL服务端搞定后真正的重头戏来了。Qt连接MySQL驱动是关键。如果你下载的是官方Qt安装包并且安装时勾选了对应的库模块那么驱动文件应该是存在的。问题在于你写的程序运行时Qt能不能找到它。先说一个最常见的报错QSqlDatabase: QMYSQL driver not loaded。看到这句话先别急着怀疑MySQL配置先检查驱动文件在哪。Windows下驱动文件通常位于Qt安装目录的plugins\sqldrivers文件夹比如D:\Qt\5.15.2\mingw81_64\plugins\sqldrivers\qsqlmysql.dll D:\Qt\5.15.2\msvc2019_64\plugins\sqldrivers\qsqlmysql.dll如果这个文件存在那加载失败的原因往往是缺少依赖库。qsqlmysql.dll不是一个大文件但它依赖MySQL客户端的libmysql.dll。也就是说光有qsqlmysql.dll还不够你得把MySQL安装目录下的libmysql.dllMySQL 8.0里叫libmysql.dll在安装目录的bin文件夹里复制到两个位置一个是你的程序运行目录另一个是Qt插件的sqldrivers目录旁边或者系统目录。Linux下则更明显插件叫libqsqlmysql.so依赖libmysqlclient.so。如果系统没装客户端库就会加载失败。用ldd命令就能看明白ldd /usr/lib/x86_64-linux-gnu/qt5/plugins/sqldrivers/libqsqlmysql.so输出里如果有not found那就说明缺依赖。Ubuntu下执行sudo apt install libmysqlclient21就能补齐。CentOS/RHEL那边叫mysql-libs或者mysql-community-libs具体看你用哪个版本。注意不要为了省事把整个Qt目录里的插件都拷贝到运行目录简单粗暴的做法反而容易引入版本冲突。优先保障sqldrivers路径的完整性然后把运行目录里的驱动依赖放好。3.1 Qt自带驱动 vs 自己编驱动如果Qt安装包的插件目录里压根没有qsqlmysql.dll或者libqsqlmysql.so那就意味着你的Qt构建里没包含MySQL驱动模块。常见于自定义安装或者某些精简版发行包。这时候你有两条路一是安装qtbase的MySQL插件包例如Ubuntu的libqt5sql5-mysql二是从源码自己编译驱动。自己编译驱动这件事新手听起来很硬核其实思路很简单找到Qt源码里的qtbase/src/plugins/sqldrivers/mysql目录用qmake设置好MySQL头文件和库文件路径然后make。Windows下需要先安装MySQL的C ConnectorLinux下则依赖libmysqlclient-dev。编译过程本身不难坑主要在路径。不过对于初学者我建议先检查系统包和官方自带的驱动别一上来就尝试自编译。毕竟自编译要环境干净、路径清晰还得注意编译器版本和Qt版本匹配一通操作下来学习精力全耗在环境上了。3.2 Qt中启用MySQL驱动的最小代码框架驱动确认没问题后就可以在代码里用固定的套路来加载驱动了。这里给一个可以直接跑的框架先不涉及业务逻辑只验证连接#include QCoreApplication #include QSqlDatabase #include QSqlError #include QDebug int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); QSqlDatabase db QSqlDatabase::addDatabase(QMYSQL); db.setHostName(127.0.0.1); db.setPort(3306); db.setDatabaseName(testdb); db.setUserName(qt_dev); db.setPassword(123456); if (!db.open()) { qDebug() 连接失败: db.lastError().text(); return -1; } qDebug() 连接成功; db.close(); return a.exec(); }注意这里的addDatabase(QMYSQL)字符串必须和Qt编译时的驱动名一致。MySQL的驱动名是QMYSQL。写错比如写成了QMYSQL3老版本遗留叫法就会直接触发driver not loaded。提示如果你在QSqlDatabase::addDatabase()之前调用了QCoreApplication::instance()-addLibraryPath()要注意路径拼接问题。大多数情况下只要运行目录里有插件和依赖库Qt能自动找到。这个框架跑通了后面你的项目就能在db.open()成功之后使用QSqlQuery进行增删改查了。4. 核心环节三第一个Qt工程怎么把配置真正跑起来代码只是一个公式工程配置才是让它成立的前提。很多新手在Qt Creator里新建了一个空工程然后直接写数据库代码结果编译时找不到头文件链接时报undefined reference to原因出在pro文件没配置。Qt的工程文件.pro里最基础的两条是QT core gui如果不需要界面就core以及QT sql。少了sql模块QSqlDatabase类根本不会被链接进来。所以你的pro文件至少要有QT core sql CONFIG console c11 TARGET mysql_test TEMPLATE app SOURCES main.cpp如果你用的是Qt Widgets界面再加上QT widgets。很多教程里写QT core gui sql但gui不等于widgets如果你后面用了QMainWindow会缺一个模块。先按需求加别贪多。然后编译运行。如果一切正常控制台会打印出“连接成功”。这个最简单的成功验证比什么复杂理论都管用。如果你的系统环境是Windows MinGW套件这里有个经常被忽略的细节运行时缺libwinpthread-1.dll、libgcc_s_seh-1.dll这类动态库程序停在启动阶段。这是MinGW程序常见的部署问题把Qt安装目录下bin文件夹里的这几个dll拷贝到运行目录即可。4.1 在工程里动态检查可用的驱动如果你的环境比较复杂比如系统里装了多个MySQL客户端库、或者Qt插件目录杂乱建议在代码里先把可用驱动打出来快速定位QStringList drivers QSqlDatabase::drivers(); qDebug() drivers;正常输出会包含QSQLITE、QMYSQL、QMYSQL3等。如果列表里根本没有QMYSQL说明驱动插件没被Qt发现先别排查连接问题回头检查插件路径和依赖库。如果列表里有QMYSQL但open()失败再看具体的lastError()这就能把排查范围缩小一大半。我接手过不少同事的项目他们配置半天连不上最后打印驱动列表发现Qt加载的插件目录压根不是自己改的那份是因为项目里设置了QCoreApplication::setLibraryPaths把搜索路径覆盖了。所以动态检查这一步不要省。4.2 配置连接参数时容易被忽略的几个默认值setHostName()里如果填localhost和127.0.0.1在MySQL服务端视角看是两回事。localhost在Linux上往往走Unix socket客户端和服务器在同一台机器上时MySQL默认使用socket方式连接而不是TCP。Qt的MySQL驱动走的是TCP所以填localhost可能被MySQL解析成socket导致连接方式不匹配。安全的做法是在Qt里统一填127.0.0.1强制走TCP。setPort(3306)这里MySQL默认端口是3306但你在my.ini里改过端口的话这里必须对应改。不要想当然。我还遇到过用户MySQL跑在WSL里Windows侧映射端口不是3306然后拿着映射后的端口填进代码这种场景属于环境复杂需要自己梳理清楚。数据库名setDatabaseName()填的是你要操作的库它不负责自动创建库。很多人第一次连库还没建就卡在“连接失败”上。建议先在建库这一步就把testdb建好或者填写一个系统自带的库名比如mysql先测试连接。5. 常见问题与排查技巧实录这一节是全文最值钱的部分。配置MySQL和Qt连接老手和新手的差距往往就体现在踩坑的速度上。下面这组问题每一个都是我或者身边同事真真切切遇到过的按出现频率排列排查思路直接给到位。报错信息原因排查方法QMYSQL driver not loadedQt找不到MySQL驱动插件或依赖缺失检查sqldrivers目录、libmysql.dll依赖、驱动列表输出SSL connection error: SSL is required...MySQL要求SSL但Qt侧SSL参数没对上连接参数里关掉SSL或配置服务端SSL策略ERROR 2002 (HY000): Cant connect to local MySQL server through socket /tmp/mysql.sock客户端想走socket但服务端没有这个socket文件用-h 127.0.0.1 -P 3306强制TCP连接检查mysqld是否运行Authentication plugin caching_sha2_password cannot be loadedMySQL 8.0默认认证插件与旧驱动不兼容改账号认证方式为mysql_native_password或换新驱动Unknown database testdb填的库名不存在先连接mysql库再CREATE DATABASE5.1 MySQL 8.0的可插拔认证与SSL问题详解MySQL 8.0默认使用caching_sha2_password认证插件比旧的mysql_native_password安全很多。但问题是Qt自带的驱动版本如果不够新或者依赖的MySQL客户端库是5.x版本根本无法识别这个新插件连接就会失败。解决办法有两个方向一是把MySQL账号的认证插件改回mysql_native_password适合不想升级依赖的情况二是确保libmysql版本新到支持新插件推荐长期方案。改认证插件的方式前文已经给了语句这里再针对SSL说明一下。MySQL 8.0默认开启SSL要求有些版本、有些连接场景下服务端会强制要求SSL。此时Qt连接报错会出现SSL connection error。最省事的处理是连接参数里加MYSQL_OPT_SSL_MODEQt的MySQL驱动可以通过设置连接选项来处理比如db.setConnectOptions(MYSQL_OPT_SSL_MODEDISABLED);如果你的是测试环境数据敏感性不高SSL关闭问题不大。如果是正式环境还是老老实实配好证书别图省事。5.2 驱动文件拷贝了但加载失败依赖库才是真凶很多人遇到driver not loaded第一反应是再拷一次驱动文件结果发现拷了十次也没用。问题十有八九出在依赖库上。Windows平台qsqlmysql.dll依赖MySQL客户端的libmysql.dll。你可以用 Dependencies 这个工具查看dll依赖绿色对勾表示正常红色叉号就是缺失。我自己就遇到过一个迷惑案例拷贝了libmysql.dll到运行目录依然报错后来才发现是因为运行目录里还有一个旧的libmysql.dll版本来自另一个安装包版本太旧不满足插件的符号要求。这种“文件在但不匹配”的情况比缺文件更隐蔽只能通过工具排查依赖版本。Linux平台则用ldd检查libqsqlmysql.so的依赖。常见缺失是libmysqlclient.so.21低版本系统上只有libmysqlclient.so.18就会出现找不到符号的问题。解决方法是升级MySQL客户端库或装对应发行版的兼容包。5.3 Qt Creator中运行正常、双击exe却连不上数据库这个问题很典型讲透它能帮你理解整个配置链路。Qt Creator里运行程序时环境变量里带着Qt库的路径所以插件和依赖都能找到。但你跑到资源管理器里双击编译好的exeQt库路径不再自动注入程序要么闪退、要么driver not loaded。解决办法就是打包部署时要带上Qt依赖。最基础的手工做法在程序运行目录下建一个sqldrivers目录把qsqlmysql.dll放进去再在程序根目录放上libmysql.dll和各Qt dll。如果你用Qt自带的windeployqt.exe它会自动分析可执行文件的Qt依赖并拷贝对应的dll和插件。执行命令windeployqt --release --no-compiler-runtime mysql_test.exe注意windeployqt放在Qt的bin目录里并且要用与构建套件相同版本的。如果你用MSVC构建需要在安装了编译器插件的命令行环境里执行或者在Qt命令行工具中执行。MinGW构建的直接用MinGW的windeployqt即可。5.4 QSqlQuery执行时报错但db.open()是成功的配置通了之后连接本身没问题但执行SQL时报错。这种情况先看QSqlError和lastError()的输出。常见原因有几种表名写错、字段名和SQL关键字冲突、字符串没有用引号包裹、编码问题导致SQL语句里的中文乱码。编码问题在中文环境下很常见。Windows下控制台默认还是GBK或GB18030Qt源码文件如果保存成了GBK字符串字面量传给MySQL时如果数据库连接字符集是utf8mb4就会出现中文乱码。稳妥的做法是源码文件一律UTF-8编码并且在连接后执行SET NAMES utf8mb4或者设置连接选项。MySQL 8.0的新客户端库默认字符集通常已经是utf8mb4但Qt的编码传递链里还是可能出问题。从配置角度说连接成功后先做一次字符集校准动作是一个稳妥的好习惯QSqlQuery query(db); query.exec(SET NAMES utf8mb4);这样能规避大部分中文乱码问题。5.5 老掉牙的坑驱动名写错与端口漏配再低级的问题也总有人犯。QSqlDatabase::addDatabase(QMYSQL)里的大小写是敏感的小写qmysql不行中横线不行。端口不填的情况下Qt默认值是0而不是3306如果用不指定端口的方式去连MySQL客户端库会失败。所以明确写setPort(3306)更稳妥。还有一个小坑如果你的项目里同时用了SQLite和MySQLaddDatabase()的第二个参数可以让连接有别名否则默认是默认连接。两个实例都写addDatabase(QMYSQL)第二次调用会把之前的默认连接覆盖掉。如果需要同时连接多个数据库要这样写QSqlDatabase db1 QSqlDatabase::addDatabase(QMYSQL, conn_testdb); db1.setDatabaseName(testdb);你可以只建一个默认连接但学习阶段建议理解这个机制后面项目变复杂时就能避免很多麻烦。6. 驱动对应关系与常见配置速查表为了让这个配置过程更加清晰我把Qt与MySQL搭配的几个关键参数整理成一个速查表方便你在不同环境下照着配置。配置项推荐值说明Qt版本5.15.2LTS版本驱动相对齐全兼容性较好MySQL版本8.0.x当前主流注意认证插件兼容性驱动名称QMYSQL加载时大小写敏感的固定名称连接地址127.0.0.1Linux下避免localhost解析成socket端口3306与MySQL服务端配置保持一致字符集utf8mb4服务端、表结构、连接级都要统一认证插件mysql_native_password或caching_sha2_password老驱动选前者新驱动选后者这里再提供一个Windows环境下验证驱动是否可用的标准流程。先确认MySQL的bin目录在系统PATH里然后打开Qt命令行工具输入mysql -u qt_dev -p -h 127.0.0.1 -P 3306 testdb如果这个命令能进入MySQL命令行说明MySQL服务没问题。再编译运行前文那个最小代码看QSqlDatabase::drivers()里有没有QMYSQL。两层都通过连接就不会有大问题。Linux环境下类似确认mysql客户端能连再用Qt程序和命令行各测一次。命令行是最好用的排错工具比图形界面更能暴露真实问题。有时Navicat能连、Qt不能连问题往往出在Qt的驱动链接库上而不是MySQL本身。用命令行能把你带离“是不是MySQL坏了”的猜测。7. 从配置走向开发下一篇的方向展望当db.open()能成功返回trueQt和MySQL之间的连接配置就真正落地了。此时你手里已经有一台能连通的数据库服务、一套能拉起来的Qt开发环境、一个能打印“连接成功”的最小程序后面再往深走无非是三条路用QSqlQuery执行增删改查、用QSqlTableModel绑定界面控件、用连接池应对高并发场景。这三条路我都走过最大的感受是连接配置只是入场券真正的门道在于SQL执行策略和模型视图框架的理解。比如QSqlQuery适合写复杂的SQL、执行存储过程而QSqlTableModel配合QTableView能快速显示一张表的数据适合做简单管理工具。下一次展开讲的时候我会用一个员工信息表的增删改查实战来拆解把QSqlQuery和QSqlTableModel两种方式都跑一遍。配置阶段的这些基础动作当时觉得繁琐后面所有开发都会受益因为一旦出错你能快速判断出问题在哪一环。8. 写在最后配置阶段的三条实用经验把这篇教程的干货压成三句话送给正被配置折磨的人。第一排查顺序永远是从底层往上。MySQL命令行连不通就先解决MySQL命令行通了再去看Qt驱动驱动列表里有QMYSQL再看连接参数。不要一上来就怀疑代码很多时候代码一行没错错的是环境。第二版本和位数的一致性怎么强调都不过分。Qt是64位MySQL客户端库也要64位Qt用MinGW编译驱动就要选带MinGW的构建目录千万别混用MSVC和MinGW的插件文件。第三把每一次报错信息完整记录下来。很多人发帖问问题只截一张“连接失败”的图下面的具体错误文本反而没截到。lastError().text()里的内容才是你排查的真正线索也是别人帮你看问题时最需要的信息。配置MySQL这一步说难不难说简单也藏着不少细节。照着这篇一步步来把服务端装好、驱动确认好、最小工程跑通你的Qt数据库开发之路就算正式开始了。后面再回头处理具体功能时你会感谢今天这个把环境打扎实的自己。
Qt+MySQL配置实战：从服务端安装到驱动加载与连接成功
很多刚开始用Qt连MySQL的朋友第一反应都是“不就是装个数据库、加个驱动、写两行代码嘛”真到自己上手才发现光一个配置环节就能卡住半天。有的报QMYSQL driver not loaded有的报SSL connection error还有的在Linux下折腾半天连/tmp/mysql.sock都找不到。这篇教程不讲虚的就围绕“Qt MySQL”这条线先把最基础也最容易出问题的“配置MySQL”这一步彻底捋清楚。学完之后你能把本地的MySQL服务跑起来让Qt项目正确加载驱动并稳稳连上数据库。适合刚接触Qt开发、还没成功跑通数据库连接的初学者也适合被各种连接报错折腾到头疼的老哥参考。1. 整体思路先理清Qt连MySQL要过哪三关Qt开发要连上MySQL本质上要解决三件事MySQL服务端能正常监听并提供连接、Qt这边能加载对应数据库驱动、两者之间的网络与认证参数完全对齐。这三件事任何一环出问题都会以不同形式的报错暴露出来。为什么很多教程一上来就教你怎么在Qt里写连接代码因为对于已经在用MySQL的人来说服务端这一关早就过了自然觉得理所当然。但不少新手其实是先装了Qt后装MySQL甚至MySQL和Qt的位数都不一样那问题就多了。就我实际接触过的案例来看90%的连接失败都可以归结到下面几个原因MySQL服务没有启动或者只监听在localhost客户端连的却是别的地址Qt编译出来的程序加载不到qsqlmysql.dll或libqsqlmysql.so也就是驱动缺位MySQL 8.0默认的caching_sha2_password认证插件和Qt自带的旧版驱动不兼容Windows下Qt是MinGW版本却配了一套MSVC编译的驱动运行时直接崩溃所以这一篇的配置思路就按顺序来先把MySQL服务端和客户端工具装好、把库跑起来再确认Qt侧驱动可用最后用一个最简单的工程把连接打通。每一步都给你可以直接抄的检查命令尽量把坑都踩平了。1.1 用哪个版本组合最省心版本选择这件事直接影响你要不要自己编译驱动。先说结论我自己长期在用的组合是Qt 5.15.2 MySQL 8.0Windows和Linux都在用。这个搭配在稳定性和驱动兼容性上比较平衡。如果你用的是Qt 5.12以后的版本官方安装包里已经自带了MySQL驱动但分编译器。mingw目录下对应MinGW的驱动msvc目录下对应MSVC的驱动。如果你下载的是qt-opensource-windows-x86-64-5.15.2.exe展开后能找到D:\Qt\5.15.2\mingw81_64\plugins\sqldrivers\qsqlmysql.dll这样一个文件说明驱动是有的。MySQL这边官方下载页提供MySQL Community Server 8.0.x安装包区分32位和64位和Qt的位数必须对上。我见过有人Qt装64位、MySQL装32位结果驱动文件拷贝到哪都加载不了查了半天才发现位数不匹配。另外MySQL Adviser那个包只是连接工具不是服务端别装错。另外如果你在Linux下开发建议直接用系统包管理器装libqt5sql5-mysql或者qtbase5-dev对应的驱动包省去手工拷贝的麻烦。1.2 配置前需要确认的几个基础点在你开始动手前先在命令行里确认三件事。第一MySQL服务是否已经在运行Windows下打开服务管理器看MySQL80这个服务Linux下执行systemctl status mysqld或者service mysql status。第二确认Qt版本和构建套件打开Qt Creator在“工具 → Kits”里看当前Kit的编译器类型和Qt版本路径。第三确认连接MySQL时要用的账号和权限root账号本地连接一般没问题但如果要远程连就需要额外授权。这三个点确认完了再往下走就不会出现那种“驱动已经放了但还没生效”的乌龙情况。2. 核心环节一MySQL服务端的安装与基础配置MySQL的安装方式多种多样Windows下通常是图形化安装器Linux下则常用apt、yum或自带离线包。无论哪种方式安装完必须做对几件基础配置root密码、字符集、服务端口和允许连接的地址。Windows安装时安装器会让你选Developer Default还是Server only。我建议选Server only避免装一堆用不上的组件。配置类型选Development Computer端口默认3306认证方式如果用了MySQL 8.0会让你选Use Legacy Authentication还是Use Strong Password Encryption。这里先剧透一个坑如果驱动版本较老或者走ODBC连线选Legacy Authentication会更稳否则后面大概率遇到认证协议不识别的问题。但也不是说必须选旧认证Qt自带的较新驱动是支持caching_sha2_password的这个我们后面验证。root密码设置要记牢如果你是从学习机或测试环境开始密码设得再简单都行但别在项目里硬编码到正式环境。为了后面方便命令行操作建议勾选Create MySQL Router之外的全部默认选项但不需要安装MySQL Router。Linux下用apt安装的MySQL 8.0默认root密码不是空的而是安装时生成的一个临时密码或者需要通过socket peer credentials认证。所以你第一件事是执行sudo mysql进入MySQL命令行然后把root密码改成自己习惯的。命令也很直白ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;字符集配置是很容易被忽略的细节。Windows安装器有个步骤叫Accounts and Roles后面还有Apply Configuration但字符集不会直接让你选。安装完成后找到my.ini配置文件加上这么一段[mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_unicode_ci port3306 bind-address127.0.0.1utf8mb4可以完整存放emoji和生僻字现在的项目基本都用它别再用老旧的utf8。bind-address决定了MySQL要不要接受外部连接如果只是本机Qt开发连库保持127.0.0.1就够了既安全又省心。改完配置记得重启MySQL服务Windows在服务管理器里重启Linux执行systemctl restart mysql或service mysql restart。2.1 创建专用账号并验证连接这一步很多人直接跳过用root账号开发测试图省事。但真正规范的做法是给应用建一个专用账号只授予它需要的权限。这样万一证书泄露风险也可控。我自己的习惯是CREATE USER qt_devlocalhost IDENTIFIED BY 123456; GRANT ALL PRIVILEGES ON testdb.* TO qt_devlocalhost; FLUSH PRIVILEGES;这里的testdb是你要用的数据库名字如果你还没创建就先执行CREATE DATABASE testdb CHARACTER SET utf8mb4;。然后验证一下能否用新账号登录mysql -u qt_dev -p testdb如果这里能顺利进入MySQL命令行说明服务端这边已经通了问题就集中在Qt侧。如果不能登录优先检查账号授权语法和bind-address。2.2 图形化工具Navicat装不装很多教程会顺手推荐Navicat说方便查看数据。实话讲Navicat确实好用但它是收费软件。如果是为了学习Qt开发未必非要装它。DBeaver Community和MySQL Workbench都是免费替代品。MySQL Workbench是官方出品既能连接管理数据库还能做ER图功能很全。工具的作用是帮你直观确认“数据库本身没毛病”别让它反过来干扰你的主任务。我自己在终端环境里还会用mysql命令行完成大部分操作图形工具更多是查数据、看表结构时用。你用什么都行核心是能正常读写数据。3. 核心环节二Qt侧MySQL驱动验证与连接准备MySQL服务端搞定后真正的重头戏来了。Qt连接MySQL驱动是关键。如果你下载的是官方Qt安装包并且安装时勾选了对应的库模块那么驱动文件应该是存在的。问题在于你写的程序运行时Qt能不能找到它。先说一个最常见的报错QSqlDatabase: QMYSQL driver not loaded。看到这句话先别急着怀疑MySQL配置先检查驱动文件在哪。Windows下驱动文件通常位于Qt安装目录的plugins\sqldrivers文件夹比如D:\Qt\5.15.2\mingw81_64\plugins\sqldrivers\qsqlmysql.dll D:\Qt\5.15.2\msvc2019_64\plugins\sqldrivers\qsqlmysql.dll如果这个文件存在那加载失败的原因往往是缺少依赖库。qsqlmysql.dll不是一个大文件但它依赖MySQL客户端的libmysql.dll。也就是说光有qsqlmysql.dll还不够你得把MySQL安装目录下的libmysql.dllMySQL 8.0里叫libmysql.dll在安装目录的bin文件夹里复制到两个位置一个是你的程序运行目录另一个是Qt插件的sqldrivers目录旁边或者系统目录。Linux下则更明显插件叫libqsqlmysql.so依赖libmysqlclient.so。如果系统没装客户端库就会加载失败。用ldd命令就能看明白ldd /usr/lib/x86_64-linux-gnu/qt5/plugins/sqldrivers/libqsqlmysql.so输出里如果有not found那就说明缺依赖。Ubuntu下执行sudo apt install libmysqlclient21就能补齐。CentOS/RHEL那边叫mysql-libs或者mysql-community-libs具体看你用哪个版本。注意不要为了省事把整个Qt目录里的插件都拷贝到运行目录简单粗暴的做法反而容易引入版本冲突。优先保障sqldrivers路径的完整性然后把运行目录里的驱动依赖放好。3.1 Qt自带驱动 vs 自己编驱动如果Qt安装包的插件目录里压根没有qsqlmysql.dll或者libqsqlmysql.so那就意味着你的Qt构建里没包含MySQL驱动模块。常见于自定义安装或者某些精简版发行包。这时候你有两条路一是安装qtbase的MySQL插件包例如Ubuntu的libqt5sql5-mysql二是从源码自己编译驱动。自己编译驱动这件事新手听起来很硬核其实思路很简单找到Qt源码里的qtbase/src/plugins/sqldrivers/mysql目录用qmake设置好MySQL头文件和库文件路径然后make。Windows下需要先安装MySQL的C ConnectorLinux下则依赖libmysqlclient-dev。编译过程本身不难坑主要在路径。不过对于初学者我建议先检查系统包和官方自带的驱动别一上来就尝试自编译。毕竟自编译要环境干净、路径清晰还得注意编译器版本和Qt版本匹配一通操作下来学习精力全耗在环境上了。3.2 Qt中启用MySQL驱动的最小代码框架驱动确认没问题后就可以在代码里用固定的套路来加载驱动了。这里给一个可以直接跑的框架先不涉及业务逻辑只验证连接#include QCoreApplication #include QSqlDatabase #include QSqlError #include QDebug int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); QSqlDatabase db QSqlDatabase::addDatabase(QMYSQL); db.setHostName(127.0.0.1); db.setPort(3306); db.setDatabaseName(testdb); db.setUserName(qt_dev); db.setPassword(123456); if (!db.open()) { qDebug() 连接失败: db.lastError().text(); return -1; } qDebug() 连接成功; db.close(); return a.exec(); }注意这里的addDatabase(QMYSQL)字符串必须和Qt编译时的驱动名一致。MySQL的驱动名是QMYSQL。写错比如写成了QMYSQL3老版本遗留叫法就会直接触发driver not loaded。提示如果你在QSqlDatabase::addDatabase()之前调用了QCoreApplication::instance()-addLibraryPath()要注意路径拼接问题。大多数情况下只要运行目录里有插件和依赖库Qt能自动找到。这个框架跑通了后面你的项目就能在db.open()成功之后使用QSqlQuery进行增删改查了。4. 核心环节三第一个Qt工程怎么把配置真正跑起来代码只是一个公式工程配置才是让它成立的前提。很多新手在Qt Creator里新建了一个空工程然后直接写数据库代码结果编译时找不到头文件链接时报undefined reference to原因出在pro文件没配置。Qt的工程文件.pro里最基础的两条是QT core gui如果不需要界面就core以及QT sql。少了sql模块QSqlDatabase类根本不会被链接进来。所以你的pro文件至少要有QT core sql CONFIG console c11 TARGET mysql_test TEMPLATE app SOURCES main.cpp如果你用的是Qt Widgets界面再加上QT widgets。很多教程里写QT core gui sql但gui不等于widgets如果你后面用了QMainWindow会缺一个模块。先按需求加别贪多。然后编译运行。如果一切正常控制台会打印出“连接成功”。这个最简单的成功验证比什么复杂理论都管用。如果你的系统环境是Windows MinGW套件这里有个经常被忽略的细节运行时缺libwinpthread-1.dll、libgcc_s_seh-1.dll这类动态库程序停在启动阶段。这是MinGW程序常见的部署问题把Qt安装目录下bin文件夹里的这几个dll拷贝到运行目录即可。4.1 在工程里动态检查可用的驱动如果你的环境比较复杂比如系统里装了多个MySQL客户端库、或者Qt插件目录杂乱建议在代码里先把可用驱动打出来快速定位QStringList drivers QSqlDatabase::drivers(); qDebug() drivers;正常输出会包含QSQLITE、QMYSQL、QMYSQL3等。如果列表里根本没有QMYSQL说明驱动插件没被Qt发现先别排查连接问题回头检查插件路径和依赖库。如果列表里有QMYSQL但open()失败再看具体的lastError()这就能把排查范围缩小一大半。我接手过不少同事的项目他们配置半天连不上最后打印驱动列表发现Qt加载的插件目录压根不是自己改的那份是因为项目里设置了QCoreApplication::setLibraryPaths把搜索路径覆盖了。所以动态检查这一步不要省。4.2 配置连接参数时容易被忽略的几个默认值setHostName()里如果填localhost和127.0.0.1在MySQL服务端视角看是两回事。localhost在Linux上往往走Unix socket客户端和服务器在同一台机器上时MySQL默认使用socket方式连接而不是TCP。Qt的MySQL驱动走的是TCP所以填localhost可能被MySQL解析成socket导致连接方式不匹配。安全的做法是在Qt里统一填127.0.0.1强制走TCP。setPort(3306)这里MySQL默认端口是3306但你在my.ini里改过端口的话这里必须对应改。不要想当然。我还遇到过用户MySQL跑在WSL里Windows侧映射端口不是3306然后拿着映射后的端口填进代码这种场景属于环境复杂需要自己梳理清楚。数据库名setDatabaseName()填的是你要操作的库它不负责自动创建库。很多人第一次连库还没建就卡在“连接失败”上。建议先在建库这一步就把testdb建好或者填写一个系统自带的库名比如mysql先测试连接。5. 常见问题与排查技巧实录这一节是全文最值钱的部分。配置MySQL和Qt连接老手和新手的差距往往就体现在踩坑的速度上。下面这组问题每一个都是我或者身边同事真真切切遇到过的按出现频率排列排查思路直接给到位。报错信息原因排查方法QMYSQL driver not loadedQt找不到MySQL驱动插件或依赖缺失检查sqldrivers目录、libmysql.dll依赖、驱动列表输出SSL connection error: SSL is required...MySQL要求SSL但Qt侧SSL参数没对上连接参数里关掉SSL或配置服务端SSL策略ERROR 2002 (HY000): Cant connect to local MySQL server through socket /tmp/mysql.sock客户端想走socket但服务端没有这个socket文件用-h 127.0.0.1 -P 3306强制TCP连接检查mysqld是否运行Authentication plugin caching_sha2_password cannot be loadedMySQL 8.0默认认证插件与旧驱动不兼容改账号认证方式为mysql_native_password或换新驱动Unknown database testdb填的库名不存在先连接mysql库再CREATE DATABASE5.1 MySQL 8.0的可插拔认证与SSL问题详解MySQL 8.0默认使用caching_sha2_password认证插件比旧的mysql_native_password安全很多。但问题是Qt自带的驱动版本如果不够新或者依赖的MySQL客户端库是5.x版本根本无法识别这个新插件连接就会失败。解决办法有两个方向一是把MySQL账号的认证插件改回mysql_native_password适合不想升级依赖的情况二是确保libmysql版本新到支持新插件推荐长期方案。改认证插件的方式前文已经给了语句这里再针对SSL说明一下。MySQL 8.0默认开启SSL要求有些版本、有些连接场景下服务端会强制要求SSL。此时Qt连接报错会出现SSL connection error。最省事的处理是连接参数里加MYSQL_OPT_SSL_MODEQt的MySQL驱动可以通过设置连接选项来处理比如db.setConnectOptions(MYSQL_OPT_SSL_MODEDISABLED);如果你的是测试环境数据敏感性不高SSL关闭问题不大。如果是正式环境还是老老实实配好证书别图省事。5.2 驱动文件拷贝了但加载失败依赖库才是真凶很多人遇到driver not loaded第一反应是再拷一次驱动文件结果发现拷了十次也没用。问题十有八九出在依赖库上。Windows平台qsqlmysql.dll依赖MySQL客户端的libmysql.dll。你可以用 Dependencies 这个工具查看dll依赖绿色对勾表示正常红色叉号就是缺失。我自己就遇到过一个迷惑案例拷贝了libmysql.dll到运行目录依然报错后来才发现是因为运行目录里还有一个旧的libmysql.dll版本来自另一个安装包版本太旧不满足插件的符号要求。这种“文件在但不匹配”的情况比缺文件更隐蔽只能通过工具排查依赖版本。Linux平台则用ldd检查libqsqlmysql.so的依赖。常见缺失是libmysqlclient.so.21低版本系统上只有libmysqlclient.so.18就会出现找不到符号的问题。解决方法是升级MySQL客户端库或装对应发行版的兼容包。5.3 Qt Creator中运行正常、双击exe却连不上数据库这个问题很典型讲透它能帮你理解整个配置链路。Qt Creator里运行程序时环境变量里带着Qt库的路径所以插件和依赖都能找到。但你跑到资源管理器里双击编译好的exeQt库路径不再自动注入程序要么闪退、要么driver not loaded。解决办法就是打包部署时要带上Qt依赖。最基础的手工做法在程序运行目录下建一个sqldrivers目录把qsqlmysql.dll放进去再在程序根目录放上libmysql.dll和各Qt dll。如果你用Qt自带的windeployqt.exe它会自动分析可执行文件的Qt依赖并拷贝对应的dll和插件。执行命令windeployqt --release --no-compiler-runtime mysql_test.exe注意windeployqt放在Qt的bin目录里并且要用与构建套件相同版本的。如果你用MSVC构建需要在安装了编译器插件的命令行环境里执行或者在Qt命令行工具中执行。MinGW构建的直接用MinGW的windeployqt即可。5.4 QSqlQuery执行时报错但db.open()是成功的配置通了之后连接本身没问题但执行SQL时报错。这种情况先看QSqlError和lastError()的输出。常见原因有几种表名写错、字段名和SQL关键字冲突、字符串没有用引号包裹、编码问题导致SQL语句里的中文乱码。编码问题在中文环境下很常见。Windows下控制台默认还是GBK或GB18030Qt源码文件如果保存成了GBK字符串字面量传给MySQL时如果数据库连接字符集是utf8mb4就会出现中文乱码。稳妥的做法是源码文件一律UTF-8编码并且在连接后执行SET NAMES utf8mb4或者设置连接选项。MySQL 8.0的新客户端库默认字符集通常已经是utf8mb4但Qt的编码传递链里还是可能出问题。从配置角度说连接成功后先做一次字符集校准动作是一个稳妥的好习惯QSqlQuery query(db); query.exec(SET NAMES utf8mb4);这样能规避大部分中文乱码问题。5.5 老掉牙的坑驱动名写错与端口漏配再低级的问题也总有人犯。QSqlDatabase::addDatabase(QMYSQL)里的大小写是敏感的小写qmysql不行中横线不行。端口不填的情况下Qt默认值是0而不是3306如果用不指定端口的方式去连MySQL客户端库会失败。所以明确写setPort(3306)更稳妥。还有一个小坑如果你的项目里同时用了SQLite和MySQLaddDatabase()的第二个参数可以让连接有别名否则默认是默认连接。两个实例都写addDatabase(QMYSQL)第二次调用会把之前的默认连接覆盖掉。如果需要同时连接多个数据库要这样写QSqlDatabase db1 QSqlDatabase::addDatabase(QMYSQL, conn_testdb); db1.setDatabaseName(testdb);你可以只建一个默认连接但学习阶段建议理解这个机制后面项目变复杂时就能避免很多麻烦。6. 驱动对应关系与常见配置速查表为了让这个配置过程更加清晰我把Qt与MySQL搭配的几个关键参数整理成一个速查表方便你在不同环境下照着配置。配置项推荐值说明Qt版本5.15.2LTS版本驱动相对齐全兼容性较好MySQL版本8.0.x当前主流注意认证插件兼容性驱动名称QMYSQL加载时大小写敏感的固定名称连接地址127.0.0.1Linux下避免localhost解析成socket端口3306与MySQL服务端配置保持一致字符集utf8mb4服务端、表结构、连接级都要统一认证插件mysql_native_password或caching_sha2_password老驱动选前者新驱动选后者这里再提供一个Windows环境下验证驱动是否可用的标准流程。先确认MySQL的bin目录在系统PATH里然后打开Qt命令行工具输入mysql -u qt_dev -p -h 127.0.0.1 -P 3306 testdb如果这个命令能进入MySQL命令行说明MySQL服务没问题。再编译运行前文那个最小代码看QSqlDatabase::drivers()里有没有QMYSQL。两层都通过连接就不会有大问题。Linux环境下类似确认mysql客户端能连再用Qt程序和命令行各测一次。命令行是最好用的排错工具比图形界面更能暴露真实问题。有时Navicat能连、Qt不能连问题往往出在Qt的驱动链接库上而不是MySQL本身。用命令行能把你带离“是不是MySQL坏了”的猜测。7. 从配置走向开发下一篇的方向展望当db.open()能成功返回trueQt和MySQL之间的连接配置就真正落地了。此时你手里已经有一台能连通的数据库服务、一套能拉起来的Qt开发环境、一个能打印“连接成功”的最小程序后面再往深走无非是三条路用QSqlQuery执行增删改查、用QSqlTableModel绑定界面控件、用连接池应对高并发场景。这三条路我都走过最大的感受是连接配置只是入场券真正的门道在于SQL执行策略和模型视图框架的理解。比如QSqlQuery适合写复杂的SQL、执行存储过程而QSqlTableModel配合QTableView能快速显示一张表的数据适合做简单管理工具。下一次展开讲的时候我会用一个员工信息表的增删改查实战来拆解把QSqlQuery和QSqlTableModel两种方式都跑一遍。配置阶段的这些基础动作当时觉得繁琐后面所有开发都会受益因为一旦出错你能快速判断出问题在哪一环。8. 写在最后配置阶段的三条实用经验把这篇教程的干货压成三句话送给正被配置折磨的人。第一排查顺序永远是从底层往上。MySQL命令行连不通就先解决MySQL命令行通了再去看Qt驱动驱动列表里有QMYSQL再看连接参数。不要一上来就怀疑代码很多时候代码一行没错错的是环境。第二版本和位数的一致性怎么强调都不过分。Qt是64位MySQL客户端库也要64位Qt用MinGW编译驱动就要选带MinGW的构建目录千万别混用MSVC和MinGW的插件文件。第三把每一次报错信息完整记录下来。很多人发帖问问题只截一张“连接失败”的图下面的具体错误文本反而没截到。lastError().text()里的内容才是你排查的真正线索也是别人帮你看问题时最需要的信息。配置MySQL这一步说难不难说简单也藏着不少细节。照着这篇一步步来把服务端装好、驱动确认好、最小工程跑通你的Qt数据库开发之路就算正式开始了。后面再回头处理具体功能时你会感谢今天这个把环境打扎实的自己。
