Mac上Qt SQL驱动加载失败的完整排查与修复指南-育师

先交代一下背景：某次我把项目迁移到 Mac 上重新编译，跑起来之后去连数据库，控制台直接给我甩了三行 “QSqlDatabase: QMYSQL driver not loaded”，再往下追一行 “available drivers: QSQLITE”。那会儿我还没意识到，这个错误会让我在接下来两天里把 Qt 的插件机制、macOS 的动态库路径、甚至签名公证全部折腾一遍。如果你也在 Mac 平台下遇到 Qt SQL 驱动加载的问题，这篇文章就是给你写的。我会把现象分类、加载原理、完整排查链路、各个数据库驱动的差异，以及发布部署阶段会踩的坑全部过一遍，尽量说清楚“为什么”，而不是只给“怎么办”。

1. 症状先分级：你的驱动问题属于哪一种

很多人一碰见驱动加载失败就急着搜解决办法，但“驱动加载失败”这句话太笼统了，Mac 平台上至少能分四种不同的表现，对应完全不同的修复方向。我建议你先停下来，花一分钟对号入座，能省下大量无效操作。

1.1 四种最常见的故障表现

先看这个对照表，基本覆盖了日常开发中 90% 的“Qt SQL 驱动加载失败”场景：

症状类型	具体表现	最可能的根因
A. 驱动列表完全为空	`QSqlDatabase::drivers()`返回空列表，连 QSQLITE 都没有	Qt 插件目录没被识别到，或者程序里没有调用`addLibraryPath`
B. 只有 QSQLITE	驱动列表里只有 QSQLITE，MySQL/PostgreSQL 驱动消失	`libqmysql.dylib`/`libqpsql.dylib`存在但依赖的客户端库缺失
C. Qt Creator 里正常，独立运行崩	在 IDE 里点运行一切正常，打包或双击 app 就报驱动 not loaded	部署后插件路径、动态库路径、rpath 没有正确打包进去
D. 驱动列表有目标驱动，但连接失败	`drivers()`里能看到 QMYSQL，但`QSqlDatabase::open()`报错	客户端库版本不匹配、SSL 参数不匹配、连接参数错误

最常见的是 B 和 C。B 的典型场景是你明明用 Qt 官方安装包装了 MySQL 驱动插件，但drivers()只返回 SQLite；C 的典型场景是你在开发机上一切正常，换个目录打包给同事，就全部歇菜。

1.2 先确认一个关键事实：驱动是个插件

这里要先把概念掰扯清楚：Qt 的 SQL 驱动不是编译进主程序里的静态代码，而是放在插件目录下的动态库。你在编译时链接的是Qt6Sql这个框架库，但真正去连 MySQL 的数据收发，是靠运行时动态加载libqmysql.dylib这个插件完成的。

这个机制有点像电脑上的外设驱动：系统本身不知道你的打印机怎么工作，打印机开机后找到对应驱动文件才干活。Qt 也一样，它启动的时候去特定目录扫一圈，发现libqmysql.dylib就把它加载进来，加载成功就在drivers()里显示 QMYSQL，加载失败就静默跳过。

问题就出在这个“静默跳过”上。插件加载失败时 Qt 不会弹窗，你只有在访问drivers()时才看到列表少了一项。所以排查的第一步永远是：先确认你的插件文件本身存不存在、依赖的库齐不齐。

2. Qt 驱动插件加载机制：Mac 上为什么格外容易翻车

同样一套 Qt 程序，在 Windows 上装好驱动就能跑，一到 Mac 上就各种加载失败。这不是玄学，而是 macOS 的动态库机制和 Windows 有本质区别。理解了这层差异，你就知道问题该往哪个方向查。

2.1 macOS 的 Bundle 结构与插件目录

macOS 上的可分发性程序通常是一个.appbundle，本质上是一个带固定目录结构的文件夹：

YourApp.app/ Contents/ Info.plist MacOS/ YourApp # 真正的可执行文件 Frameworks/ # 动态框架 PlugIns/ sqldrivers/ # 数据库驱动插件

Qt 程序启动后，默认会去Contents/PlugIns找插件，sqldrivers 子目录放的就是libqsqlite.dylib、libqmysql.dylib、libqpsql.dylib这些驱动库。

但是注意：如果你是在开发阶段直接双击运行编译出的可执行文件，而不是打包成 .app，那 Qt 去哪个目录找插件就得靠编译时的路径。Qt 官方安装包在 Mac 上默认把插件放在/Users/你的用户名/Qt/版本号/macos/plugins/这类目录里。可执行文件一般会带一个编译好的绝对路径，所以开发机上通常能找到。

问题来了：一旦你把程序复制到别的目录，或者打包成 .app 后没有把插件按正确相对路径放进去，Qt 就找不到驱动插件了。这是 C 类症状最常见的原因——不是驱动文件丢了，而是程序换了个地方，相对路径对不上了。

2.2 DYLD 与 SIP：Mac 上改库路径为什么那么难

Windows 下 Dll 加载论顺序：可执行文件目录、系统目录、PATH 环境变量目录，逻辑简单直接。Mac 上完全不是这么回事，动态库通过install_name记录自己的身份和依赖关系，程序启动时用dyld（动态链接器）按install_name去寻找依赖库。

macOS 10.11 之后引入了 SIP（System Integrity Protection），它对DYLD_LIBRARY_PATH这类环境变量做了大量限制。简单说：你在终端里export DYLD_LIBRARY_PATH=xxx想帮 Qt 找到 MySQL 库，大概率根本无效，尤其是对受保护的系统和系统自带的二进制生效有限，对从 Xcode 跑起来的 app 也经常不起作用。

这就是很多人照着 Windows 时代的经验改环境变量后抓狂的原因。在 Mac 上，靠环境变量“帮忙找库”这条路基本被堵死，正确做法只有两个：要么把依赖库的绝对路径写进驱动插件本身，要么用@rpath/@executable_path这类相对路径让程序自动定位，要么直接把库拷到系统默认搜索目录（但不推荐，污染系统）。

2.3 为什么 QSQLITE 总在，其他驱动总不在

SQLite 驱动几乎是所有平台上的“幸存者”，这是因为它依赖的东西太少了。libqsqlite.dylib 内部直接集成了 SQLite 的实现（或者只依赖系统自带的基础库），不需要额外找第三方客户端。反观 libqmysql.dylib，它要工作必须找到 MySQL 的客户端库 libmysqlclient.dylib，libqpsql.dylib 则必须找到 libpq.dylib。

这些第三方客户端库往往不在系统默认搜索路径里。你是通过 Homebrew 装的 MySQL？那库在/opt/homebrew/opt/mysql-client/lib（Apple Silicon）或者/usr/local/opt/mysql-client/lib（Intel）下；你是下载官方 dmg 装的？那库在/usr/local/mysql/lib。这些路径 dyld 默认不知道，插件加载时一依赖解析失败，整个插件就被丢弃，剩下的驱动列表里自然只有 QSQLITE。

所以“只有 QSQLITE”这件事本身就是线索：Qt 没问题，你的开发库路径配置有问题。

3. 我的排查链路：从空驱动列表到定位缺失依赖

现在进入正题。我把自己当时完整排查的过程拆开来讲，每一步都有明确的命令和目的，你可以直接照着敲。这套链路在 Mac 平台上基本是通用的，不管你是 Qt 5 还是 Qt 6。

3.1 第一步：确认 Qt 到底去哪里找插件

先不要急着改代码。第一步是搞清楚你当前这个 Qt 环境实际是从哪个目录加载插件的。

在工程里写个最小测试，打印这两条信息：

#include <QCoreApplication> #include <QDebug> #include <QSqlDatabase> #include <QLibrary> int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); qDebug() << "Plugin paths:"; for (const QString &path : QCoreApplication::libraryPaths()) { qDebug() << " " << path; } qDebug() << "Available drivers:" << QSqlDatabase::drivers(); return 0; }

libraryPaths()会列出 Qt 当前搜索插件时扫描的目录列表。正常情况下应该包含 Qt 安装目录下的plugins路径。如果这个列表里压根没有 sqldrivers 所在的目录，那你需要的不是修驱动，而是让你的应用能找到插件目录。

除了用代码打印，编译期也可以用 qmake 或者 CMake 的变量查到插件目录：

# 如果是 qmake 工程 qmake -query QT_INSTALL_PLUGINS # 如果是 CMake，可以在 CMakeLists.txt 里输出 message(STATUS "Qt plugins dir: ${QT_INSTALL_PLUGINS}")

我遇到过一次很无语的情况：某版本的 Qt 动态库编译时用的插件路径指向了一个不存在的旧版本目录，导致libraryPaths()里扫出来的目录里啥都没有。这种就属于环境安装混乱，重装对应版本的 Qt 比手动改路径更省事。

3.2 第二步：检查插件文件本身是否存在

确认了搜索路径之后，直接去那个目录看驱动文件。以 Qt 6 为例，插件目录通常长这样：

ls -l ${QT_INSTALL_PLUGINS}/sqldrivers/

正常至少应该有：

libqsqlite.dylib
libqmysql.dylib（如果你安装了 MySQL 相关组件）
libqpsql.dylib（如果是 PostgreSQL）

如果你连 libqmysql.dylib 这个文件都没有，问题就非常清晰了：你当前这个 Qt 构建根本没有包含 MySQL 驱动插件。这时候有两条路：

回 Qt 安装器里把对应组件补装上（如果用的是官方安装包）；
从源码单独编译这个驱动插件，我后面单独讲。

如果文件存在但还是加载不了，那就进入下一步，检查依赖链。这一步才是最考验人的地方。

3.3 第三步：用 otool 检查依赖链

macOS 上检查动态库依赖的神器是otool，它的功能对标 Linux 下的ldd。对插件执行：

otool -L ${QT_INSTALL_PLUGINS}/sqldrivers/libqmysql.dylib

输出会列出这个插件所有依赖的动态库路径，类似：

libqmysql.dylib: @rpath/Qt6Sql.framework/Versions/A/Qt6Sql @rpath/Qt6Core.framework/Versions/A/Qt6Core /usr/local/mysql/lib/libmysqlclient.21.dylib /usr/lib/libSystem.B.dylib

看到最后那个/usr/local/mysql/lib/libmysqlclient.21.dylib就要瞪大眼睛了：这个路径在 dyld 加载时被写死了。如果你的 MySQL 客户端库不在这条路径上，dyld 就会加载失败，整个插件被丢弃。

验证这个判断可以直接执行：

# 手动确认路径是否存在 ls -l /usr/local/mysql/lib/libmysqlclient.21.dylib # 或者用 dyld_info 看绑定信息（macOS 13+） dyld_info -dependents ${QT_INSTALL_PLUGINS}/sqldrivers/libqmysql.dylib

如果路径不存在，恭喜你，根因找到了。

3.4 第四步：用 install_name_tool 修正依赖路径

根因确定以后，有两个思路。第一个思路是让插件去找正确位置的库，第二个思路是把库文件放到插件找的那个位置。我更推荐前者，因为改库的搜索路径是持久化的修改，而不是靠手动复制文件维持。

以我当时的 MySQL 为例，我用的库在/opt/homebrew/opt/mysql-client/lib/libmysqlclient.dylib，而插件里写死的是/usr/local/mysql/lib/libmysqlclient.21.dylib。执行：

cd ${QT_INSTALL_PLUGINS}/sqldrivers/ sudo install_name_tool -change \ /usr/local/mysql/lib/libmysqlclient.21.dylib \ /opt/homebrew/opt/mysql-client/lib/libmysqlclient.dylib \ libqmysql.dylib

-change参数的意思是把旧路径替换成新路径。改完之后再跑一次otool -L确认变更生效。然后重新运行你那个最小测试程序，看看drivers()里是不是多出了 QMYSQL。

这里有几个很实际的注意点：

改完之后插件文件的修改日期会变，dyld 不会因此拒绝加载，但如果你之后对应用做了代码签名，修改后的插件签名会失效，第三方库也一样，需要在最后统一重新签名，这一点后面讲部署时单独展开。
有些库版本名不一样，比如老版本叫libmysqlclient.18.dylib，新版本叫libmysqlclient.21.dylib，你替换的目标路径要和实际存在的文件严格一致。拷文件的时候建议用ln -s建个软链，或者直接复制真实文件，别拷个空链接过去。
如果改了路径但库版本 API 不兼容，驱动能加载但连接时会报函数找不到之类的崩溃。所以如果切换了客户端库大版本，强烈建议连驱动插件一起重新编译，不要只改路径硬顶。

3.5 第五步：善用 QT_DEBUG_PLUGINS 环境变量

如果你不想一上来就用 otool 逐个检查，可以先用 Qt 自带的调试开关看加载日志。在终端里：

QT_DEBUG_PLUGINS=1 ./YourApp

这个环境变量会让 Qt 在加载每个插件时打印详细的调试信息，包括：

找到哪些候选插件路径
对每个插件文件尝试加载
加载失败的具体原因（通常包含 dyld 的报错）

可视化效果非常惊人：你能直接看到 Qt 尝试加载 libqmysql.dylib 失败时那一串 dyld 错误，比你自己猜半天强得多。我后来的习惯是：一遇到插件相关的问题，先开这个开关，再决定要不要动用 otool。

4. 分数据库驱动的修复方案：MySQL、PostgreSQL、SQLite 三大场景

前面是通用排查链路，这一节我按数据库类型把大家经常踩到的坑分别过一遍。不同的客户端库，依赖链、编译方式和部署策略都差得很远。

4.1 MySQL：libmysqlclient 的路径是最大痛点

MySQL 是 Mac 平台上 Qt 驱动加载失败的重灾区，主要原因是 MySQL 的官方 C 客户端库安装方式太五花八门。

不管你是用什么方式装的 MySQL，最终只需要确认一件事：找到libmysqlclient.dylib（老版本可能是libmysqlclient.18.dylib、libmysqlclient.21.dylib），然后用前面说的install_name_tool -change把插件里写死的路径改成实际存在的路径。

如果你用的 MySQL 是通过 Homebrew 安装的mysql-client包，实际库通常在这里：

# Apple Silicon（M1/M2/M3/M4） /opt/homebrew/opt/mysql-client/lib/libmysqlclient.dylib # Intel Mac /usr/local/opt/mysql-client/lib/libmysqlclient.dylib

如果用的是官方 dmg 安装包，路径通常是：

/usr/local/mysql/lib/libmysqlclient.21.dylib

需要注意的一点是：Homebrew 装的 mysql-client 库通常以 unversioned 的libmysqlclient.dylib和一个带版本号的符号链接形式存在。你在install_name_tool -change的时候，目标路径最好指向带完整版本号的那个真实文件，而不是软链，否则之后签名和部署时偶尔会出现奇怪的问题。

另外一个深坑：MySQL 老版本客户端库依赖libssl，如果你系统的 OpenSSL 路径和库编译时不一致，即使 libmysqlclient 找到了，它内部再去找 libssl 时也可能失败。这种情况 otool 检查 libmysqlclient.dylib 本身就能发现，同样用install_name_tool处理。

4.2 PostgreSQL：libpq 的依赖问题更隐蔽

PostgreSQL 的 Qt 驱动依赖libpq.dylib。libpq 和 libmysqlclient 有一个显著区别：libpq 的依赖树通常更深，它经常依赖：

libssl.dylib/libcrypto.dylib（OpenSSL 相关）
libldap.dylib
libkrb5.dylib
libpq本身

也就是说你修好了插件到 libpq 的路径，下一步 libpq 内部可能又找不到 OpenSSL 了，得顺着依赖树一层一层往下捋。这就是为什么我强烈建议你直接用otool -L顺着整条链检查，而不是只盯着最顶上那一层。

PostgreSQL 的库一般在这里：

# Homebrew /opt/homebrew/opt/postgresql@15/lib/libpq.dylib /usr/local/opt/postgresql@15/lib/libpq.dylib # 官方安装器（postgres.app 等） /Applications/Postgres.app/Contents/Versions/15/lib/libpq.dylib

libpq 这种依赖树很深的库，手工改路径会非常痛苦。我个人的经验是：PostgreSQL 驱动尽量别用 Qt 编译好的现成插件，直接用源码自己编译驱动，并在 CMake 或 qmake 里指定 libpq 的路径。这样生成的插件在编译阶段就把路径写对了，依赖解析时更干净。

4.3 SQLite：系统自带版本太老，也可能成为问题

SQLite 驱动虽然“经常在线”，但也不是完全没有坑。Qt 自带的 libqsqlite.dylib 默认是编译进 Qt 的 SQLite 功能的，它在运行时可能走系统自带的/usr/lib/libsqlite3.dylib，而 macOS 自带的 SQLite 版本往往比较保守，部分新特性不可用。

如果你只是做简单的 key-value 存储、本地缓存，那系统自带的 SQLite 完全够用，根本不用折腾。但如果你依赖较新的 SQLite 特性（比如STRICT表、某些新窗口函数），还是建议你确认一下 Qt 实际加载的 SQLite 版本：

SELECT sqlite_version();

如果你需要带自定义扩展的 SQLite 驱动，最好的方式是直接从 Qt 源码编译 SQLite 驱动插件，把 SQLite 源码一起编进去。这个后面讲编译驱动时统一说。

4.4 直接源码编译驱动插件：一劳永逸的方案

如果你的客户端库路径实在太乱，或者 Qt 安装包压根没带某个驱动，最彻底的办法是从源码单独编译你需要的驱动插件。用 Qt 6 + CMake 的项目来说，你不需要编译整个 Qt，只要你本地有 Qt 的源码包（可以从官方源码下载你对应版本），就能单独编 sqldrivers 子模块。

以编译 MySQL 驱动为例，核心思路是在 CMake 配置时指定 MySQL 插件：

git clone --branch v6.5.0 --depth 1 https://github.com/qt/qtbase.git cd qtbase/src/plugins/sqldrivers cmake -S . -B build-mysql \ -DCMAKE_PREFIX_PATH=/path/to/qt \ -DCMAKE_BUILD_TYPE=Release \ -DQt6Sql_DIR=/path/to/qt/lib/cmake/Qt6Sql \ -DMySQL_INCLUDE_DIR=/opt/homebrew/opt/mysql-client/include \ -DMySQL_LIBRARY=/opt/homebrew/opt/mysql-client/lib/libmysqlclient.dylib \ -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"

编译完成之后，把生成的libqmysql.dylib复制到 Qt 的插件目录里，替换掉原来的文件：

cp build-mysql/qsqlmysql/libqmysql.dylib ${QT_INSTALL_PLUGINS}/sqldrivers/

源码编译的好处非常直接：编译期就通过install_name把客户端库的真实路径写进插件了，不会再出现“插件在这里但依赖的库不在”这种割裂问题。缺点是需要你有 CMake 相关经验，对刚入门的朋友来说门槛稍高。

但如果你的应用本身不做裁剪、不是对体积敏感的产品，这一点成本几乎可以忽略，我觉得值得投入一天时间把编译环境过一遍。

5. 部署阶段才是真正的考试：macdeployqt、rpath 与签名

好多人在开发机上一切正常，一旦打包给同事或者准备上架分发，驱动又开始 not loaded。这个现象几乎可以肯定是部署环节丢了三样东西之一：插件目录、第三方库、签名信息。开发阶段解决了加载问题，部署阶段你得重新建立一遍“程序在新地点怎么找到驱动”的规则。

5.1 macdeployqt 能替你做什么，不能替你做什么

Qt 官方部署工具macdeployqt的主要职责是把 Qt 相关框架和 Qt 自带插件复制进 .app bundle 里。它对 Qt 自家的库处理得挺好，但你用的 MySQL 客户端库 libmysqlclient、PostgreSQL 的 libpq，它通常帮不上忙。因为这些库属于第三方依赖，不在 Qt 的“管辖范围”内。

所以基本流程是这样：

# 先构建出 .app cmake --build build --target YourApp # 拷贝 Qt 依赖和 Qt 插件 macdeployqt YourApp.app -verbose=2

-verbose=2可以让你看到它处理了什么。执行后你会发现YourApp.app/Contents/PlugIns/sqldrivers/下自动出现了 libqsqlite.dylib 等驱动文件。

但如果你只做了这一步就发给别人，大概率还是不行——因为 libqmysql.dylib 指向的 libmysqlclient 并不在 app 里。需要手动把客户端库复制进去，并修正路径。

5.2 手动补齐第三方库的完整步骤

这里的标准套路是把第三方库复制到Contents/Frameworks目录下，然后用install_name_tool把引用路径改成@rpath形式的动态查找路径。

以 MySQL 为例，完整命令序列如下：

# 1. 复制客户端库到 app 内部 mkdir -p YourApp.app/Contents/Frameworks cp /opt/homebrew/opt/mysql-client/lib/libmysqlclient.21.dylib \ YourApp.app/Contents/Frameworks/ # 2. 修改库自身的安装名（install name id） install_name_tool -id \ @rpath/libmysqlclient.21.dylib \ YourApp.app/Contents/Frameworks/libmysqlclient.21.dylib # 3. 修改驱动插件所引用的路径 install_name_tool -change \ /opt/homebrew/opt/mysql-client/lib/libmysqlclient.21.dylib \ @rpath/libmysqlclient.21.dylib \ YourApp.app/Contents/PlugIns/sqldrivers/libqmysql.dylib

@rpath是一个占位符，真正的值来自可执行文件的 LC_RPATH 列表。你需要在可执行文件上添加一个 rpath，让它知道去哪里找@rpath指向的库：

install_name_tool -add_rpath @executable_path/../Frameworks \ YourApp.app/Contents/MacOS/YourApp

@executable_path表示可执行文件所在目录，../Frameworks正好指向Contents/Frameworks。这样一来，程序启动时 dyld 会顺着 rpath 在 app 内部找到客户端库，不再依赖开发机上的绝对路径。

验证是否配置正确，一个很实用的命令是：

dyld_info -dependents YourApp.app/Contents/MacOS/YourApp

这个命令会列出可执行文件所有依赖的最终解析路径。如果你看到指向/opt/homebrew/...这种绝对路径的条目，说明还有库没被挪进 app；如果看到@rpath/...开头的，说明路径机制已经统一了。

5.3 签名之后驱动又崩了？这是正常的

Mac 的代码签名不仅仅是安全校验，它会把二进制里所有 install_name 相关的内容连同整个文件的哈希一起锁定。说白了，你之前用 install_name_tool 改过的东西，在签名之后 Apple 会重新计算并固化，但 dyld 不会因为 path 变了就拒绝，它只是要求“已签名的文件没有被篡改”。

所以顺序很重要：先改路径和复制库，最后再统一签名。如果你改了先签名，后续再碰 install_name，签名就会失效，程序启动会提示“无法验证开发者”。

如果你不做正式分发，可以用 ad-hoc 签名，开发阶段也够用：

codesign --force --deep --sign - YourApp.app

如果你要分发，得用 Developer ID 证书，并且还要面对 Hardened Runtime 的问题。Hardened Runtime 开启后，默认会禁用加载任意路径的动态库，但通过正确的 rpath 机制加载 app 内部的库是没有问题的，真正麻烦的是部分第三方库在签名验证上不够严格。

我这里给一个实际经验：Hardened Runtime 下，如果应用程序要加载的 dylib 有自己的签名问题，dyld 会报一个“Library not loaded: ... reason: no suitable image found”错误。解决方案不是关闭 Hardened Runtime，而是把库文件用你的证书重新签名一次：

codesign --force --sign "Developer ID Application" \ YourApp.app/Contents/Frameworks/libmysqlclient.21.dylib

库签名跟随主程序一遍签完，很多奇怪的问题就消失了。

5.4 发布前的自检清单

我后来总结了一套发布前固定检查流程，每次都按这个顺序过一遍，能提前发现很多驱动加载问题：

从干净环境（另一台没有装开发库的 Mac）测试，或者至少把DYLD_FALLBACK_LIBRARY_PATH清掉再测；
QT_DEBUG_PLUGINS=1 ./YourApp.app/Contents/MacOS/YourApp，看插件加载日志是不是还有红字；
otool -L YourApp.app/Contents/PlugIns/sqldrivers/*.dylib，确认所有依赖路径都以@executable_path、@rpath或系统路径开头；
codesign --verify --deep --strict YourApp.app，确认签名完整；
双击启动 .app，而不是在终端里手动执行，因为双击情境下 dyld 的环境和开发状态完全不同。

这一步是真的检验部署成果的关键。很多开发者在终端里跑得通，双击就崩，本质就是环境变量和绝对路径没转移到 app 内部。

6. 从源码出发的备选思路：静态链接驱动插件

如果你的应用对分发复杂度容忍度很低，或者客户端库的依赖链实在太乱，还有一个思路值得考虑：把驱动插件静态编译进主程序。

Qt 的插件系统允许你用静态插件的方式把驱动直接编进可执行文件里。这样程序启动时就不需要再去文件系统找libqmysql.dylib了，驱动代码已经在进程内部。部署时也不用担心插件目录丢失、依赖库缺失这些烦心问题。

使用静态插件的要点是：

你用的 Qt 本身必须是静态编译版本（这个是最关键的瓶颈，因为官方下载的 Qt 基本上全是动态库版本）；
在CMakeLists.txt或.pro文件里链接插件：

find_package(Qt6 REQUIRED COMPONENTS Sql) # 以 MySQL 为例 find_package(Qt6 COMPONENTS Sql QMysqlPlugin) target_link_libraries(YourApp PRIVATE Qt6::Sql Qt6::QMysqlPlugin)

告诉 Qt 你要静态加载插件：

#include <QtPlugin> Q_IMPORT_PLUGIN(QMysqlDriverPlugin)

静态编译这条路确实能根治很多部署问题，但代价是你的应用体积会变大，且如果未来要换 Qt 版本或者换客户端库版本，得重新编译一次整个静态 Qt。它更像是一个权衡之后的取舍，而不是默认推荐方案。如果你只是要快速交付一个内部工具，动态插件方案做好路径处理完全够用。

最后再补充几个实战体会

这一段时间折腾下来，我最深的感受是：Mac 平台下 Qt SQL 驱动加载问题，80% 都不是 Qt 本身的问题，而是 macOS 的动态库路径机制和第三方客户端库安装环境的匹配问题。与其遇到一次修一次，不如把思路固定成一套流程：先看插件文件是否存在，再用 otool 检查依赖链，再用 install_name_tool 修正路径，最后部署时把第三方库一并收进 app，统一签名。这套流程你从头到尾走一遍之后，再看到 “QMYSQL driver not loaded”，第一反应就不是崩溃，而是打开QT_DEBUG_PLUGINS=1看日志，然后顺着依赖链一路往下杀了。

另外一个值得养成的习惯是：更换电脑或版本升级后，第一件事把你工程里所有动态库路径用otool扫一遍，有一份依赖清单，比到时候临时救火可靠得多。坑踩过一次就够了，我把这套路径整理出来，希望你能少走我走过的弯路。