简介面向在32位环境下使用QT5.13开发桌面应用、需要接入Oracle 11g数据库的C开发者尤其是采用MSVC编译工具链的项目团队。包内提供已编译好的QOCI驱动、OCI客户端库与头文件以及编译和运行阶段所需的动态库与导入库可省去自行编译驱动时反复排查依赖的麻烦。资源共51个文件以29个h头文件、10个dll动态库、7个lib导入库为主另有少量sym符号文件与1个说明txt压缩包约60.63MB涵盖从编译到部署的完整链路。已有364人学习下载说明该组合在QT连接Oracle的实际场景中确有需求。读者可据此完成QSqlDatabase的驱动配置理解MSVC与MinGW编译产物不兼容的边界并借助说明文件快速定位库文件放置位置减少环境搭建与运行时报错排查的时间成本。1. Qt5.13 连 Oracle11 的 32 位驱动包为什么它值得单独留一份手上有个老工控上位机要维护Qt5.13 MSVC2017 32 位数据库是 Oracle11g客户现场机器不让装完整客户端只允许丢几个 DLL 进去。这种场景下最省事的做法不是自己编译 QOCI 插件而是直接拿一份已经配好的 32 位驱动依赖包。这份资源就是干这个的把 Qt5.13 连接 Oracle11 所需的 QOCI 驱动插件和 Oracle 客户端运行库按 32 位架构打包在一起省掉 qmake、nmake、oci.h 路径、MSVC 版本对齐这一整串折腾。适合谁适合还在维护 Qt5 老项目、目标机是 32 位 Windows、又不想在每台机器上装 Oracle Client 的从业者。新手能照着把连接跑通熟手更关心的是位数、版本、环境变量这几个边界后面几章会逐个拆。2. 先搞清 QOCI 的加载链路驱动、客户端、位数三件事Qt 连 Oracle 不是 Qt 自己会讲 Oracle 协议它靠的是 QOCI 插件去调 Oracle 的 OCI 接口OCI 接口再落到 Oracle 客户端运行库上。所以一条完整的链路是你的程序 → QtSql → qsqloci 插件 → oci.dll → Oracle 客户端 DLL。这条链上任何一环位数不对、版本不对表现都是「驱动加载失败」或者「连接直接返回空」而且报错信息往往很含糊这就是很多人卡住的地方。2.1 为什么 32 位程序必须配 32 位驱动和 32 位客户端Windows 的进程位数决定了它能加载的 DLL 位数32 位进程只能加载 32 位 DLL没有例外。Qt5.13 的 MSVC2017 32 位套件编译出来的 exe 是 32 位那么 qsqloci.dll 必须是 32 位它依赖的 oci.dll 也必须是 32 位。常见翻车是开发机上装的是 64 位 Oracle 客户端环境变量 PATH 里也是 64 位的 oci.dll程序一跑就提示 QOCI driver not loaded。原因不是插件没放对而是插件找到了、但它去加载 oci.dll 时位数不匹配加载器直接拒绝。判断位数别靠猜用工具看。Dependency Walker 或者 dumpbin 都行我一般用 dumpbin 快速确认# 在 VS 开发者命令行里执行确认 DLL 的机器类型 dumpbin /headers qsqloci.dll | findstr machine dumpbin /headers oci.dll | findstr machine输出里出现14C machine (x86)就是 32 位8664 machine (x64)是 64 位。两个文件必须都是 x86。这一步看着笨但能省掉后面半小时的瞎试。2.2 插件目录结构和 Qt 的搜索顺序Qt 找插件有一套固定顺序先看程序目录下的plugins/sqldrivers再看QT_PLUGIN_PATH环境变量指向的目录最后看 Qt 安装目录里的plugins/sqldrivers。部署时最稳的做法是把插件放到 exe 同级的sqldrivers子目录然后用QCoreApplication::addLibraryPath或者直接在代码里指定别指望开发机能跑现场就能跑。典型的部署结构长这样YourApp/ YourApp.exe Qt5Core.dll Qt5Sql.dll sqldrivers/ qsqloci.dll oci.dll oraociei11.dll orannzsbb11.dll注意oci.dll和oraociei11.dll放在 exe 同级不要塞进sqldrivers里。插件加载 oci.dll 时走的是系统 DLL 搜索路径exe 所在目录优先级很高放同级最省心。oraociei11.dll是 Instant Client 的「大包」包含大部分 OCI 功能orannzsbb11.dll是网络加密相关缺了它某些连接方式会报 ORA-12154 之外的怪错。2.3 版本对齐Qt5.13、MSVC2017、Oracle11 三者的兼容边界Qt5.13 官方预编译包用的是 MSVC2017如果你的 Qt 是 MinGW 版本这份 MSVC 编译的插件直接不能用ABI 不兼容必须换 MSVC 套件或者自己用 MinGW 重编。Oracle11g 客户端这边32 位 Instant Client 的版本号要和 oci.dll 对得上混用不同小版本的 oci.dll 和 oraociei11.dll 会出现「找不到符号」或者连接时崩溃。血泪经验是驱动包里的 DLL 成套用别从别处抓一个「看起来更新」的 oci.dll 替换进去版本错配的崩溃往往发生在连接建立之后排查成本极高。3. 把驱动接进项目从文件落位到连接跑通这一章是能直接抄的部分。假设你拿到的是解压后的驱动包里面应该有qsqloci.dll和一组 Oracle 客户端 DLL。目标是把它们放到正确位置让一个最小的 Qt 程序能连上 Oracle11。3.1 文件落位与 qsqloci.dll 的放置先确认你的 Qt 套件是msvc2017 32bit。在 Qt Creator 的「工具 → 选项 → Kits」里看编译器或者看 Qt 安装目录名带msvc2017且是 32 位就对了。然后把qsqloci.dll复制到 Qt 安装目录的plugins/sqldrivers下同时也在你的构建输出目录exe 旁边建一个sqldrivers放一份。开发阶段两份都放避免调试时加载到旧插件。# 假设 Qt 安装在 C:\Qt\Qt5.13.2\5.13.2\msvc2017 # 驱动包解压在 D:\pkg\qoci32 copy D:\pkg\qoci32\qsqloci.dll C:\Qt\Qt5.13.2\5.13.2\msvc2017\plugins\sqldrivers\ mkdir build\debug\sqldrivers copy D:\pkg\qoci32\qsqloci.dll build\debug\sqldrivers\Oracle 客户端 DLLoci.dll、oraociei11.dll、orannzsbb11.dll等复制到 exe 同级目录。如果你在 Qt Creator 里直接运行exe 在build-xxx-Debug\debug\下就放那里。逻辑说明插件目录决定 Qt 能不能找到 QOCI 驱动exe 同级决定插件能不能找到 oci.dll两处缺一不可。3.2 用 QSqlDatabase 验证驱动是否被识别先别急着连库第一步是确认 Qt 看见了 QOCI 驱动。写个最小程序打印可用驱动列表#include QCoreApplication #include QSqlDatabase #include QDebug int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); // 打印 Qt 实际搜索的插件路径排查时非常有用 qDebug() libraryPaths: QCoreApplication::libraryPaths(); // 列出当前可用的 SQL 驱动 const QStringList drivers QSqlDatabase::drivers(); qDebug() drivers: drivers; if (!drivers.contains(QOCI)) { qDebug() QOCI 未加载检查 qsqloci.dll 位数和依赖; return 1; } return 0; }QSqlDatabase::drivers()返回的是驱动名字符串列表出现QOCI才说明插件被成功加载。如果列表里没有先看libraryPaths打印出来的路径里有没有你放插件的目录再看qsqloci.dll的依赖是否齐全。参数说明libraryPaths是 Qt 当前生效的插件搜索路径addLibraryPath可以在运行时追加但要在创建任何数据库连接之前调用。3.3 连接字符串与字符集参数怎么设驱动识别之后连接本身反而简单。关键是连接字符串里的服务名写法和字符集。Oracle11 的 Instant Client 对NLS_LANG敏感中文乱码十有八九是这里没设。#include QSqlDatabase #include QSqlError #include QSqlQuery #include QDebug bool connectOracle() { QSqlDatabase db QSqlDatabase::addDatabase(QOCI); // 主机:端口/服务名服务名不是 SID写错会报 ORA-12505 db.setHostName(192.168.1.10); db.setPort(1521); db.setDatabaseName(ORCL); // 这里填服务名 db.setUserName(app_user); db.setPassword(your_password); if (!db.open()) { qDebug() open failed: db.lastError().text(); return false; } QSqlQuery q(db); q.exec(SELECT 1 FROM DUAL); if (q.next()) { qDebug() connected, value q.value(0).toInt(); } return true; }逻辑说明setDatabaseName在 QOCI 下对应的是服务名Service Name不是 SID。很多老文档写 SID连不上就报 ORA-12505这是高频坑。setPort不设默认走 1521。字符集方面在程序启动前设置环境变量NLS_LANGSIMPLIFIED CHINESE_CHINA.AL32UTF8或者在系统环境变量里配好否则查出来的中文可能是问号。注意这个变量要在进程启动时生效程序里用qputenv设置要在加载 OCI 之前稳妥做法是在main最开头设置。4. 避坑与排查五条现场踩出来的记录这一章全是现象、原因、解决三段式都是这类 32 位驱动部署里反复出现的。4.1 现象提示 QOCI driver not loaded但文件明明在原因通常有三个插件位数不对、插件依赖的 oci.dll 找不到、或者 Qt 加载了另一个路径下的旧插件。先确认qsqloci.dll是 x86再确认 exe 同级有 32 位oci.dll最后看libraryPaths打印的路径顺序可能开发机 Qt 目录里有个 64 位插件抢先被加载。解决清掉错误路径下的插件只保留一份正确的用dumpbin逐个确认位数。4.2 现象连接时报 ORA-12505 或 ORA-12514原因setDatabaseName填了 SID 而不是服务名或者服务名拼错。ORA-12505 是监听器不认识你给的 SIDORA-12514 是服务名没注册。解决找 DBA 确认lsnrctl status里注册的 Service Name填进setDatabaseName。如果对方只给 SID可以试(DESCRIPTION(ADDRESS(PROTOCOLTCP)(HOSTx)(PORT1521))(CONNECT_DATA(SIDxxx)))这种完整描述符写法。4.3 现象程序启动直接崩溃没有任何 Qt 报错原因混用了不同版本的 Oracle 客户端 DLL比如oci.dll是 11.2 的oraociei11.dll是别的版本加载时符号解析失败。这种崩溃发生在进程初始化阶段调试器都来不及拦。解决整套 DLL 来自同一个驱动包不要单独替换其中某一个。用dumpbin /dependents oci.dll看它依赖哪些 DLL确保都在。4.4 现象查询中文全是乱码或问号原因NLS_LANG没设或设错客户端字符集和数据库字符集不匹配。解决进程启动前设NLS_LANGSIMPLIFIED CHINESE_CHINA.AL32UTF8如果数据库是 ZHS16GBK则设SIMPLIFIED CHINESE_CHINA.ZHS16GBK。注意这个变量影响的是客户端转换行为设错方向比不设更糟先查SELECT * FROM NLS_DATABASE_PARAMETERS WHERE PARAMETERNLS_CHARACTERSET确认库的字符集。4.5 现象开发机能连拷到现场机器就连不上原因现场机器缺 VC 运行库或者 PATH 里有另一个 Oracle 客户端的 oci.dll 抢先被加载。解决装对应版本的 VC 运行库MSVC2017 对应 vc141并在部署包里确保 exe 同级 DLL 优先。可以用 Process Monitor 过滤oci.dll的加载路径一眼看出实际加载的是哪个文件这招比猜快得多。5. 进阶把驱动包做成可复现的部署清单到这一步连接已经能跑但真正省事的是把「哪些文件、放哪里、什么环境变量」固化成一份可复现的清单下次换机器直接照抄。我一般会在项目根目录放一个deploy/目录里面按目标结构摆好文件再配一个批处理做校验。echo off REM 校验部署目录里关键 DLL 的位数全部应为 x86 set DUMPBINC:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x86\dumpbin.exe for %%f in (qsqloci.dll oci.dll oraociei11.dll) do ( echo %%f %DUMPBIN% /headers %~dp0%%f | findstr /i machine ) REM 设置客户端字符集按实际库字符集调整 set NLS_LANGSIMPLIFIED CHINESE_CHINA.AL32UTF8这段批处理的逻辑dumpbin路径按你本机 VS 安装调整Hostx64\x86表示用 64 位宿主工具分析 32 位目标输出里只留 machine 行方便肉眼比对。NLS_LANG在这里设只对当前命令行会话生效正式部署还是写进系统环境变量或者程序启动时qputenv。几个值得固化的参数边界列成表更清楚项目正确取值错了会怎样插件位数x86驱动加载失败oci.dll 位数x86插件加载 oci 失败setDatabaseName服务名ORA-12505/12514NLS_LANG与库字符集一致中文乱码Qt 套件msvc2017 32bit插件 ABI 不兼容还有一个验证技巧在程序里加一段启动自检把QSqlDatabase::drivers()、libraryPaths()、NLS_LANG当前值一起打到日志里。现场出问题时让运维把日志发回来比远程连过去猜快得多。这套自检我后来在每个 Qt 数据库项目里都保留成本几行代码省下的是整晚的排查。从那以后我每次交付带 Oracle 连接的 Qt 程序都会先在一台干净的 32 位虚拟机上按部署清单走一遍确认位数、字符集、运行库三样都对再发到现场。这份驱动包的价值不在于文件本身多神秘而在于它把版本和位数这对最容易错配的东西固定住了剩下的就是照清单落位。希望帮到你。本文还有配套的精品资源点击获取