简介围绕QT 5.15.16版本与Visual Studio 2019的Windows编译场景这份编译包面向需要快速获得可用Qt库的中高级C开发者尤其适合在Win10下同时兼顾32位与64位目标的应用项目省去手动配置源码与依赖的繁琐流程。包内共2000个文件容量753.36MB其中1548个头文件构成内容主体覆盖Qt Core、Gui、Widgets、Test等主流模块的公开接口声明另有json配置与pri工程文件辅助项目属性设置方便在VS2019中按需引用整体结构清晰。目前已有863人学习压缩包采用zip格式交付适合具备C基础、正从零搭建Qt开发环境的开发者入手。整体沿用include、lib、plugins、bin的经典目录划分既清晰又便于查找引入后即可配置头文件路径与库目录同时借助插件机制灵活扩展功能根据业务需要选用特定模块实现跨平台桌面端或嵌入式界面的高效开发缩短从环境准备到正式编码的过渡时间。 说句实在话在 Windows 上自己编译 Qt 这件事听着有点折腾但只要你碰过一遍 Qt 5.15.16就会发现官方安装包给的东西不一定够用。想调试 Qt 源码、想裁剪模块、想用 MSVC 2019 配合特定补丁版本自己编译几乎是绕不开的路。这篇文章就围绕“QT5.15.16编译win10vs2019”这条主线把从环境准备、源码获取、configure 参数设置到最终集成到 VS2019 的完整过程拆开讲把我踩过的坑、验证过能用的命令、以及排查问题的思路全部列出来。不管是刚入门想自己编译 Qt 的新手还是被编译错误折腾到头秃的老开发这篇文章应该都能给你省下不少时间。1. 编译前的真问题为什么非要自己编译 5.15.161.1 官方安装包的“潜规则”与自编译的适用场景很多人在官网下 Qt 时都会发现Qt 5.15 及以后版本开源版在线安装包里已经不容易直接勾选到 5.15.x 的二进制组件了。官方策略调整后5.15 系列虽然属于 LTS 版本但二进制安装包更多面向商业许可用户普通开源用户想拿到这个版本的 MSVC 预编译库往往得费不少劲。就算你之前安装过 5.15.2想升级到 5.15.16 这个修复了多个 bug 的补丁版本官方在线安装器里也不一定给你痛痛快快列出来。这时候自己编译就成了最可靠的路。另一个常见场景是你需要修改 Qt 源码本身比如想调试某段 QPainter 绘制逻辑或者需要给 QML 引擎打个补丁用安装包根本做不到。再有就是项目里要求“特定编译器和特定 Qt 版本强绑定”比如客户指定 VS2019 Qt 5.15.16那你只能本地编译一套匹配的库。自编译还方便裁剪不需要 WebEngine、不需要 Qt Charts 的项目可以在 configure 阶段直接 skip出来的库更小、编译更快也避免一堆用不上的 DLL 干扰部署。1.2 环境选型win10 vs2019 的搭配逻辑为什么选 win10 vs2019这几个热搜词放在一起本身就说明问题VS2019 的 MSVC v142 工具集和 Qt 5.15 系列的官方支持列表高度匹配。Qt 5.15 发布时官方文档明确支持 MSVC 2017 和 MSVC 2019用 VS2019 编译出的库兼容性和 ABI 稳定性都有保障。Win10 系统则是当前存量最大的 Windows 版本在 win10 上编译 Qt 的教程资料也多遇到问题大概率能搜到现成答案。这里也顺手提醒一句如果你想在 win11 上编译流程完全一样但 Windows SDK 版本可能默认拉到更高版本导致某些模块报奇怪的链接错误。我在 win11 上试过一次问题基本都出在 SDK 版本和 MSVC 工具集不匹配上最后老老实实回到 win10 环境跑通了。所以如果你是第一次自编译 Qt建议直接选一套兼容度最高的组合别上来就挑战新系统。2. 环境准备VS2019安装、Perl/Python补齐与其他依赖2.1 VS2019 安装时最容易漏掉的那几个勾选VS2019 不是装完就能直接编译 Qt 的。很多人装的是社区版或者专业版默认只勾了“使用 C 的桌面开发”但编译 Qt 还需要额外的 Windows SDK 版本。我建议在 VS Installer 里明确检查这三项“使用 C 的桌面开发”工作负载这是必须的它包含 MSVC v142 编译器和核心头文件。右侧“安装详细信息”里Windows 10 SDK 选择 10.0.18362 或者相近版本太新的 SDK 偶尔会和 Qt 5.15.16 的某些源码不兼容。“适用于 Windows 的 C CMake 工具”建议一起勾上虽然我们主要用 configure 脚本生成 Makefile但有些辅助工具会依赖 CMake省得后面再补。装完 VS2019 后记得打开“开发人员命令提示符”测试一下 cl 命令能不能用。这一步很多人忽略结果编译到一半才提示找不到编译器浪费时间。如果 cl 命令提示“不是内部或外部命令”说明环境变量没注入请重新打开命令提示符窗口或者手动执行 VsDevCmd.bat。2.2 Perl、Python、Ruby一个都不能少Qt 5.15 的编译脚本依赖三个解释器工具Perl 用来处理源码生成和构建脚本Python 主要用于部分生成器工具比如 qml 相关的代码生成Ruby 则是某些模块如 qmake 的某些功能会用到的辅助工具。严格说如果只编译基础模块Perl 几乎必装Python 在 Qt 5.15 里也是硬性要求Ruby 在某些模块中才用到但建议一起装省心。我用的是 Strawberry Perl64 位版本默认安装到 C:\Strawberry安装完成后把它加入 PATH。Python 我装的 3.8.10因为 Qt 5.15 的脚本和 Python 3.9 偶尔有兼容性小问题为了稳妥选 3.8。装完以后在命令行里逐个验证perl -v python --version ruby -v三个命令都能正常回显版本号环境准备这一关才算过。如果某个命令提示找不到多半是 PATH 没配好或者安装时忘了勾选“Add to PATH”选项。3. 源码获取与 configure 参数详解3.1 Qt 5.15.16 源码从哪里拿、解压到哪Qt 源码包可以从 Qt 官方提供的开源下载镜像获取。下载时注意选 qt-everywhere-opensource-src-5.15.16.zip 或者 tar.xz 格式Windows 下我推荐 zip解压速度更快也不容易遇到符号链接问题。下载完成后解压目录有讲究路径里不要有中文、空格、特殊符号推荐解压到类似 C:\Qt\src\qt-5.15.16 这种纯英文路径。我第一次编译时图方便解压到了“D:\软件\qt”结果 configure 阶段各种诡异报错排查了半天才发现是路径里中文和空格惹的祸。源码解压好以后我建议在 Qt 源码目录旁边专门建一个编译输出目录比如 C:\Qt\build-qt51516把编译产物和源码分离。这样做的最大好处是如果编译失败想重新 configure直接把 build 目录清空就行不用重新解压源码。我后期调试过好几次这个习惯帮我省了大量等待时间。3.2 configure 命令逐参数拆解每个参数为什么这么写Qt 5.15 编译流程的第一步是执行根目录下的 configure.bat。我在 VS2019 的开发人员命令提示符里进入 build 目录然后调用源码目录里的 configure推荐参数如下cd /d C:\Qt\build-qt51516 C:\Qt\src\qt-5.15.16\configure.bat -prefix C:\Qt\Qt5.15.16\msvc2019_64 -opensource -confirm-license -debug-and-release -shared -mp -nomake examples -nomake tests -skip qtwebengine -skip qtwebview -opensource -confirm-license这里每个参数都有实际意义不是随便写的。-prefix 决定最终编译完的库安装到哪个目录我习惯单独放到 C:\Qt\Qt5.15.16\msvc2019_64以后在 VS 里配置路径直接指到这里就行。-debug-and-release 会同时生成 debug 和 release 两种库虽然编译时间几乎翻倍但实际开发时 debug 版和 release 版都有需求省得到时候再编一次。-shared 生成动态链接库-mp 开启多进程编译能在多核 CPU 上明显缩短编译时间。-nomake examples -nomake tests 是告诉构建系统别编译示例和测试代码这是最有效的编译“瘦身”手段。-skip qtwebengine 是我强烈建议加上的参数QtWebEngine 是编译时间最长、依赖最多、最容易出问题的模块如果项目不需要浏览器内核一定要跳过去。还有几个参数我没写但值得说明。-opensource -confirm-license 表示接受开源协议并确认许可证如果不加configure 会交互式提问在无人值守编译时非常麻烦。如果你需要静态编译可以加 -static 但是 Qt 5.15 的静态编译在 MSVC 下需要额外处理一堆依赖新手不建议尝试。需要禁用 Qt 3D 或者 Qt Charts 等模块可以再加 -skip qt3d 之类的参数看实际需求。3.3 configure 成功后的输出信息怎么看configure 完成会打印一段摘要列出了本次配置的 Qt 模块、编译模式、安装路径等信息。这里我总结一个“望闻问切”的检查方法先看最底部是否出现“Qt is now configured for building”这类字样没有基本就是失败了。再看中间列出的模块列表确认有没有意外少了关键模块。比如如果你看到 Qt WebEngine 虽然在列表里但被标记为“no”而你又没加 -skip说明该模块因缺少依赖被自动禁用了这不算错误但你要留意自己是否需要。最后检查一下 QMAKE 相关路径是否正常这影响到后面 qmake 是否能顺利生成 Makefile。实际经验里configure 阶段最常见的错误是“Perl not found”或者“Python not found”这种错误特别好解决装好工具、配好 PATH 就行。还有一种情况是 Windows SDK 版本不对报错信息里会提到找不到某个 SDK 头文件这时候回到 VS Installer 勾选相应 SDK 版本即可。4. 正式编译jom/nmake、耗时、资源占用与常见错误4.1 为什么我选择 jom 而不是 nmakeconfigure 完成后目录下会生成 Makefile。接下来执行编译传统做法是直接输入 nmake但单进程编译 Qt 这种大型项目会慢到怀疑人生。Qt 官方为 Windows 平台提供了 jom 工具它是 nmake 的兼容替代品支持多核并行编译。下载 jom 后解压到任意目录把 jom.exe 所在目录加入 PATH然后在 build 目录直接执行jom -j 8-j 8 是并发数一般设置为 CPU 物理核心数的两倍内。比如 8 核 16 线程的 CPU用 -j 8 或者 -j 16 都可以但内存不够大时并行太多会导致内存占满。我实测 16G 内存机器用 -j 16内存占用接近 12G系统卡顿明显改成 -j 8 以后稳定很多编译时间也没差多少。所以保守起见强烈建议从 -j 8 开始如果资源充裕再往上调。整个编译时长和模块数量、机器配置有很大关系。我在 10 代 i5 16G 内存 SSD 的环境下跳过 WebEngine 后完整编译加安装大约耗时 1.5 到 2 小时。如果你没跳过 WebEngine时间可能翻倍甚至更多。所以再次强调按需裁剪模块是提高效率的关键。4.2 编译过程可能遇到的高频错误与排查方法编译过程遇到错误是常态重要的是学会从日志里定位问题。我把最常见的几类错误和解决方案整理成表格方便你对照排查错误特征可能原因解决方案提示无法打开包含文件“xxx.h”某个系统 SDK 包缺失或版本不匹配检查 VS Installer 中 Windows SDK 版本尽量使用 10.0.18362 附近版本链接阶段报 LNK1104 无法打开文件“xxx.lib”依赖库路径未正确包含确认 configure 时 -prefix 路径无特殊字符重新 configure 并注意输出中依赖库是否找到编译时直接报“fatal error C1060: compiler is out of heap memory”jom 并发数过高导致内存不足调低 -j 参数关闭杀毒软件实时监控增加虚拟内存qml 相关错误或 qtquick 模块编译失败源码路径存在中文/空格或 Python 版本问题确认路径全英文Python 建议 3.8 版本报错提示“Perl not found”PATH 未配置或安装不完整重新安装 Strawberry Perl 并确认环境变量杀毒软件疯狂报毒或删除临时文件编译生成大量 exe/dll 被误判把源码目录、build 目录加入杀毒软件白名单或暂时关闭实时防护这些错误里内存不足和杀毒软件误删是我遇到频率最高的两类。尤其是杀毒软件有时候报毒弹窗一闪而过你还没反应过来它就把生成的临时文件删了然后编译后续环节疯狂报错。首次编译大型项目强烈建议把构建目录加白名单。4.3 编译完成后的安装nmake install 或 jom install编译产物不会自动复制到 -prefix 指定的目录还需要执行安装步骤。同样是并行执行推荐使用jom install安装过程会比编译快很多主要是把编译好的 bin、lib、include、qml、plugins 等内容复制到安装目录。安装完成后检查 C:\Qt\Qt5.15.16\msvc2019_64 下是否生成了 bin、lib、include、mkspecs 等子目录。如果这些目录都齐了这套 Qt 库就算基本可用了。安装完成后还需要配置环境变量。我习惯把 C:\Qt\Qt5.15.16\msvc2019_64\bin 加入系统 PATH这样在命令行里直接就能执行 qmake、windeployqt 等工具。注意 PATH 配置优先级如果之前装过其他 Qt 版本要确保当前要用的版本排在被优先搜索的位置。5. VS2019 里配置自编译 QtQt VS Tools 与项目设置5.1 安装 Qt Visual Studio Tools 扩展Qt 官方提供了 Visual Studio 扩展用于在 VS 中创建 Qt 项目、自动处理 moc/uic/rcc 等预编译步骤。VS2019 对应的扩展名称是 “Qt Visual Studio Tools”在 VS 菜单栏找到“扩展”-“管理扩展”在线搜索安装即可。安装后重启 VS会新增 Qt VS Tools 菜单。安装扩展只是第一步关键是在扩展设置里指向刚编译出来的 Qt 版本。打开“Qt VS Tools”-“Qt Versions”点“Add new Qt version”版本名称随意我填的是 5.15.16_msvc2019_64路径选择 C:\Qt\Qt5.15.16\msvc2019_64。识别成功后列表里会显示 qmake 路径和 Qt 版本号。这一步如果路径不对后面新建项目时会在“Qt Project Settings”里报错。5.2 新建 Qt Widgets 项目验证编译链配置完成后可以新建一个最简单的 Qt Widgets Application 来验证整条编译链是否打通。创建项目时在项目向导里选择 Qt 版本为刚才新增的 5.15.16。如果是已经存在的项目则在项目属性 - Qt Project Settings 中修改 Qt Installation 为当前版本。项目生成后注意检查项目属性的几个关键选项“调试”和“Release”配置下C/C - 附加包含目录是否自动包含了 Qt 的 include 路径。链接器 - 附加库目录是否指向 lib 路径。Qt Project Settings 中是否勾选了需要的 Qt Modules比如 Qt Core、Qt GUI、Qt Widgets。我遇到过一个容易忽略的问题VS 编译时提示找不到 moc 生成的 moc_xxx.cpp。这通常是因为 Qt VS Tools 没正确识别 qmake 路径或者项目文件没有正确执行 Qt 的自定义生成步骤。解决办法是右键项目 - Rebuild如果还不行检查 .vcxproj 中是否有 Qt 相关的 Import 配置在 Qt Project Settings 里重新勾选模块后保存一般能解决。5.3 部署发布的小细节windeployqt 帮你补全 DLL编译运行成功后如果你需要把程序发给别人运行直接拷贝 exe 是跑不起来的因为 Qt 的 DLL 没有跟着过去。Qt 提供了自动部署工具 windeployqt在命令行里执行windeployqt your_app.exe这个工具会根据 exe 依赖的模块自动拷贝对应 DLL、插件和 QML 目录到 exe 所在文件夹。我在部署 5.15.16 编译的程序时发现windeployqt 会把 platform 插件、styles 插件等一并复制过来比手动搜 DLL 省心太多。需要注意windeployqt 最好与编译使用的 Qt 版本一致否则可能拷贝了错误版本的库运行阶段报“无法定位程序输入点”之类的错误。6. 进阶排查编译完成后的运行期问题与性能对比6.1 “找不到 Qt5Core.dll”与 PATH 顺序问题编译和配置都成功VS 里也能正常 F5 运行但直接把 exe 扔到别的机器或者另开一个终端里运行却提示找不到 Qt5Core.dll。这种情况十有八九是 PATH 环境变量顺序问题或未配置 PATH。如果是自己开发机确认 C:\Qt\Qt5.15.16\msvc2019_64\bin 在 PATH 中且在系统变量里优先级足够高。如果你同时装了多个 Qt 版本务必让当前版本的 bin 路径排在更前面否则运行时加载的是另一个版本的 Qt 库轻则行为诡异重则直接崩溃。判断当前 exe 到底加载了哪个 Qt5Core.dll可以在程序里调用 qVersion() 打印版本号或者在命令行里用 where Qt5Core.dll 查看搜索路径。这种方法能快速确认版本冲突问题。6.2 自编译库与官方预编译库的性能和体积对比我特别对比过自编译和官方在线安装包提供的库官方预编译库默认开启了大量通用特性以便适配不同场景体积相对较大自己编译时可以裁剪模块、关闭不需要的特性最终生成的 Qt5Core.dll、Qt5Widgets.dll 体积有可感知的下降。实际运行性能方面在相同编译器版本和编译选项下两者差异很小毕竟底层代码一致。如果你愿意用 -optimize-size 或 -optimize-speed 参数配置优化级别自编译库可能更贴合自己的性能需求。如果你担心自编译库不稳定其实大可放心Qt 的构建系统本身比较成熟只要环境匹配、参数合理编译出来的库在日常项目开发中完全可靠。我拿自编译的 5.15.16 跑过一个含复杂 QML 动画和 WebSocket 通信的工控程序连续运行半个月没出异常。6.3 一次 QML 编译错误的完整复现与解决记录这里分享一个我印象特别深的 QML 编译错误。当时项目里引入了一个自定义 QML 模块编译时总是报“module MyModule is not installed”。排查了很久最后发现是 qmldir 文件放错了目录Qt 的 QML 引擎在导入模块时会按 qmldir 所在路径解析模块名。自编译 Qt 环境下QML 模块搜索路径与官方安装包略有差异对自定义模块的文件组织要求更严格。解决办法是把包含 qmldir 的目录放到 Qt 安装目录的 qml 文件夹下或者在项目路径中通过 QML_IMPORT_PATH 明确指定模块路径。这类问题在官方预编译版本里也可能遇到但在自己编译、自己组织目录结构时更容易踩中排查思路往往是“先确认模块路径能否被引擎找到再确认 qmldir 语法是否正确”。7. 写给新手的几条独家建议第一次自己编译 Qt总是会碰到各种预想不到的小问题但坚持下来你对 Qt 构建体系的理解会和纯用安装包完全不同。我自己编译这版 5.15.16 时最大的体会是环境干净比什么技巧都重要。干净指两个方面一是系统里不要有一堆旧版 Qt、旧版编译器残留的环境变量干扰二是源码目录和构建目录保持独立干净。很多时候 configure 成功但编译乱报错原因就是环境变量里混入了不该有的路径。另外编译过程中如果某个步骤卡住别急着反复重跑先把日志保存下来搜索报错关键词。绝大多数问题在网络上都有前人踩坑记录甚至 Qt 官方 bug 跟踪系统里也有对应讨论。编译这套库真正花时间的不是敲命令那几秒而是排查环境问题、等待编译完成的过程。但你一旦完整跑通一次后面再编译其他版本、其他模块就是轻车熟路的事。最后送上一句实操体会编译装好后强烈建议立刻新建一个测试项目跑通“写代码 - 编译 - 运行 - 部署”全流程再干别的。很多问题在测试项目里几分钟就能暴露别等做到一半才发现库本身有缺陷到时候排查范围就大了。希望这篇文章能让你少走点弯路顺利产出自己专属的 Qt 5.15.16 编译版本。本文还有配套的精品资源点击获取