1. 在 Windows 10 上编 Qt 5.15.12 的 32 位动态库:代码开发工具错位比代码错更常见
在 Windows 10 上把 Qt 5.15.12 编成 32 位动态库,很多人第一反应是找一份 configure 命令复制粘贴,跑完却发现 cl.exe 根本不是 x86,或者工程里 QSerialPort 找不到定义。问题往往不在 Qt 源码,而在代码开发工具这一层没摆正:命令行环境、jom、MSVC 工具链、qmake 的 .pro,各管一段,错一段后面全是玄学。这篇面向需要在 Windows 10 上从源码编 32 位 Qt 共享库、或拿到一份 Qt 工程要先把套件和模块跑通的人,按工具链准备、configure 拆参、编译验证、排错、产物确认的顺序走一遍。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具先摆正:x86 命令行、jom 与 .pro 模块
2.1 为什么必须用 x86 Native Tools Command Prompt
Qt 的 configure 里有一个参数叫 -platform win32-msvc,名字里带 win32,很容易让人以为写了它就是 32 位。实际不是。这个参数只决定用哪套工具链类型,也就是 MSVC,不决定目标位数。真正决定 cl.exe 是 32 位还是 64 位的,是你打开的那个命令行窗口。
在普通 cmd 里,PATH 里挂着的 cl.exe 可能是 x64 版本;在 x64 环境下即便 configure 写了 win32-msvc,检测到的 cl.exe 还是 x64 编译器。所以第一步不是进源码目录,而是从开始菜单找到 x86 Native Tools Command Prompt for VS 打开。这个窗口会把环境变量指向 x86 的工具集,后面的 configure 和 jom 都在这个窗口里跑。
一个最小验证动作:在窗口里直接敲 cl,看输出末尾标的目标架构。看到 x86 再往下走,看到 x64 就关掉重开,别在这个窗口里继续折腾。这一步花十秒,能省掉后面编译几个小时才发现产物位数不对的血泪经验。
2.2 jom 放进 PATH 与源码目录的位置
Qt 5.15.12 的源码包解开后是一个大目录,我一般放在纯英文、无空格的路径下,比如 D:\build\qt-everywhere-src-5.15.12。路径里带空格或中文,configure 阶段不一定立刻报错,但后面生成 Makefile、调用工具链时容易出一些看不出根因的失败,能避就避。
jom 是 Qt 生态里常用的并行构建工具,需要单独准备一个目录,比如 D:\build\qt-tools\jom。把它加到 PATH 的最前面:
bat复制cd /d D:\build\qt-everywhere-src-5.15.12
set PATH=D:\build\qt-tools\jom;%PATH%
cd /d 里的 /d 是允许跨盘符切换,源码在 D 盘而当前在 C 盘时必须有它。set PATH=...;%PATH% 是把 jom 目录插到原有 PATH 前面,保证命令行里敲 jom 时优先命中你准备的这份,而不是系统里某个旧版本。这两行建议和后面的 configure 一起写进一个 bat,每次构建前执行,减少手工输入带来的差异。
2.3 先读 .pro:模块清单比源码更能说明问题
拿到一份 Qt 工程,不要先找 exe,也不要急着编译,先找后缀为 .pro 或 CMakeLists.txt 的工程文件。.pro 是最能暴露信息的地方,它直接告诉你这个工程依赖哪些 Qt 模块。一个典型的 .pro 开头长这样:
ini复制QT += core gui widgets
QT += serialport sql
TARGET = TraceSys
TEMPLATE = app
CONFIG += c++11
SOURCES += \
main.cpp \
MainWindow.cpp \
SerialWorker.cpp \
TraceTableModel.cpp
HEADERS += \
MainWindow.h \
SerialWorker.h \
TraceTableModel.h
FORMS += \
MainWindow.ui
逐行看:QT += core gui widgets 是基础模块,界面程序基本都要;QT += serialport sql 说明这个工程要和串口设备、数据库打交道,这两行直接决定你编出来的 Qt 库能不能支撑它。TARGET = TraceSys 是最终 exe 的名字,它不一定等于工程目录名,有人把工程目录改了名,exe 还叫 TraceSys.exe,定位进程和日志时会绕路。TEMPLATE = app 表示产出应用程序,CONFIG += c++11 是编译标准,SOURCES、HEADERS、FORMS 列出源文件、头文件和界面文件。
这里有一个很实际的判断点:如果 .pro 里只写了 QT += core gui widgets,而源码里又出现了 QSerialPort 和 QSqlDatabase,那要么模块被裁剪了,要么是手工 include 了第三方库。缺 serialport 模块时,编译会立刻报 QSerialPort 找不到定义,这不是代码逻辑问题,是工程配置问题。先补上 QT += serialport sql 再查代码错误,能少走半天弯路。
反过来说,这一步也会影响你编 Qt 库时的取舍:工程需要的模块,configure 的 -skip 列表里就不能出现;工程用不到的模块,可以大胆跳过,省编译时间。模块清单先对齐,后面的 configure 才有依据。
3. configure 逐参数拆解:共享库、工具链与模块裁剪怎么定
3.1 完整命令与执行位置
确认命令行是 x86、jom 已进 PATH、源码目录已进入之后,执行 configure。下面是我在 32 位共享库场景下的常用命令:
bat复制cd /d D:\build\qt-everywhere-src-5.15.12
set PATH=D:\build\qt-tools\jom;%PATH%
configure.bat ^
-opensource -confirm-license ^
-shared ^
-platform win32-msvc ^
-mp ^
-opengl desktop ^
-nomake examples -nomake tests ^
-skip qtwebengine -skip qtwebview ^
-prefix D:\build\qt-5.15.12-x86
^ 是 bat 里的续行符,整条命令实际上是一行。执行位置必须在源码根目录,因为 configure.bat 就在那里,它会根据当前目录生成 Makefile 和构建配置。cd /d 和 set PATH 重复一次是有意的:如果这个 bat 是单独双击执行的,前面的窗口状态不会带过来,必须在同一个脚本里重新定位。
命令跑完不要只看最后一行有没有报错,往上翻一翻,确认它检测到的编译器架构、目标平台、安装前缀是不是你想要的。configure 的输出里会明确写出这些信息,这是后面排查的第一手依据。
3.2 许可证与库类型:-opensource、-confirm-license 与 -shared
-opensource -confirm-license 表示使用开源版并跳过许可证交互确认。如果不加 -confirm-license,configure 会停下来等你输入,写在 bat 里就会卡住。这两个参数只解决构建流程,不解决合规问题:如果是在公司内部产品里用 Qt,开源协议对应的义务要自己提前确认清楚,这不是构建参数能覆盖的事。
-shared 明确要的是动态库。Qt 的 configure 在不传这个参数时默认也是 shared,但显式写出来更安全,原因是很多人会从别人的配置里复制粘贴,而别人的配置可能是 static。一旦漏掉这个差异,编出来的是静态库,部署时要么体积失控,要么链接行为完全不同。这种错误不会在 configure 阶段报警,只会在你部署或链接时以另一种形式翻车。
与之相对的是 -static,它会产出静态库。静态库不是不能用,但和动态库是两条部署路线,依赖分发方式、插件加载方式都不一样。这篇文章只走 -shared 这一条,命令里显式写出来,就是为了让后来复制这条命令的人一眼看到关键差异。
3.3 工具链与并行:-platform win32-msvc 与 -mp
-platform win32-msvc 指定使用 MSVC 工具链。再强调一次,这个参数只决定工具链类型,不决定位数;位数由你打开的命令行决定。在 x64 环境下即便写了 win32-msvc,检测到的 cl.exe 还是 x64 编译器,编出来的库自然也是 x64。这就是为什么 2.1 节要先确认命令行环境,参数本身救不了环境错位。
-mp 是开启 MSVC 的多进程编译。它让编译器在编译单个文件时也能并行,配合 jom 的并行构建,能把多核机器的编译时间压下来。这个参数适合核数多、内存足的机器;如果机器内存偏紧,并行度太高会把内存吃满,编译中途被系统杀掉,现象是莫名其怪的中断,而不是明确的编译错误。
-opengl desktop 指定桌面 OpenGL 实现。这个参数和 32 位目标没有直接关系,但如果你的工程用到 Qt Quick 或 OpenGL 相关模块,它会影响链接的库。保持和工程实际需求一致即可,不确定时不要随意改成别的值。
3.4 裁剪与落地:-nomake、-skip 与 -prefix
-nomake examples -nomake tests 表示不编译示例和测试。Qt 源码里 examples 和 tests 数量很大,编它们对产出库没有帮助,只会拉长构建时间。除非你要参考某个示例的源码,否则这两个开关建议保留。
-skip qtwebengine -skip qtwebview 是跳过指定模块。qtwebengine 依赖链重、编译时间长,qtwebview 也常被一起跳过。这里的关键是边界:跳过的模块如果被你的工程依赖,后面编译工程时就会缺头文件或库文件。所以 -skip 列表要和 2.3 节读出来的 .pro 模块清单对一遍,工程用到的模块一个都不能跳。
-prefix D:\build\qt-5.15.12-x86 指定安装路径。这个路径是后面 jom install 的落地位置,也是你最终要加进 PATH 或写进工程套件配置的目录。路径同样建议纯英文、无空格,并且和源码目录分开,源码目录将来可以删,安装目录要长期保留。目录名里带上 x86 是个好习惯,机器上同时存在 x64 版本时不容易拿错。
4. 编译、安装与验证:让代码开发工具真正产出 32 位 DLL
4.1 jom 编译:并行度与失败后的第一反应
configure 成功后,源码根目录会生成 Makefile 一类构建文件,接下来用 jom 编译:
bat复制jom
不带参数时 jom 会用上所有可用核心。机器内存一般、又想留点余量给系统时,可以显式限制并行度:
bat复制jom -j4
-j4 表示同时跑四个编译任务。这个数字不是越大越好:前面 configure 开了 -mp,单个编译任务内部已经会并行,jom 再按全核开,整体并发会翻倍,内存吃紧的机器容易中途卡死或编译进程被杀。遇到没有明确错误信息的中断,先怀疑并行度,把 -j 降下来重跑,而不是去改源码。
jom 失败时会打印第一个出错的文件和命令行。第一反应应该是往上翻,看这个文件属于哪个模块、缺的是哪个头文件,而不是从最后一行报错开始猜。Qt 这种大工程,一个模块失败往往会带出一串后续错误,真正的根因通常在最前面那几条。
4.2 jom install 与目录结构
编译通过后,把产物安装到 configure 时指定的前缀目录:
bat复制jom install
这条命令会按 -prefix D:\build\qt-5.15.12-x86 把 bin、lib、include、plugins 等目录铺开。安装完成后,先别急着写业务代码,花两分钟看一眼目录:bin 下应该有 Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll 等动态库,lib 下是对应的导入库,include 下是头文件。如果 bin 里缺了你在 .pro 里用到的模块对应的 DLL,说明 configure 阶段裁多了,回到 3.4 节对一遍 -skip 列表。
安装路径不要和源码目录混在一起。源码目录将来可能被清理或换版本,安装目录要作为工具链长期存在。机器上如果同时有 x64 的 Qt,两个安装目录的命名要能一眼区分,比如都带上架构后缀,避免工程套件指错。
4.3 用 dumpbin 确认位数,不要靠目录名猜
产物是不是 32 位,不要靠目录名或 configure 参数猜,直接看 DLL 的文件头:
bat复制dumpbin /headers D:\build\qt-5.15.12-x86\bin\Qt5Core.dll | findstr machine
dumpbin 是 MSVC 工具集自带的,在 x86 Native Tools 命令行里可以直接用。/headers 输出 PE 头信息,findstr machine 过滤出目标架构那一行。看到 x86 才算真正落地;看到 x64,说明整个构建是在 x64 环境里跑的,回到 2.1 节重开命令行,清掉构建产物重新 configure。
这一步建议固化成习惯:每次编完库,先 dumpbin 看一眼核心 DLL,再往工程里接。省下的不是一次检查的时间,而是后面工程链接报架构不匹配时,从工程配置一路查到 Qt 库源码的时间。
4.4 让工程找到这份 Qt
库编好了,工程还得能找到它。最直接的方式是把安装目录的 bin 加进 PATH:
bat复制set PATH=D:\build\qt-5.15.12-x86\bin;%PATH%
这样 qmake 和运行时都能命中这份 Qt。工程侧的套件配置里,qmake 路径指向 D:\build\qt-5.15.12-x86\bin\qmake.exe,编译器和调试器仍然用 MSVC 那一套。套件里的 Qt 版本、编译器、调试器三者要对应同一套架构,任何一项指到 x64,都会在链接或运行阶段报出来。
运行时如果提示找不到 Qt5Core.dll,先确认 PATH 里有没有这个 bin 目录,再确认 DLL 的位数和 exe 的位数是否一致。32 位 exe 加载 64 位 DLL 会直接失败,报错信息不一定直白,dumpbin 是更可靠的判断手段。
5. 避坑与排查:五类翻车现场的现象、原因与解法
5.1 编出来的 DLL 是 x64
现象:configure 和 jom 都跑完了,没有明显报错,但用 dumpbin 看 Qt5Core.dll,machine 一栏是 x64。拿去链接 32 位工程时报架构不匹配。
原因:configure 是在 x64 的命令行环境里执行的。-platform win32-msvc 只指定工具链类型,不指定位数,检测到的 cl.exe 是 x64,产物自然也是 x64。这个坑的隐蔽之处在于构建过程完全不报错,只有到使用环节才暴露。
解决:关掉当前窗口,从开始菜单打开 x86 Native Tools Command Prompt for VS,敲 cl 确认输出是 x86,再重新执行 configure 和 jom。构建产物建议清掉重来,不要在旧产物上增量编译,避免混入 x64 的目标文件。
5.2 编译工程时报 QSerialPort 找不到定义
现象:Qt 库编完了,工程一编译就报 QSerialPort 找不到定义,或者提示某个 Qt 模块的头文件不存在。
原因:两种可能。一是 .pro 里少了 QT += serialport,工程配置没把模块引进来;二是编 Qt 库时用了 -skip 把工程需要的模块裁掉了,安装目录里根本没有对应的头文件和库。
解决:先看 .pro,按 2.3 节的方式补齐 QT += serialport sql,重新执行 qmake 再编译。如果 .pro 已经写了还报错,去安装目录的 include 下看有没有对应模块目录,没有就说明库编的时候裁多了,调整 -skip 列表重新 configure。判断顺序很重要:先查工程配置,再查库产物,不要一上来就怀疑源码。
5.3 配置从别处复制,编出来是静态库
现象:部署时发现程序依赖一堆东西,或者链接行为和预期不一致,检查产物发现拿到的是静态库而不是动态库。
原因:configure 命令是从别人的配置里复制来的,别人的场景是 static,命令里带了 -static 或者漏了 -shared。Qt 在不传 -shared 时默认也是 shared,但一旦复制来的命令里显式写了 -static,就会覆盖默认行为。
解决:把 -shared 显式写进命令,并且每次复制配置后逐参数对一遍,重点看 -shared 和 -static 这一对。构建前把这行命令存进 bat,减少手工复制粘贴的机会。这类错误 configure 不会报警,只能在部署或链接阶段发现,提前对参数比事后排查便宜得多。
5.4 -skip 跳过了工程真正依赖的模块
现象:库编译安装都正常,工程编译时报某个模块的头文件或库缺失,而这个模块在源码里确实用到了。
原因:configure 的 -skip qtwebengine -skip qtwebview 是为了省编译时间,但如果工程依赖了被跳过的模块,安装目录里就不会有对应的产物。跳过的模块不会在 configure 阶段报错,只会在工程编译时以缺文件的形式出现。
解决:回到 .pro 或 CMakeLists.txt,把工程实际依赖的模块列出来,和 -skip 列表逐个对照,工程用到的模块从跳过列表里去掉,重新 configure 和编译。裁剪的前提是确认不用,不是看别人跳了也跟着跳。
5.5 公司内部产品直接用 -opensource 的合规盲区
现象:构建本身没有任何报错,库能编出来,程序也能跑,但用在公司内部产品里时,开源协议对应的义务没人确认过。
原因:-opensource 只是选择开源版构建,-confirm-license 只是跳过交互确认,这两个参数解决的是构建流程,不解决使用场景的合规问题。把这套配置直接搬进公司产品,协议义务仍然存在。
解决:在项目早期就把 Qt 的版本、构建参数、使用方式记录清楚,协议义务由负责的人提前确认,不要等到产品发布前才回头补。构建参数能复制,合规判断不能复制,这一条只能自己走一遍。
6. 产物验证与日常习惯:把 32 位这件事钉死
6.1 用一个最小工程验证这份 Qt 真能用
库编完、dumpbin 确认是 x86 之后,我一般会建一个最小工程,把 .pro 里声明的模块真跑一遍,而不是直接接业务代码。工程文件这样写:
ini复制QT += core serialport sql
CONFIG += console c++11
CONFIG -= app_bundle
TARGET = qt32check
TEMPLATE = app
SOURCES += main.cpp
QT += core serialport sql 对应前面 .pro 里用到的模块,CONFIG += console 让它以控制台程序运行,方便看输出。main.cpp 只做两件事:实例化 QSerialPort,列出数据库驱动:
cpp复制#include <QCoreApplication>
#include <QSerialPort>
#include <QSqlDatabase>
#include <QDebug>
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
QSerialPort port; // 能实例化,说明 serialport 模块可用
port.setPortName("COM1");
qDebug() << "serialport ok";
qDebug() << QSqlDatabase::drivers(); // 能列出驱动,说明 sql 模块可用
return 0;
}
把安装目录的 bin 加进 PATH 后执行:
bat复制qmake qt32check.pro
jom
qmake 生成 Makefile,jom 编译。跑起来看到 serialport ok 和驱动列表,说明这份 Qt 的模块是完整的。这一步比直接上业务工程快得多,出问题也容易定位:报 QSerialPort 找不到就是模块缺失,报 DLL 加载失败就是位数或 PATH 问题,边界很清楚。
6.2 把命令固化成 bat,别靠记忆
这套流程里手工输入的地方越多,出错概率越大。我的习惯是把 cd、PATH、configure 写进一个 bat,参数只改一处;每次开命令行先敲一下 cl 确认是 x86,再执行 bat;编完先 dumpbin 看一眼核心 DLL,再往下走。这些动作加起来不到一分钟,但能挡住位数错位、模块裁多、配置复制错这几类最常见的翻车。
从那以后我每次开命令行都先敲 cl,看到 x86 才继续;configure 也不再手打,而是存成 bat,换机器只改路径不改参数。希望帮到你。
