从 4.x 一路装到 6.xWindows、Ubuntu 全折腾过。很多人在 Qt 上写代码没问题卡死在第一步安装上版本选错、编译器没装、PATH 没配好最后冒出那句经典的 could not find the Qt platform plugin windows 就开始怀疑人生。这篇文章我按实际的安装顺序整一套完整流程版本怎么选、下载源走哪条、装完怎么验证、报错怎么查你跟着走一遍环境基本上一天内就能跑起来。1. 安装前的准备先想明白装给谁用、怎么用1.1 搞清楚你要哪个版本的 QtQt 的版本号看着像流水线其实选择逻辑很固定。目前个人项目里最常听到的是 5.12、5.14.2、5.15.2 和 6.x 这一堆。如果公司项目或参考代码还在用旧版别盲目追新——我记得很清楚Qt 5.15 是最后一个提供开源离线安装包的长期支持版本很多教学帖、老工程的依赖都停在这附近。新学的人我更建议直接上 Qt 6 的 LTS或者稳妥的 5.15.2前者的新特性多后者的资料全。判断标准其实就三条第一项目目标平台和编译器是什么第二依赖的库有没有版本绑定第三团队里别人用什么。比如你后面想接 Halcon 做图像处理Halcon 的算子接口和编译器版本匹配很重要这种情况下就得提前确认 Qt 的位数、编译器类型和 Halcon 的运行时要求能对上。另外位数问题别忽略。32 位和 64 位的程序对应不同构建目录第三方库比如工业相机 SDK、数据库驱动通常也分 x86/x64装之前一定要想清楚主攻哪个。现在新机器基本都是 64 位直接选 64 位 Kit 最省事但有些老设备或串口控件只提供 32 位库那就得老老实实保留一个 32 位环境。1.2 离线安装包和在线安装器选哪个很多人不知道 Qt 的安装器分两种。在线安装器就是那个需要登录账号、边下边装的 MaintenanceTool 套件优势是可以按需勾选组件、随时增减缺点是网络不稳定时很容易中断而且新版要求注册账号。离线安装包则是一个完整的 .exe 或 .run 文件体积大但装的时候不需要联网也不会出现下载到一半断了的尴尬。我的建议很直接能用离线包就别用在线安装器。尤其是国内网络环境几 GB 的离线包用镜像源一口气拉下来比在线安装器逐组件下载靠谱得多。Qt 5.15.2 之前的老版本都有现成的离线包找对镜像十分钟就能下完。Qt 6 之后的离线包没那么好找了官方在线安装器成了事实上的标准路径不过清华镜像等源里也保留了离线包后面详细说。1.3 MSVC 和 MinGW 系到底差在哪这是新手最容易晕的地方。Qt 在 Windows 上有两套编译工具链MSVC 用的是微软 Visual Studio 的编译器MinGW 用的是 GNU 社区在 Windows 上的移植编译环境。qt-qpa-plugin 找不到、依赖库链接失败、第三方库调不通很多问题的根源都是两套工具链混用。选 MSVC 还是 MinGW核心看两个场景。如果你的开发流程里用 Visual Studio、需要调试 Windows 原生 API、或者要对接工业库比如 Halcon那 MSVC 是必然选择注意你机器上还得装对应版本的 Visual Studio Build Tools。如果只是想快速做界面工具、不依赖太多第三方原生库MinGW 更省事因为它的路径和环境变量配置更简单Qt 安装包里自带编译器不用额外装 VS。我个人在 Windows 上主力是 msvc2019_64原因就是做图像处理和工业软件时MSVC 生态的兼容性更稳。但你如果是刚开始入门别两头纠结先选一个用起来后面有跨编译器需求再补。2. 下载渠道官方源和清华镜像怎么搭着用2.1 官方下载路径的正确打开方式Qt 官方网站的下载入口藏得比较深直接从主页找Downloads容易点到营销页。真正有效的是直接进 download.qt.io 或 archive.qt.io 的目录结构里面按版本、按平台分类全套安装包。老版本离线包都在 archive 路径下新版本在线安装器在官方下载页或者镜像源的 online_installers 目录里。需要注意官方域名的在线安装器没有账号是跑不动的这是 2020 年之后许可证策略调整的结果。开源用户选 open source 对应的安装器就行但依然要有 Qt 账户。不想注册账号的话就去镜像站找 offline 安装包。2.2 清华镜像源的配置细节国内拉 Qt 离线包清华 TUNA 镜像基本是首选地址是 mirrors.tuna.tsinghua.edu.cn/qt/。目录结构和官方 archive 基本一致老版本的文件都在那边留了一份。下载时直接定位到对应版本目录Windows 平台找 qt-opensource-windows-x86-5.15.2.exe 这类命名新版本找 qt-opensource-xxx-online-installer 或 archive 里的离线包Linux 找 qt-opensource-linux-x64-5.14.2.run用浏览器下载容易断我习惯用支持断点续传的下载工具拉镜像文件。几 GB 的包一旦中途断了重头再来时间成本扛不住。2.3 文件完整性怎么验证下载完第一件事不是双击安装而是校验文件完整性。Qt 官方和镜像站都提供对应的 .md5 或 .sha1 校验文件。Windows 上可以用 certutil -hashfile 命令PowerShell 里的 Get-FileHash 也行。比如校验 5.15.2 的安装包Get-FileHash .\qt-opensource-windows-x86-5.15.2.exe -Algorithm SHA1拿产出的哈希值和镜像站标注的对比一致就说明文件没损坏。这一步很多人跳过但一旦遇到安装器解压失败、装到一半报错回头排查时你会感谢当时多花的一分钟。3. Windows 下的完整安装流程3.1 动手前必须先处理的三个前置条件第一安装路径。千万别装到带中文、空格或特殊符号的路径下比如 C:\Program Files\Qt 这种带空格的路径也尽量避开。Qt 的构建系统对路径敏感后续 Makefile 和编译器工具链一旦碰上空格报错能把人绕晕。我一般装到 D:\Qt\ 这种纯英文路径清爽且无后续烦恼。第二MSVC 用户先检查有没有装 Visual Studio 的 Build Tools。如果选的是 msvc2019_64 组件机器上必须得有 VS2019 对应的 C 开发环境具体是 MSVC v142 编译工具链和 Windows SDK。没有的话Qt 装完了也无法编译因为 Qt 本身不捆绑微软编译器。第三管理员权限。别直接右键以管理员身份运行走完全程Qt 的目录写入不需要全局管理员但安装过程中要改环境变量、注册系统组件时权限不足会静默失败。稳妥的做法是右键安装包选择管理员运行路径选用户可写的位置。3.2 安装向导里每一步怎么勾双击安装包后第一屏是欢迎页第二屏选组件。很多新手在这里全选结果装出十几个 GB 还慢得不行。正确的勾法是你的编码需求Qt 5.15.2 里至少勾选 Qt 5.15.2 下的 msvc2019_64 或 mingw81_64如果调试需要再勾选 Sources 源码包体积大但看源码排错很有用Qt Creator 组件在 Tools 分类下默认勾选别去掉不需要的模块如 Android、WebAssembly 组件等你真用到再来回折腾不迟另外有个很容易被忽略的细节是Qt Debug Information Files这类调试符号文件勾上之后崩溃调试的时候能看到调用栈里的行号和模块信息对排查 Qt 自身的崩溃问题帮助非常大。磁盘空间能接受的话建议勾上。组件选完就是漫长的复制等待。安装完成后工具菜单里会生成 Qt Creator 和 MaintenanceTool 的快捷方式。先别急着打开下一步是配置编译器套件。3.3 Qt Creator 里编译器套件不报红的配置第一次打开 Qt Creator它会自动扫描本机的编译器和调试器。打开工具-选项-Kits正常情况下能看到一个默认 Kit比如 Desktop Qt 5.15.2 MSVC2019 64bit。关键看三点编译器栏是否显示 Microsoft Visual C Compiler调试器栏是否自动识别 CDBQt 版本栏是否指向你刚安装的 qmake 路径。如果 Kit 显示黄色感叹号或红色错误原因基本是编译器没被识别。MSVC 的编译器信息需要从 Windows 注册表读取如果系统里只有精简版 VS 组件Qt Creator 可能扫不到。解决办法是打开 Visual Studio Installer补装使用 C 的桌面开发工作负载然后重启 Qt Creator 重新扫描。MinGW 用户相对简单安装包自带编译器Kit 一般自动匹配。但我通常会手动确认一下构建目录用的是 64 位版本避免出现64 位 Qt 配 32 位 MinGW这类默认配置的坑。3.4 环境变量 PATH 的正确配置Qt 安装完默认的安装器会往系统 PATH 里加一行 Qt 的 bin 路径。但我见过不少机器装完没有自动加或者加的是临时解压路径这就会导致运行程序时出现 could not find the Qt platform plugin windows。正确做法是手动确认一下。右键此电脑-属性-高级系统设置-环境变量在系统变量 PATH 里添加你的 Qt bin 目录比如 D:\Qt\5.15.2\msvc2019_64\bin同时把编译器对应的 DLL 目录比如 VS 的 VC\Tools\MSVC\版本\bin\Hostx64\x64也放在 PATH 里。配完之后新开一个 cmd 窗口执行 qmake -v能输出 Qt 版本信息就说明路径生效。注意旧窗口不会刷新环境变量测试时一定要新开终端。这个细节导致很多人以为没配成功实际只是用了旧窗口。4. Ubuntu 下搭建 Qt 开发环境的实操记录4.1 用系统包管理器安装还是官方安装器Linux 下装 Qt 有两条路。一条是 apt 直接装系统包sudo apt update sudo apt install qtbase5-dev qtcreator这条路的好处是快、依赖自动解决但装出来的 Qt 版本通常比官方落后且 Qt Creator 版本也可能不是最新的。另一条是下载官方 .run 离线安装器在 Ubuntu 下执行chmod x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run交互界面跟 Windows 一样勾选组件时注意把 Desktop gcc 64 和 Qt Creator 选上。装出来的路径默认在 ~/Qt 或 /opt/Qt看安装时指定的目录。我给 Ubuntu 用户的实际建议是如果你只是日常练手apt 装一套完全够用如果你要复现公司或网络课程的依赖版本用官方 .run 安装器更可控。两条路我都走过.run 装的 Qt 目录更干净卸载也方便缺点是占用磁盘空间比 apt 版本更大。4.2 装完后的权限和启动问题Ubuntu 下装完 Qt 最常见的问题集中在两点第一个是 .run 安装完成后Qt Creator 启动时缺少 xcb 平台插件报错类似 could not find the Qt platform plugin xcb。这个报错几乎都是系统缺少 OpenGL 和 xcb 相关运行库执行sudo apt install libxcb-xinerama0 libxkbcommon-x11-0 libgl1-mesa-dev就能解决绝大部分情况。第二个是如果当前用户无权限写安装目录Qt Creator 的配置写不进去会出现闪退或设置无法保存。解决办法是确保安装目录的所有者是当前用户sudo chown -R 用户名:用户名 /opt/Qt4.3 用一个控制台程序验证环境环境装没装好最有效的验证是编译一个小程序。命令行方式最直接写一个 main.cpp#include QCoreApplication #include QDebug int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); qDebug() Qt environment ok; return 0; }然后qmake -project qmake make ./项目名能输出 Qt environment ok说明 qmake、编译器、运行库全部正常。这一步比直接开 Qt Creator 建项目更能定位问题——如果命令行编译失败问题出在工具链命令行编译成功但 IDE 里跑不起来问题大概率出在 Qt Creator 的 Kit 配置上。5. 安装后的验证、常见报错与卸载要点5.1 那个著名的 qpa 平台插件报错怎么一次性解决Cannot find the Qt platform plugin windows 绝对是 Qt 新手排名第一的拦路虎。这个报错的核心原因是程序运行时找不到 platforms 插件目录也就是 Qt bin 目录下的 platforms 文件夹里的 qwindows.dll。三种场景最容易触发直接双击运行编译出的 exe没经过 Qt Creator且 PATH 里没有 Qt bin把 exe 拷到别的机器只带了 exe 没带 Qt 的 DLL用 windeployqt 部署时部署目录结构不对排查思路按三步走。先确认环境变量 PATH 里有没有 Qt 的 bin 路径没有就加上。第二检查 bin 目录下 platforms 文件夹是否存在如果缺失重装对应组件或者从完整安装里补拷。第三不要依赖 exe 同目录放一个 platforms 文件夹而是用官方推荐的 windeployqt 做部署。发布程序时我固定用这个命令windeployqt 你的程序名.exe它会自动拷贝程序依赖的所有 Qt DLL、platforms 插件和样式插件。5.2 安装期常见报错速查报错现象可能原因解决办法安装器解压失败或卡住下载的安装包损坏校验哈希重新从镜像下载Kit 显示编译器警告缺少 VS Build Tools 或编译器路径不对补装对应版本 C 开发工作负载编译报 msvcp140.dll 找不到缺少 VC 运行库安装 VC 2015-2022 运行库qmake 命令不存在环境变量未配置手动添加 Qt bin 到 PATH 并新开终端安装完成但 Qt Creator 打不开显卡驱动或 OpenGL 库缺失更新显卡驱动或安装 mesa 相关依赖5.3 卸载 Qt 时最容易被忽略的事卸载 Qt 不是把整个目录删掉就完事。Windows 下要用 Qt 安装目录里的 MaintenanceTool.exe选择卸载模式它能清理注册表和快捷方式。直接删目录会留下一堆垃圾项之后重装容易出奇怪问题。特别提醒三点第一卸载前先检查有没有正在运行的程序占用 Qt 的 DLL第二卸载完记得清理环境变量里的 Qt 相关 PATH否则换版本后旧路径会残留第三如果你装过多个 Qt 版本建议只保留一个主用版本其他全部删掉版本间交互的 PATH 冲突是我见过最多的问题来源。最后说点个人体会。Qt 安装这件事百分之八十的问题出在版本和编译器混搭剩下的百分之二十是路径和环境变量。很多人遇到 qpa 插件报错就重装系统其实从 PATH 和 platforms 目录入手十分钟就能解决。装好环境之后后续再看信号槽、多线程 moveToThread、自定义 QAbstractTableModel 这些机制都会顺畅很多。先别急着优化界面、折腾大框架把环境稳定住后面的路自然好走。