简介Qt 5.15.12 是面向 Windows 10 32 位环境的 Qt 开发组件专门服务于使用微软VC2019编译器构建跨平台 C 应用的开发者也适合需要维护老式32位架构或兼容旧系统接口的桌面项目团队。该 Win32 动态库版本提供核心、控件、网络等模块的头文件声明保留 TLS 加密传输能力同时剔除体积大且编译复杂的 WebEngine 模块让最终发布包更精简、依赖更可控。压缩包内共有 2000 个文件以 .h 头文件为主体整体大小约 360.47MB这些头文件是编写和编译 Qt 程序必需的接口定义来源。已有 586 人学习下载。获取这套完整头文件后开发者能以较低成本搭好开发环境在 Debug 与 Release 模式之间切换快速完成 GUI 界面、网络通信及基础数据结构相关功能的编码、调试与部署对 32 位 Windows 应用开发具有较强实用价值。1. 为什么非要自己编译一份32位Qt动态库接手一个维护了三年的工业设备上位机项目软件要跑在Windows 10的32位嵌入工控机上界面用的是Qt5。项目最头疼的是官方预编译的Qt5.15版本只提供了64位MSVC和MinGW的二进制包32位动态库要么在老版本里找要么就得自己动手编。一开始我也想过能不能用静态库凑合但设备升级需要插件热加载动态库是硬性需求。折腾了两周前前后后翻车十几次把configure、nmake、jom那套流程摸透了才得到一份干净的32位DLL。这篇笔记就是那次编译过程的完整记录从环境准备到坑点排查全部写出来给正好要下Qt5.15.12源码自己编译32位动态库的朋友做参考。2. 编译前的环境准备源码、工具链与依赖2.1 拿到Qt 5.15.12的源码包编译动态库第一步是下载源码。Qt官方发布版在5.15.2之后就不再提供离线二进制包但源码包和后续补丁版本仍然通过在线安装器或镜像站发布。我使用的版本号是5.15.12属于Qt 5.15长期支持分支的修正版修复了不少小问题。下载时认准qt-everywhere-opensource-src-5.15.12.zip这样的命名别下成在线安装器的exe。源码包解压到纯英文路径比如D:\src\qt-5.15.12。这一步看似简单实际是个大坑后面会专门讲。解压完成后目录下会看到configure.bat、qtbase、qtdeclarative等一级模块目录。注意我们只需要编译基础模块也就是qtbase里的核心库如果不需要QML等额外模块可以在configure时通过-skip参数跳过节省大量时间。提示如果用在线安装器获得源码路径会嵌套在安装目录里结构可能不同。建议直接解压独立的源码压缩包环境干净可控。2.2 选择编译器MSVC还是MinGW32位动态库在Windows 10上有两套主流工具链MSVC微软Visual C和MinGWGCC的Windows移植版。选哪套取决于你项目里其他依赖库的编译方式。如果现有第三方库是MSVC编译的你最好也用MSVC编译Qt否则后续链接会因C运行时不一致而出各种莫名错误如果项目里所有库都是MinGW编译的那就统一用MinGW。我这次项目里的硬件厂商SDK是用MSVC编译的所以选MSVC 2019社区版。注意Qt的-platform参数要和编译器对应MSVC对应win32-msvcMinGW对应win32-g。另外32位目标需要安装对应x86的编译组件Visual Studio安装器里要勾选“适用于Windows的C CMake工具”和“MSVC v142 x86/x64生成工具”。2.3 依赖库处理OpenSSL与ICUQt默认会尝试自动检测OpenSSL和ICU如果检测不到就跳过对应功能。对于一般桌面应用这俩不是必需但如果你的程序要支持HTTPS、TLS加密通信就需要提供OpenSSL动态库。我这里项目用不到HTTPS为了减少编译复杂性直接在configure命令行里添加-no-openssl -no-icu强行关闭检测。这样既不会因缺失依赖而失败也避免链接时引入额外DLL。如果确实需要OpenSSL务必下载32位版本的OpenSSL预编译包解压到独立目录然后在configure时用-openssl-linked -I C:\openssl\include -L C:\openssl\lib指定路径。这里要提醒一下64位和32位OpenSSL不能混用曾经有人把64位的lib文件给32位编译用最后链接阶段报无法解析的外部符号。3. 配置与生成构建文件configure参数详解3.1 写一条干净的configure命令行进入源码根目录打开“x86 Native Tools Command Prompt for VS 2019”命令提示符注意是x86版不是x64然后执行以下命令cd /d D:\src\qt-5.15.12 configure.bat -release -shared -platform win32-msvc -mp -opensource -confirm-license -prefix D:\Qt\5.15.12\msvc2019 -skip qtdeclarative -skip qtquickcontrols2 -skip qtwebengine -skip qtmultimedia -nomake examples -nomake tests -no-openssl -no-icu -opengl desktop这条命令里每个参数都有实际意义。-release编译发布版不包含调试符号体积小、运行快-shared明确生成动态库这是本次编译的核心要求-platform win32-msvc指定编译器平台-mp开启多进程编译能显著缩短编译时间。-prefix指定安装路径这决定了后续nmake install把库放到哪里。-skip后面跟的是不需要编译的模块比如WebEngine这种重量级模块直接跳过能省掉n个小时。3.2 configure输出与参数检查configure执行过程中会打印很多检测信息重点看最后几行。出现“QMake is now configured for building”说明配置成功。此时目录下会生成config.summary文件用文本编辑器打开检查以下几项Build type: releaseArchitecture: i386或者x86这代表32位Dynamic vs static: dynamicOpenSSL: noICU: no我习惯用findstr /I x86 dynamic config.summary来快速筛选确认无误后再进入编译。如果发现Architecture显示x86_64说明当前shell不是32位编译器环境需要重新打开x86版本的Native Tools命令提示符。3.3 修改编译线程数与并行度现代CPU核心多编译Qt这种大型库串行编译会让人等到怀疑人生。configure生成Makefile后执行nmake时可以指定并行数。Visual Studio自带的环境变量里没有内置-j参数但nmake支持通过-N指定并行其实nmake本身不支持并行。我之前也以为有并行选项后来发现MSVC环境下需要用jom替代nmake。jom是Qt官方提供的并行构建工具用法几乎和nmake一致。如果你的环境里没有jom可以只用nmake编译但会很慢。我建议装一个jom把它放到C:\Qt\Tools\jom然后在PATH里加上该目录。编译时执行jom -j 8这里的-j 8表示同时运行8个编译进程。注意不是越大越好8核CPU用8基本合适超过物理核心数反而会因为内存带宽不足导致性能下降。第一次编译时建议先用jom -j 4测试确认没有低级错误再调高并行数。4. 编译执行与结果验证4.1 编译及安装从jom到install确认configure无误后接着执行编译jom -j 8这个过程会持续很长时间我机器i7-9700、16G内存只编译qtbase和基础模块用了大约50分钟。期间屏幕会高速滚动各种.cpp编译命令如果有红色错误信息会停下来。遇到第一个错误就查看信息别急着继续。常见的是源码路径含空格导致的命令解析错误下方避坑章节会专门讲。编译完成后执行安装命令jom install这条命令会把头文件、库文件、qt.conf、mkspecs等复制到之前-prefix指定的目录D:\Qt\5.15.12\msvc2019。安装成功后在那个目录下会看到bin、lib、include等子目录lib下面有生成的Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll以及配套的.lib文件。记住动态库的实际文件在bin目录lib目录里的dll其实是空的链接库其实MSVC下lib目录存放的是导入库.lib真正的DLL在bin目录。运行时需要的是bin里的dll。4.2 验证DLL位数与依赖经过漫长等待得到一个32位DLL后第一件事是验证位数。用Visual Studio自带的dumpbin命令dumpbin /headers D:\Qt\5.15.12\msvc2019\bin\Qt5Core.dll输出信息里找到FILE HEADER VALUES段如果显示machine (x86)就是32位。如果显示x64就说明配置时用错了编译器需要重新来过。还要检查DLL的依赖项使用dumpbin /dependents Qt5Core.dll正常情况下会看到KERNEL32.dll、USER32.dll、ADVAPI32.dll等系统库如果出现MSVCP140.dll或VCRUNTIME140.dll说明依赖了MSVC运行时部署到目标机器时需要安装对应版本的Visual C Redistributable。我一般把x86版运行时打包到安装程序里否则在新系统上会弹“找不到VCRUNTIME140.dll”。4.3 用一个命令行小Demo验证库可用编译完动态库最好写十几行代码跑通链接。新建一个test.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(QStringLiteral(Qt 32-bit DLL OK)); label.show(); return app.exec(); }然后创建test.pro工程文件QT widgets SOURCES test.cpp在命令行里设置环境变量指向新编译的Qt用其自带的qmake生成Makefile并编译set PATHD:\Qt\5.15.12\msvc2019\bin;%PATH% set QMAKESPECwin32-msvc qmake test.pro jom编译成功后运行test.exe能够弹出标签窗口就说明动态库可正常工作。如果提示找不到DLL把bin目录加入PATH即可。这个验证过程值得每次编译后都做一遍虽然简单但能快速暴露链接或运行时的兼容问题。5. 避坑指南四个高频踩坑点与处理方案5.1 路径含中文或空格导致的编译失败现象configure正常但编译到一半报错“cannot open file D:\源码\qt-5.15.12....(系统找不到指定的路径)”或者出现非语法错误的假报错。原因Qt源码及安装路径中如果包含中文、空格、特殊符号Makefile中对路径的解析会出错特别是源码路径里的中文会把命令行参数拆散。解决解压源码前就改到纯英文目录。检查环境变量TEMP和TMP是否带有中文路径可以在命令行里设置set TEMPD:\Temp再执行configure。所有涉及路径的参数都统一用英文短路径避免用带空格的Program Files目录。5.2 编译出来的DLL是64位而不是32位现象按教程走完流程dumpbin检查发现dll是x64或者链接时提示“module machine type x64 conflicts with target machine type x86”。原因configure时虽然指定了-platform win32-msvc但在64位操作系统中打开的是“x64 Native Tools Command Prompt”命令行里的编译器是64位版本默认生成64位代码。Qt的configure会检测编译器的默认输出格式生成64位配置。解决重新打开“x86 Native Tools Command Prompt for VS 2019”在窗口标题栏能看到“x86”字样。同时验证cl命令的输出版本运行cl后第一行显示“x86”才是正确环境。彻底删除之前的构建缓存源码目录下的.qmake.cache和Makefile重新configure。5.3 运行时提示找到不到入口点或DLL注册失败现象把编译好的DLL复制到目标机器运行程序时提示“无法找到入口点 于...”或者某些插件加载时崩溃。原因最常见的是版本混用动态库比如程序同时加载了Qt 5.15.12和Qt 5.15.2的dll两个版本间符号不一致。另外32位进程加载了64位dll也会报入口点错误——Windows加载器发现dll位数不符直接拒绝执行。解决强制所有Qt相关dll来源于同一个编译目录。用dumpbin /dependents检查exe依赖的Qt库路径确认没有从旧目录拷贝来的残留。部署到目标机器前把bin下的所有dll统一拷贝到exe同目录并使用windeployqt工具自动收集依赖。如果使用第三方插件确保插件也是同一版本、同一位数编译的。5.4 configure检测不到OpenSSL或ICU导致功能缺失现象configure日志里显示OpenSSL: no程序运行时调用QSslSocket相关功能直接报“The feature ssl is not enabled”或者连接HTTPS站点失败。原因我在前面提到用-no-openssl关闭检测但如果需要用到SSL而源码包或环境里没有正确安装OpenSSL的库和头文件Qt只能禁用SSL功能。Qt的OpenSSL检测默认搜索C:\OpenSSL和系统目录找不到就静默跳过。解决下载Qt对应版本的OpenSSL 1.1.x预编译包区分32位和64位。设置环境变量OPENSSL_ROOT并在configure命令行中加入-openssl-linked -I C:\OpenSSL-Win32\include -L C:\OpenSSL-Win32\lib。注意Qt5.15对OpenSSL 3.x支持并不好建议用官方标注兼容的1.1.1版本。配置完成后在config.summary里再次确认OpenSSL: yes。6. 进阶用法把自编译动态库无缝集成到现有项目6.1 修改系统环境变量与Qt Creator配置拿到自编译Qt动态库后要让它成为日常开发的一部分。先修改系统PATH把D:\Qt\5.15.12\msvc2019\bin放到最前面确保命令行启动的程序优先使用这个目录下的dll。然后在Qt Creator里添加Manual套件Qt版本指向D:\Qt\5.15.12\msvc2019\bin\qmake.exe编译器选用MSVC x86CMake工具按需配置。用这个套件打开已有项目重新编译就可以直接观察到项目是否和自编译库兼容。我习惯用qmake管理项目因为自编译库自带对应的mkspecsqmake能自动识别。CMake项目需要额外指定CMAKE_PREFIX_PATH在CMakeLists.txt里做如下设置set(CMAKE_PREFIX_PATH D:/Qt/5.15.12/msvc2019) find_package(Qt5 REQUIRED COMPONENTS Widgets)6.2 用windeployqt打包部署依赖程序开发完不能直接把exe拷走至少要把Qt的dll和插件结构一起部署。Qt的bin目录下自带windeployqt.exe对可执行文件执行cd /d D:\build\test D:\Qt\5.15.12\msvc2019\bin\windeployqt.exe --release test.exe这个工具会自动扫描exe的依赖将Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll以及platforms目录下的qwindows.dll都复制到exe所在目录。特别提醒如果使用了QWebEngine或Qt5Network这个工具的输出可能不完整还需要手动检查。我之前在32位环境下用windeployqt时发现它偶尔会误复制64位dll所以部署完一定要用dumpbin检查exe旁边dll的位数。6.3 编写一键构建与部署脚本每次都手动敲命令容易出错我最后把整个编译和打包过程写进一个批处理脚本build_qt_32.bat从头到尾执行一遍echo off setlocal set QTDIRD:\Qt\5.15.12\msvc2019 set PATH%QTDIR%\bin;C:\Qt\Tools\jom;%PATH% call C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars32.bat cd /d %~dp0 qmake test.pro jom -j 8 windeployqt --release release\test.exe echo Deployment completed. endlocal这个脚本先初始化x86编译环境再用设定好PATH的qmake构建最后自动部署。脚本里有一行很关键call vcvars32.bat它确保整个环境都是32位工具链规避了位数混乱的风险。从那以后我每次拿到新版本Qt源码或换电脑都强制走一遍这个流程从configure参数核对到dll验证不再偷懒跳过任何一步。希望这些记录对你能有实际的帮助。本文还有配套的精品资源点击获取