第一次下载安装 Qt 的体验往往不是打开浏览器点一下“下载”按钮那么简单。官方安装器慢得让人怀疑人生离线包体积又是两三个 GB版本选错后面写代码就变成“unknown module”和“cannot mix incompatible”的连环报错现场组件没勾全等到项目里用到串口、图表、数据库才发现当时省掉的那几分钟后面得用一整天还回来。这个教程就把 Qt 下载安装这件事从里到外梳理一遍覆盖版本选择、官方源与国内镜像下载、安装器配置、组件勾选以及装完以后最常见的报错排查和发布打包前的准备工作。新手可以直接照着做老手也可以拿它回头检查一下自己的环境有没有埋雷。1. 动手下载之前先把版本和编译器这盘棋摸清楚1.1 在线安装器和离线安装包到底选哪个Qt 的安装方式主要分两种官方发布的是qt-unified-windows-x64-x.x.x-online.exe这种在线安装器体积只有几十 MB本质是一个下载器运行时要联网拉取组件离线包则是qt-opensource-windows-x86_64-5.15.2.exe这种体积经常超过 2GB里面把对应版本的库、工具链和示例程序都打包好了。在线安装器的好处是灵活同一个安装器可以装多个 Qt 版本后续还能随时用维护模式添加或者移除组件不需要重新下载整个安装包。缺点也很明显一是要求注册 Qt 账号哪怕开源用户也需要登录二是首次拉取组件的速度完全取决于网络环境官方源在国内的速度通常不太理想。如果你是第一次接触 Qt我不建议一上来就用在线安装器否则光下载组件这一步就够你喝一壶。离线包最大的优势是稳定可控。网上大量基于 Qt 5.14.2、5.15.2 的教程、企业项目模板、第三方依赖库说明几乎都是围绕这两个版本展开的。离线包下载一次可以反复安装使用安装过程中不需要强制登录账号装出来的环境干净、可预期。我给大多数同学的建议就是认准离线包尤其是 Qt 5.15.2。这里有个背景值得知道Qt 官方从 5.15 之后调整了开源二进制发行策略5.15.2 基本是最后一个提供完整开源离线安装包的常规版本再往后的 Qt 6 系列基本只能靠在线安装器或者源码自行编译。如果你不想折腾老老实实拿 5.15.2 离线包起步完全够用很多年。1.2 把版本、编译器、工具链对上号新手最容易犯的错是在不知道“Qt 版本和编译器强关联”的情况下乱选安装组件。Qt 在 Windows 下最常见的两套工具链分别是 MinGW 和 MSVC整套环境到 Qt Creator 里的 Kit套件都是围绕这个组合来组织的。Qt 版本常见编译器安装目录名适用场景Qt 5.15.2MSVC 2019 64-bitmsvc2019_64调用 Windows API、对接第三方 MSVC 库Qt 5.15.2MinGW 8.1.0 64-bitmingw81_64纯 C/Qt 开发自带编译器省事Qt 5.14.2MinGW 7.3.0 64-bitmingw73_64老版本项目、兼容旧教程Qt 5.14.2MSVC 2017 64-bitmsvc2017_64老版本 VS 环境选择依据很简单如果项目只是纯粹的 Qt C 界面和业务逻辑不涉及第三方二进制库MinGW 套件最省心它自带编译器不需要额外安装 Visual Studio。如果项目要调用 Windows 原生 API、要对接 Halcon、OpenCV、PROJ 这类第三方库我强烈建议用 MSVC 套件因为市面上一大堆第三方预编译库默认就是按 MSVC 编译的MinGW 想链接它们经常会出现符号不匹配、ABI 不兼容的幺蛾子。这些关系还会直接影响你后面怎么改.pro文件。比如在.pro里写QT serialport但实际安装时没勾选 SerialPort 模块编译就会直接报unknown module(s) in qt: serialport。版本选对、组件选全这类低级问题就成功避开了一大半。1.3 什么情况需要走国内镜像源很多老手可能觉得“下载 Qt 不是官网点一下就行了吗”那是没有体会过在普通宽带下从官方源拉取 2GB 安装包的心情。尤其是公司网络、教育网这类环境连接官方服务器经常几 KB 每秒。还有一种更常见的场景公司内网或隔离环境本身连不上外网只能手动下载离线包再拷进去安装。这时候国内镜像站的价值就体现出来了。镜像站并非只是“下载加速”那么简单它本身包含了官方安装器、离线安装包、在线组件仓库的完整存档目录树结构和官方 archive 严格对应。所以你可以把它理解成一个随时可达的备用软件源。常用镜像站地址我放在下一章直接复制文件链接丢给下载工具速度通常能跑到带宽上限。2. 官方页面与国内镜像加速下载的完整实操2.1 从官方 archive 目录直接拿离线包如果你网络环境不错或者需要核对某个版本是否存在直接去官方 archive 页面是最权威的。路径是download.qt.io/archive/qt/往下能看到 5.9、5.12、5.14、5.15、6.0 等大版本号点进去再选具体小版本号。以 Qt 5.15.2 的 Windows 离线包为例完整下载地址是https://download.qt.io/archive/qt/5.15/5.15.2/qt-opensource-windows-x86_64-5.15.2.exe打开 5.15.2 目录后里面会有一堆文件Windows 用户认准qt-opensource-windows-x86_64-5.15.2.exe这个文件。注意一个小坑5.14.2 以及更早版本的文件名里没有x86_64字样而是叫qt-opensource-windows-x86-5.14.2.exe这里面的x86其实表示 Windows 通用安装器不是 32 位别只看文件名把自己绕晕了。官方 archive 页面上通常会列出每个文件的哈希校验值。下载到本地后我建议花十秒用 PowerShell 算一下 SHA256 再解压安装防止下载过程里文件损坏。命令是Get-FileHash .\qt-opensource-windows-x86_64-5.15.2.exe -Algorithm SHA256这一步看起来多余但它能避免后面安装到一半报文件损坏、装完才发现某个 dll 缺失的问题。项目不管大小环境干净可靠永远是第一位的。2.2 国内镜像站的具体地址和操作方式如果你下载速度不理想直接换国内镜像站。我自己常用的有四个全部实测可用镜像站访问路径模板清华 TUNAhttps://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/5.15/5.15.2/中科大 USTChttps://mirrors.ustc.edu.cn/qtproject/archive/qt/5.15/5.15.2/阿里云https://mirrors.aliyun.com/qt/archive/qt/5.15/5.15.2/腾讯云https://mirrors.cloud.tencent.com/qt/archive/qt/5.15/5.15.2/操作上没有任何技巧浏览器打开对应目录找到qt-opensource-windows-x86_64-5.15.2.exe复制文件链接到 IDM、Fiddler、迅雷这类下载工具里就行。实测在普通百兆宽带下2GB 多的文件一般几分钟到十几分钟能下完比官方源快一个数量级。有个细节需要提醒镜像站的目录结构可能存在轻微差异比如中科大用的是qtproject前缀而清华不写这个前缀。如果你在某个镜像站的地址上找不到文件可以退到它的qt/archive或者qtproject/archive根目录再进一次文件路径基本和官方仍是同构的。另外虽然镜像站的哈希值不一定都提供但你可以拿官方页面上记录的文件大小做交叉比对至少能排除下错文件这类低级错误。2.3 在线安装器同样可以走镜像参数有些场景下你还是得用在线安装器比如要装 Qt 6或者想通过在线方式同时管理多个版本的组件。其实在线安装器本身也支持镜像源参数不需要死磕官方源。假设你下载了qt-unified-windows-x64-4.6.1-online.exe可以直接在当前目录打开命令提示符执行qt-unified-windows-x64-4.6.1-online.exe --mirror https://mirrors.tuna.tsinghua.edu.cn/qt/也可以先设置环境变量再运行安装器set QT_MIRRORhttps://mirrors.tuna.tsinghua.edu.cn/qt/ qt-unified-windows-x64-4.6.1-online.exe设置镜像参数之后在线安装器的界面流程不变化仍然需要登录 Qt 账号但底层的组件包下载会走镜像。需要注意不同年代的安装器对镜像 URL 的兼容性略有差异老版本安装器可能要求在镜像参数后面带上online/qtsdkrepository/子路径。如果加了参数没反应可以先在浏览器里访问一下镜像根目录确认地址可访问再调整路径写法。3. 安装器里的那些选项到底该怎么勾3.1 安装目录、协议和账号问题一次说清离线包启动后的流程相对简单选择安装路径、选择组件、同意协议、安装。这里我最想强调的就是安装路径请务必不要用中文目录也不建议带空格。虽然现在 Qt 对空格的兼容性比早期好很多但后续用命令行工具、第三方库链接时一个带空格或者中文的路径会让你在排查问题时多出大量无谓的工作。我自己常年装在D:\Qt这种纯 ASCII 目录下干净省心。关于协议普通开发者在安装时选开源协议LGPL/GPL就可以不需要付费授权。离线包安装流程通常不会强制登录账号在线安装器则会要求注册并登录一个 Qt 账号账号本身免费注册过程中如果网络不好可能会有点烦但这是官方流程的一部分。安装到 C 盘根目录这类系统目录时部分步骤会需要管理员权限所以更推荐直接装到自定义目录避免后续维护时权限问题。3.2 组件勾选清单SerialPort、Charts 这些最容易漏离线包安装过程中出现的组件列表会把模块分得很细。以 Qt 5.15.2 MSVC 2019 64-bit 为例你在组件树里会看到类似这样的结构Qt 5.15.2 ├─ MSVC 2019 64-bit │ ├─ Qt 5.15.2 MSVC2019 64bit │ │ ├─ Qt Charts │ │ ├─ Qt Data Visualization │ │ ├─ Qt Serial Port │ │ ├─ Qt WebEngine │ │ └─ ... │ ├─ Qt Debug Information Files │ └─ Sources ├─ Developer and Designer Tools │ ├─ Qt Creator │ ├─ MinGW 8.1.0 64-bit │ └─ CMake └─ ...很多新手默认安装时只勾了“Qt 本身”或者安装向导没仔细看就一路 Next结果到了写代码阶段才发现#include QtSerialPort/QtSerialPort直接找不到头文件.pro里QT serialport一编译就报错。这类问题的根因全在那里模块压根没装。我给一个比较实用的组件勾选参考组件是否建议勾选说明Qt Charts是画曲线图、柱状图常用默认不装很容易忽略Qt Data Visualization按需做三维图时用普通业务可以不加Qt Serial Port是串口开发必备很多做下位机的同学栽在这Qt WebEngine按需体积很大只有嵌浏览器才需要Qt Debug Information Files是崩溃时能看到带行号的调用栈调试价值高Sources按需只有需要看 Qt 源码调试内部逻辑才勾这里特别提醒一句Qt Serial Port 在老的安装器版本里单独放在“Qt Serial Bus”或“Additional Libraries”这类分类下不是所有版本都一目了然地放在主模块列表里。安装时多花一分钟把列表展开翻一遍远好过装完再拿 MaintenanceTool 去补。3.3 Qt Creator 的 Kit 配置和编译器匹配Qt 安装完成后正常情况下 Qt Creator 会在首次启动时自动检测到安装的 Qt 版本和编译器套件。但自动检测不是百分百可靠尤其在多编译器、多版本共存的环境里。打开 Qt Creator 后进入 工具 - 选项 - Kits看到类似Desktop Qt 5.15.2 MSVC2019 64bit这样的 Kit 名称。关键要看三项内容编译器、调试器、Qt 版本qmake 路径。如果编译器那一列显示的是黄色感叹号或者红色的“未设置”说明 Kit 检测失败需要手动指定编译器路径。MSVC 套件要确保系统里装了对应版本的 Visual Studio 或 Build ToolsMinGW 套件则要保证 MinGW 编译器路径正确指向你安装的 MinGW 目录里的g.exe。一个常见的坑是MinGW 套件选择好了但Qt 版本那一栏指向了别的目录下的 qmake。比如你同时在C:\Qt\5.15.2\mingw81_64和D:\Qt\5.15.2\msvc2019_64各装了一套用 MinGW Kit 时 qmake 却指到了 MSVC 目录那构建必然出问题。判断方法很简单看 qmake 路径里的目录名是不是和你要用的编译器一致。这个细节比想象中重要得多热词里频繁出现的“qtcreator对应qt版本”“qt离线安装包下载5.14”这类搜索本质都是在找版本、编译器、Kit 之间的对应关系。4. 装完就报错的经典场景模块缺失、版本冲突与套件错配4.1 unknown module(s) in qt: serialport 的元凶这个报错在串口开发圈里几乎天天见。现象是在.pro文件里写了好几遍QT serialport构建时仍然报:-1: error: unknown module(s) in qt: serialport原因一句话就能说透你用的 Qt 安装里根本没有编译好的 Qt Serial Port 模块。Qt 的模块和.pro里的声明必须一一对应不是代码里写了#include QtSerialPort/QtSerialPort就能凭空出现。解决方式也不复杂。找到 Qt 安装目录下的维护工具MaintenanceTool.exe双击运行选择“添加或移除组件”在对应版本下勾选 Qt Serial Port然后更新。如果你的原始离线包还在直接重新运行那个离线安装包也能进入维护模式不需要重新下载整个 Qt。还有一个隐形坑很多同学用的是从各种渠道搞来的“绿色版”“精简版” Qt那些版本经常被作者手动阉割掉一堆模块。为了省一点磁盘空间结果串口、图表、数据库模块全都没有等到项目做一半才发现模块缺失那体验是真的酸爽。能用官方离线包或者镜像站正规安装包就别碰精简版这是我一直坚持的原则。同样的报错套路也适用于 Qt Charts、Qt Data Visualization、Qt WebEngine 等非默认模块。遇到这类问题排查思路完全一样先确认模块是否安装再确认.pro里的声明是否写错最后检查 Kit 选定的 Qt 版本目录里有没有对应模块文件夹。4.2 cannot mix incompatible qt library 的版本冲突这个报错在热词里出现了具体版本号cannot mix incompatible qt library (5.15.3) with this library (5.15.2)。它的本质是二进制兼容性问题程序编译链接时链接了一个 Qt 小版本的库运行时却加载了另一个小版本的 Qt 动态库Qt 运行库在启动时会做 ABI 一致性检查发现版本对不上立刻拒绝工作。这种冲突最常见的来源有三个。第一系统 PATH 环境变量里残留了多个 Qt 的 bin 目录比如你之前装过 Qt 5.15.3后来装了 5.15.2但 PATH 里两个目录都在程序启动时随机加载了不对的那一套。第二Qt Creator 的 Kit 里 qmake 路径和编译器不匹配构建出来的程序依赖了一个版本运行时却从另一个目录找 dll。第三项目里同时链接了第三方预编译库和 Qt而第三方库依赖的 Qt 版本和你当前 Qt 版本不相同。解决思路就是统一把环境变量 PATH 里多余的 Qt bin 目录全部清理掉只保留当前项目对应的那一个检查 Qt Creator 的 Kit确认 qmake、编译器、CMake 三项指向同一个工具链然后把 build 目录整个删掉重新 qmake 和构建。如果你自己分析 dll 依赖可以下载一个 Dependencies 工具直接打开程序 exe 看它加载了哪个版本的 Qt5Core.dll问题一目了然。4.3 套件和编译器对不上导致的构建失败热词里有一条典型报错error while building/deploying project qtmodbus (kit: desktop qt 5.9.9 mingw)。这种报错出现时Qt Creator 下方面板往往还会跟着一堆cannot find -lxxx、编译器路径不存在的提示。核心原因还是 Kit 选择和实际环境不一致。比如你从旧项目里复制了.pro文件项目配置里记住了旧 Kit但新电脑上根本没装对应的编译器或者系统里只装了 VS2019你却选了 MinGW Kit又或者 MinGW 编译器路径指向了一个不存在的老版本目录。操作建议是在 Qt Creator 的 工具 - 选项 - Kits 里把当前 Kit 的编译器、调试器、qmake 三个选项全部重置为“Detected”让 Qt Creator 自动探测。如果探测不到手动指定编译器路径。MinGW 套件需要指定gcc.exe和g.exe所在的 bin 目录这个目录通常在 Qt 安装目录下的Tools\mingw810_64\bin不在 Qt 库目录里。很多人第一次装完找不到 MinGW 编译器就是因为在组件树里漏勾了Tools - MinGW 8.1.0 64-bit只装了 Qt 库本身。4.4 卸载残留和换版本时容易忽略的细节卸载 Qt 不是简单地在控制面板里右键卸载就完事了。正确姿势是运行MaintenanceTool.exe选择“移除所有组件”它会把 Qt 库、Qt Creator、已安装模块等等按照安装日志逐项清理干净。如果你直接用控制面板卸载很可能会留下几百 MB 的残留文件下次重装时还会出现 Kit 检测混乱。如果你正在切换主用的 Qt 版本比如从 5.14 换到 5.15.2我建议先把旧版本维持原样不要马上卸载。因为旧项目可能还能跑你需要一个过渡期验证兼容性。等确认没问题再执行卸载。换版本之后旧项目的构建目录最好整个删除重新打开项目并重新选择 Kit否则构建缓存里可能还残留旧版本路径。还有一类特殊情况某些精简版、绿色版 Qt 没有 MaintenanceTool.exe。这种就只能手动删除安装目录然后检查用户目录下是否有AppData\Roaming\QtProject这类残留配置同时清理系统环境变量里的 Qt 相关路径。注册表一般情况下不用动但如果反复卸载安装后 Kit 列表总是出现幽灵项可以搜索清理 Qt 相关的注册表项操作前记得先备份注册表宁可慢一点也别误删系统项。5. 下载安装之后顺手把环境验证和发布打包这关也过了5.1 用命令行快速验证 Qt 环境是否正常安装完成之后第一个动作不应该是急着写界面而是先确认环境可用。打开命令行工具切到 Qt 的 bin 目录执行qmake -v能看到类似下面的输出就说明 qmake 和对应版本都正常QMake version 3.1 Using Qt version 5.15.2 in D:/Qt/5.15.2/msvc2019_64/lib如果提示qmake 不是内部或外部命令要么是没切到 bin 目录要么是 PATH 环境变量里没加 Qt 的 bin 路径。这里我想多说一句不要盲目往 PATH 里加 Qt 路径尤其是你电脑上装了很多版本的时候。PATH 里多个版本的 bin 混在一起正是上一章提到的cannot mix incompatible qt library的常见诱因。短期的做法就是cd到对应版本的 bin 目录再执行命令。验证完 qmake你还可以顺手做一个最小的编译实验。新建一个目录放入一个简单的main.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Qt environment OK); label.resize(200, 100); label.show(); return app.exec(); }写一个同目录下的test.proQT widgets SOURCES main.cpp然后执行qmake test.pro mingw32-make如果是 MSVC 套件把最后的编译命令换成nmake。程序能弹出一个窗口说明这套环境完全可以正常开发了。这个实验不超过两分钟却能把安装、工具链、模块路径、编译器这四件大事一次性验证完。5.2 第三方库调用前的版本匹配检查热词里有“qt 调用 proj”“qt怎么调用halcon”这两类问题其实是同一个套路拿到第三方库的 include 和 lib/dll在.pro里配置头文件路径和库路径运行期把 dll 放到可执行文件旁边或者加入 PATH。但在配置之前有三件事一定要确认一是位数。第三方库是 x64 编译的你的 Qt 也要是 x64Kit 名称里通常能看到64bit字样。二是编译器类型。用 MSVC 编译的第三方库你就用 MSVC 套件的 Qt用 MinGW 编译的库才用 MinGW 套件。MinGW 和 MSVC 的库不能混着链接这是新手踩得最多的坑。三就是 Qt 版本尽量和库作者编译时使用的 Qt 大版本一致小版本最好也别跨太多。我建议的流程永远是先做最小验证。写一个只调用第三方库单个函数的 demo比如 PROJ 库的proj_create先编译链接跑通再往正式项目里迁移。环境问题一旦和业务逻辑混在一起排查成本会成倍上升先把变量控制住才是正事。5.3 用 windeployqt 完成发布前的依赖收集很多人的 Qt 开发之路最终目标是写出一个能发给别人直接运行的桌面程序。但 Qt 编译出来的 exe 直接拷到别的机器上运行十有八九会提示缺Qt5Core.dll、Qt5Gui.dll这类文件。解决办法是让 Qt 自带的部署工具来处理依赖收集。操作流程很简单先在 Qt Creator 里切到 Release 模式编译你的项目拿到一个单独的 exe 文件新建一个干净目录把 exe 拷进去打开命令行工具切换到对应套件的 bin 目录执行windeployqt D:\release\your_app.exe需要注意windeployqt 必须使用和你编译套件对应的版本。MSVC 编译的就用msvc2019_64\bin\windeployqt.exeMinGW 编译的就用mingw81_64\bin\windeployqt.exe不要混用。执行完成之后exe 目录下会多出很多 Qt 动态库和插件目录包括 platforms、styles 等这些都是运行必需的。这里有一个容易被忽略的点如果你的程序是 MSVC 编译的目标机器上还需要 VC 运行库。如果那台机器恰好没装过任何 Visual C Redistributable运行时会直接报“应用程序无法正常启动”。所以发布前最好到处找一下对应版本的vc_redist.x64.exe和你的程序目录放一起让用户装一遍。这个步骤不是 Qt 本身的事但它是补齐“发布包完整可用”这块拼图的关键环节。6. 关于下载安装这件事我最后想说的几句话如果你问我自己电脑上的 Qt 环境是怎么配的我目前的固定组合是 Qt 5.15.2 的 MSVC2019 64bit 和 MinGW 8.1.0 64bit 两套各装一份平时写界面和对接第三方库用 MSVC写纯工具类小 demo 用 MinGW。两套的安装包最早都是从镜像站拉的离线包安装目录分开PATH 环境变量里只保留当前正在用的那套绝不混。下载安装这件事本质上就是版本、渠道、工具链三者对齐的过程。在正式开始之前花十分钟想清楚版本和编译器后面能省出一整天的排查时间。希望这份教程能让你少踩几个坑顺利把环境跑起来写出第一个能弹出来的小窗口。