刚拿到 Qt 安装包的时候大多数人的第一反应是“这有什么难的一路下一步不就行了”。等你真正装完、打开 Qt Creator、新建一个窗口工程结果发现编译器套件是灰的或者编译时报出一长串:-1: error: dependent ..\..\..\qt\5.15.2\msvc2019_64\include\qtwidget...这种莫名其妙的问题才会明白 Qt 的安装坑比想象中多。这篇博文不打算做那种“官网下载、双击 exe、下一步下一步”的流水账教程。我更想把从零到能跑通第一个 Qt 工程这件事讲透尤其针对 Windows 和 Linux 两条主路径把版本选择、编译器匹配、组件勾选、环境变量这些最劝退新人的环节拆开揉碎。无论你是刚接触 Qt 的小白还是以前用 MinGW 现在被迫切到 MSVC 的开发者或者只是想在自己电脑上把 Qt 环境快速捣鼓出来的学生党这篇文章都能当作一份可以直接照着抄的作业。1. 安装前的关键抉择先理清三件事再说下一步很多人的 Qt 安装失败其实不是手滑而是从一开始就选错了方案。安装 Qt 不像装微信装完就能用它必须解决“版本、编译器、开发工具链”这三个相互咬合的问题。这三个问题没想清楚后面每一步都会踩坑。1.1 版本怎么选LTS、经典版与新版之间的取舍Qt 的版本策略比较特殊它不搞“最新就是最好”那一套。官方每年都会发布新的功能版本比如 6.4、6.5、6.8但真正被工业界广泛使用的往往是 LTS长期支持版本因为 LTS 意味着官方会持续修复安全漏洞和关键 bug而且社区资源沉淀得足够厚。在 Windows 开发圈里5.15.2 是一个非常特殊的存在。它算是 Qt5 系列里口碑最好、兼容性最稳的版本之一很多教材、公司内部项目模板、开源项目的文档都基于它编写。即便 Qt6 发布好几年了你依然能在热词榜上看到大量“qt 5.15.2 下载安装”“qt 5.15.2 离线下载”的搜索说明这个版本的存量用户极其庞大。选版本时我给一个非常务实的建议如果只是自己学习、跟着书敲代码选 5.15.2 或 6.2 LTS 都行但优先 5.15.2因为遇到问题时代码一搜就能找到一堆答案如果是做新产品且不依赖老模块可以直接上 6.5 之后的 LTS如果项目已经定了版本那就别犹豫老老实实装指定版本不要擅自升级Qt 的模块差异和编译配置差异会让项目出现大量无谓的报错。1.2 编译器选择MinGW 还是 MSVC决定了你后面绕多少弯路Qt 官方在 Windows 平台上提供两套编译工具链MinGW 和 MSVC。这两者的区别不仅是编译器名字不同而是整个构建生态的差异。MinGW 是 GCC 在 Windows 上的移植版本优点是安装简单不需要额外装 Visual Studio下载 Qt 安装包时勾选一个 MinGW 编译器就能自己玩。对于初学者MinGW 的体验确实友好得多教材里“新建工程、点运行、弹出窗口”的流程它最符合。MSVC 是微软的 C 编译器它在 Windows 平台上的系统调用兼容性、调试器能力、性能调优方面都更强。很多商业项目、涉及 Windows 特有 API 的项目、还有需要接第三方 Windows SDK 的项目都会强制要求 MSVC 版本。但代价是你必须在机器上先装好 Visual Studio 或 Build Tools然后 Qt 才能识别到这套编译器。经常有人问能不能先装 MinGW 版以后需要了再装 MSVC可以但这两套工具链的代码不能混用同一个工程用 MinGW 编完的产物MSVC 认不了。我见过不少人两个都装了结果 Kit 选错编译时报一堆莫名其妙的头文件错误最后才反应过来是编译套件的问题。所以装之前先问自己我的项目后续方向是什么如果只是学习MinGW 足够如果是跟着公司项目走直接问清项目用哪套然后只装那一套别给自己制造选择题。1.3 在线安装器还是离线包时效、体积与网络环境之间的平衡Qt 的 Windows 安装包其实分成两种在线安装器安装时实时下载和离线安装包一次性下载完成后本地安装。很多人光顾着下载没搞清楚这两者区别以至于高速下错。在线安装器是一个很小的 exe运行后自己选择组件、版本然后边下载边装。它适合网络条件好、不介意等待的人而且组件选择灵活想装哪个模块随时可以再运行维护工具添加。但缺点也很明显国内网络环境下拖动官方服务器动辄几 KB一个大模块装几小时毫不夸张而且安装过程中断线后恢复不一定顺畅。离线安装包体积很大Qt 5.15.2 完整版离线包在 2GB 上下但它一次到位后续安装过程中不会因为网络波动卡死。离线包在下载时可以通过国内镜像站拉取比如清华源、中科大源这类正规开源镜像站一般都能跑满带宽。我的习惯是优先离线包尤其是要装 5.15.2 这个经典版本离线包只要校验好 SHA 哈希整个安装过程非常可控。2. Windows 环境下的完整安装实操推荐路线明确了版本和编译器之后下面这段是 Windows 下最顺滑的安装路线。我会以 Qt 5.15.2 离线包 MinGW 为主要示例同时在 2.4 节补充纯命令行工具用户需要的配置方式。2.1 下载离线包并校验文件别省这五分钟从镜像站下载时注意认准文件名格式官方离线包命名通常是qt-opensource-windows-x86-5.15.2.exe。如果你看到的是qt-unified-windows-x64-online-x.x.x.exe那是在线安装器别下错。下载完别急着双击先做两步。第一步核对文件大小如果镜像站标注了文件大小和 SHA-1 / MD5 哈希用工具校验一下避免下载过程损坏。第二步确认当前磁盘空间足够Qt 5.15.2 完整安装后占用大约 8-10GB如果你只选常用组件通常 3-5GB 也够但我建议至少预留 10GB因为后续还要缓存编译中间文件。安装路径的问题我多说一句虽然现在的 Qt 对中文路径容错好了很多但传统经验是尽量放在纯英文、无空格的路径下比如D:\Qt\5.15.2。有些第三方工具、CMake 脚本、脚本自动化工具对路径中的空格和中文处理不当一旦遇到那种“明明代码没错但编译产出异常”的问题排查一次的成本够你重装三遍 Qt。2.2 组件勾选对照表哪个必须装哪个可以跳过离线包双击后会弹出组件勾选界面。很多新手看到一串串英文复选框直接懵要么全选装到磁盘爆掉要么只勾了第一个装完发现连 Qt Creator 都没有。我整理一份经验导向的勾选清单以 5.15.2 为例组件分类建议勾选说明Qt Core / GUI / Widgets必选这三项是所有桌面应用的基础不装等于没装Qt QML / Quick学习中建议选如果你学 QML 界面开发勾上纯 Widgets 开发可以跳过以节省空间Qt Charts / Data Visualization按需画图表、三维可视化才需要很多开发向导类项目会用到Qt WebEngine不建议勾除非明确需要体积巨大编译也慢纯桌面应用基本用不上Developer and Designer Tools必选 Qt CreatorMinGW 按工具链需求选这里的 MinGW 版本是给你当编译器用的装了 MinGW 工具链就需要对应勾选CMake / Ninja建议勾上新版 Qt 越来越依赖 CMake装上省得后补勾选组件时有几个点容易踩坑。第一Qt Creator 和编译工具链是分开的如果你只勾了 Qt 库本身没勾 Qt Creator装完也找不到 IDE。第二如果你需要 MSVC 编译环境安装器里其实不会给你装 Visual Studio它只能带着识别已有的 VS 工具链所以 MSVC 用户必须先装好 VS 或 Build Tools 再装 Qt。第三同一个 Qt 版本下可以勾多个编译套件比如同时勾 MinGW 和 MSVC但这容易让后续 Kit 选择变得复杂新手建议先只勾一个。2.3 安装后的三个自检动作qmake、Qt Creator、示例工程安装完成后先别急着写代码花五分钟做三个检查能帮你在源头排除八成环境问题。第一步打开命令行输入qmake -v正常情况下能看到 qmake 版本和它基于的 Qt 版本。如果提示“不是内部或外部命令”说明 qmake 没进 PATH或者你还没把 Qt 的bin目录手动加进去。对于离线包和在线安装器Qt 通常会在自己的目录里写配置文件让 Qt Creator 能自己找到 qmake但命令行工具需要的 PATH 得自己处理。第二步打开 Qt Creator在“工具 - 选项 - Kits - 编译器”里确认能看到对应编译器。如果 Kits 页面显示“No suitable kits found”那基本可以确定是编译器没被识别。第三步新建一个默认的Qt Widgets Application点“构建”如果能顺利编译出一个空窗口并运行那环境就算立住了。不要直接拿别人的工程试第一轮先用官方模板验证环境才能把“环境问题”和“代码问题”分开。2.4 不需要 IDE纯命令行工具集的手动配置方式有些人不想用 Qt Creator只想用 Qt 库加自己的代码编辑器比如 VS Code那只需要把 Qt 的bin目录加入系统环境变量然后用 qmake 和编译器直接操作。具体做法右键“此电脑 - 属性 - 高级系统设置 - 环境变量”在用户变量的Path里追加D:\Qt\5.15.2\mingw81_64\bin路径根据你实际安装目录调整。如果你用 MSVC 工具链还需要在命令行里先执行 vcvars64.bat 初始化编译环境然后再用 nmake 或 jom 构建。这里有个小技巧同一台机器如果装了好几个 Qt 版本不建议把多个版本的bin都塞进 PATH否则 qmake 到底指向谁全看环境变量顺序。更规范的做法是每种项目在 Qt Creator 里指定单独的 Kit命令行开发则在每次编译前临时添加 PATH用完就关互不干扰。3. 编译器工具链补全与经典报错排查Qt 本体装好只算完成一半另一半在于编译器工具链的匹配。这一节重点聊 MSVC 场景下的工具链安装以及一个在网上被搜索了无数次的经典报错:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwid...。3.1 安装 MSVC 编译工具链Build Tools 还是完整版 Visual Studio如果你选的是 MSVC 工具链必须先决定装完整版 Visual Studio 还是只装 Build Tools独立编译工具集。两者的核心区别在于完整 VS 体积大、启动慢但内置 IDE、调试器、C 开发组件一应俱全Build Tools 则是“轻量编译器”只装命令行编译能力配 Qt Creator 足够。如果你是纯 Qt 开发装 Build Tools 更合适省得被 VS 那庞大的界面和自动更新拖累。下载时在 Visual Studio 安装器里勾选“使用 C 的桌面开发”工作负载即可。注意 Qt 5.15.2 官方包对应的是msvc2019_64也就是说官方预编译库是用 VS2019 工具集编的。如果你机器上装的是 VS2022虽然大多数情况下能通过设置打开 Qt 5.15.2 项目但最稳妥的做法是安装 VS2019 的编译工具集保证 mkspec 和运行库完全对齐。热词里出现的“vs2022 qt solutions”其实指的是 Qt 官方提供的 Visual Studio 集成插件。如果你坚持用 VS 做 Qt 开发可以给 VS 装上 Qt VS Tools 扩展用它来配置 Qt 版本路径。本质上它还是调用 Qt 的 qmake 和编译工具链只是把 CMake 配置、跟随文件生成这些步骤的复杂度替你处理掉了。3.2 破解经典 Qt 依赖报错那个长长的 dependent include 到底在说什么搜“qt 安装”进来的朋友很多人其实是被这一类报错逼来的。报错长这样:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets/qstyleoption.h does not exist.很多人一眼看到qt\5.15.2\msvc2019_64\include\qtwid...以为是不是自己的 Qt 安装坏了或者文件缺失。我用一句大白话解释这个报错说的是“编译器在按头文件依赖去找 Qt 头文件时跑到了一个不存在的路径”。注意里面那个..\..\..的层级说明这个路径是通过相对路径拼出来的而相对路径的起点是编译器的当前工作目录。如果工作目录和你 Qt 安装路径的层级关系错位编译器就会拼出一个不存在的路径。这个报错最常见的触发原因是 Kit 选择不匹配。比如你安装的是 MinGW 版 Qt但 Kit 里误选了 MSVC 编译器或者你在 Qt Creator 里打开了一个为 MSVC 写的项目但当前 Kit 是 MinGW又或者项目工程文件里写死了某个 Qt 版本路径。编译器用 A 套的工具链去解析 B 套的 include 路径路径层级当然会乱。解决办法按优先级操作第一在 Qt Creator 右下角或左侧的“构建套件选择器”里切换到与实际编译器匹配的 Kit第二执行“清理项目”再重新 qmake因为旧的 Makefile 和.pro.user文件里可能缓存了错误路径第三如果还不行删除项目目录下的build文件夹和.pro.user文件让 Qt Creator 重新构建配置第四检查.pro文件里是否有人为写死的绝对路径把它改成相对路径。这里我特别提醒一点不要为了解决这类报错去手动改 Qt 安装目录里的文件结构。很多人一看 include 路径报错就想去把msvc2019_64文件夹改名或者把 Qt 往工程目录里复制结果越弄越乱。Qt 的头文件路径是 mkspec 和 qmake 自动推导的你手动改目录结构只会让 qmake 生成的路径更不符合预期。3.3 环境变量与路径规范化别让中文目录和空格成为隐患Windows 上 Qt 开发的首选路径就是全英文、无空格。这不是玄学而是编译工具链的现实约束。CMake 对路径中的空格处理得还行但一些老旧的 make 工具、NMake、还有部分 Qt 插件源码里拼路径的方式对空格非常敏感。我自己就遇到过一个项目放在D:\My Projects\Demo用 Qt Creator 编译一切正常但换到命令行手动 qmake 之后就报找不到文件原因就是路径中的空格没被正确转义。如果你的工作目录里已经带了中文或空格别着急重新装 Qt试验一下先把整个工程文件移动到一个D:\qtwork\demo之类的干净路径下再重新构建。很多时候问题一下就消失了。还有一个环境变量层面的细节Qt 的编译过程中会读QTDIR或QMAKE这类变量有些教程会教你把它们手动设到系统环境变量里。但对普通开发机来说这些变量不是必须的设了反而容易造成多个 Qt 版本之间的干扰。我更推荐的方式让 Qt Creator 通过 Kit 管理 Qt 路径命令行开发时在.bat脚本里临时设置环境变量用完自动失效。3.4 Qt 崩溃类问题的提前预警“qt崩溃”能上热词说明很多人在安装和开发阶段都触发了程序崩溃。我这里列几个高频场景给你提前做心理建设。场景一是 Qt Creator 本身启动崩溃。多半是 OpenGL 驱动兼容问题Qt Creator 默认使用显卡加速渲染界面老旧驱动或虚拟机环境容易崩。可以尝试在启动命令行加参数-software或者修改环境变量QT_OPENGLsoftware强制 Qt Creator 走软件渲染。场景二是自己写的 Qt 程序一运行就崩溃。最常见的原因是 Debug 和 Release 的 DLL 混用比如你用 Release 编译的程序运行时却把Qt5Cored.dllDebug 版和Qt5Core.dllRelease 版搞混了。排查方法很简单用程序目录下实际加载的 DLL 版本和编译模式对照看一下。场景三是 Qt 5.15.2 在特定 Windows 版本上弹“0xc000007b”错误。这个错误码通常表示 DLL 位数不匹配或缺少 VC 运行库。检查你的编译架构x64 vs x86是否和运行的 DLL 一致同时装好对应版本的 Visual C Redistributable。4. Ubuntu / Linux 平台安装与版本共存Linux 上装 Qt 有两条截然不同的路径一条是用发行版自带的包管理器一条是下载官方安装器。两条我都用过各自适合的场景差异很大。4.1 apt 安装 vs 官网安装器先看你要的版本在不在源里用 Ubuntu 的apt install装 Qt 非常省事但它有两个硬性限制第一源里的版本通常比官网慢很多比如 Ubuntu 20.04 的默认源里是 Qt 5.12 或 5.14如果你需要 5.15.2 这个版本源里大概率没有得通过其他方式补第二apt 源里只提供基础库比如qtbase5-dev、qtdeclarative5-dev插件和扩展模块得一个个手动装非常零散。所以我给 Linux 新手的建议是如果是快速搭一个能编译 Qt 项目的环境直接sudo apt install qtbase5-dev qt5-qmake qtbase5-dev-tools够用如果需要指定版本、指定组件比如 5.15.2 完整开发环境那直接下载官方安装器或离线包装到~/Qt下更靠谱。Linux 下 Qt 官方在线安装器的运行方式是先给安装文件加执行权限然后./qt-unified-linux-x64-online.run。它会弹图形界面流程和 Windows 基本一致。如果你的服务器是无桌面环境可以用它带的命令行模式./qt-unified-linux-x64-online.run --default-answer --accept-licenses --confirm-command install qt.qt5.5152.gcc_64这个方式对自动化部署很友好。4.2 Linux 下安装时的依赖补齐缺库报错怎么读Linux 上 Qt 安装出错十有八九是系统缺共享库。Qt 在图形界面模块会依赖 X11、OpenGL、xkb 等一堆底层库缺一个安装器就在启动或运行时报错。常见缺库报错长这样error while loading shared libraries: libxcb-xinerama.so.0。遇到这类报错别慌先按提示搜包名。比如缺libxcb-xinerama.so.0在 Ubuntu 上通常执行sudo apt install libxcb-xinerama0就能解决。我给一套覆盖面比较全的依赖安装命令直接复制执行基本能解决大多数缺库问题sudo apt update sudo apt install libgl1-mesa-dev libglu1-mesa-dev libxkbcommon-x11-0 libxcb-xinerama0 libxcb-cursor0 \ libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0 \ libxcb-image0 libxcb-randr0 libxcb-xkb1 libxkbcommon-dev libxcb-xfixes0 \ libxcb-xv0 libxcb-util1 libxcb-xinput0 \ libssl-dev libdbus-1-dev这里有个大坑要特别说明Ubuntu 新版本22.04上 Qt 5 的某些模块在运行时会提示qt.qpa.plugin: Could not load the Qt platform plugin xcb。这个报错经常让新手以为安装失败实际上是因为libxcb-cursor0没装Qt 6.2 之后的 QPA 插件硬性依赖这个库。装上之后问题立刻消失。4.3 多版本共存/opt、~/Qt 与 qtchooser 的管理哲学Linux 下装多版本 Qt 是一件很自然的事比如同时装了系统 apt 源里的 Qt 5.12 和官网的 Qt 5.15.2开发时需要在两者间切换。两个版本其实可以共存关键是不能让 qmake 的查找路径乱掉。官方安装器默认会装到~/Qt目录各版本各编译器按子目录放好~/Qt/5.15.2/gcc_64/bin/qmake。apt 方式装的一般在/usr/lib/x86_64-linux-gnu/qt5/bin/qmake。手动切换的方式是在~/.bashrc里定义别名export PATH$HOME/Qt/5.15.2/gcc_64/bin:$PATH export CMAKE_PREFIX_PATH$HOME/Qt/5.15.2/gcc_64但这样写死后换版本就得改.bashrc。如果你需要更灵活的切换可以用qtchooser工具把不同 qmake 注册到配置文件中然后用qtchooser -qt5.15.2 -run-toolqmake这种方式按需调用。不过我实测下来日常开发总是固定在一个版本反而没必要把切换搞得复杂。真正需要同时维护多版本的人多半是同时在编译多个项目的 CI 环境那种场景更推荐用 Docker 容器隔离。5. 高频问题排查与实用速查表把上面这些经验和踩坑经历浓缩成一份速查表建议收藏。以后安装或编译遇到类似问题直接对着排查。问题现象可能原因快速解决Qt Creator 里看不到可用编译器Kits 为灰色编译器没装或 Qt 版本与工具链不匹配确认装了 MinGW 或 VS Build Tools在“选项 - Kits - 编译器”里手动添加匹配 qmake 路径编译报dependent ..\..\qt\5.15.2\msvc2019_64\include\... does not existKit 选错或构建目录缓存了错误路径切换正确 Kit清理 build 目录删除.pro.user重新构建qmake不是内部或外部命令Qt 的 bin 目录未加入 PATH把 Qt 的 bin 目录如D:\Qt\5.15.2\mingw81_64\bin加入系统 PATH或使用 Qt Creator 内置命令工具运行程序时报0xc000007bDLL 位数不匹配或缺少 VC 运行库检查编译架构与 DLL 架构一致性安装对应 VC Redistributable用Dependencies工具检查 DLL 依赖Ubuntu 上程序无法启动报Could not load platform plugin xcb缺libxcb-cursor0或同名系统库sudo apt install libxcb-cursor0 libxcb-*按需补齐后重新运行编译时报Cannot find -lGL缺少 OpenGL 开发库Linux 执行sudo apt install libgl1-mesa-devWindows 检查显卡驱动确认 OpenGL 可用Qt Creator 启动闪退或黑屏OpenGL 渲染兼容问题用qtcreator -software强制软件渲染或配置QT_OPENGLsoftware加装 MSVC 工具链后旧工程编译报海量 error旧的构建缓存仍指向 MinGW删除工程 build 目录重新构建检查.pro文件中的QMAKE设置卸载 Qt 不彻底残留影响新版本安装卸载工具未正确清理注册表、用户配置用安装目录下MaintenanceTool.exe卸载清理~/.config/QtLinux或注册表中 Qt 相关项Windows再说一个容易被忽略的细节Qt 安装目录里都有MaintenanceTool.exe它不仅负责卸载还能让你随时增删组件、更新版本。很多人卸载 Qt 时直接手动删文件夹导致注册表和用户配置残留一大堆垃圾下次装新版反而被旧配置干扰。正确做法永远是从MaintenanceTool走官方卸载流程。最后分享一个我自己的工程习惯拿到任何一台新电脑我装 Qt 的顺序是固定的——先装编译器再装 Qt 库然后打开 Qt Creator 先配置 Kit最后才新建测试工程。如果新机器上遇到诡异的环境问题我第一步会看 Kit 选择和构建目录而不是去动 Qt 安装文件。这个顺序帮我避开了无数看起来像“Qt 坏了”但其实是工具链误配的问题。Qt 的安装从来不是单纯的“下载、双击、下一步”它本质上是一个依赖管理问题。搞懂了版本、编译器、组件这三个维度的匹配逻辑不管是 Windows 还是 Linux不管你用 MinGW 还是 MSVC你都能快速判断问题出在哪一环。希望这篇基于真实踩坑经验写出来的安装实践指南能让你在第一次面对 Qt 时少走几步弯路。 
长河君 · 2026/10/3 3:37:55 · 阅读 1.2k Qt安装避坑指南：从版本选择到编译器工具链配置
刚拿到 Qt 安装包的时候大多数人的第一反应是“这有什么难的一路下一步不就行了”。等你真正装完、打开 Qt Creator、新建一个窗口工程结果发现编译器套件是灰的或者编译时报出一长串:-1: error: dependent ..\..\..\qt\5.15.2\msvc2019_64\include\qtwidget...这种莫名其妙的问题才会明白 Qt 的安装坑比想象中多。这篇博文不打算做那种“官网下载、双击 exe、下一步下一步”的流水账教程。我更想把从零到能跑通第一个 Qt 工程这件事讲透尤其针对 Windows 和 Linux 两条主路径把版本选择、编译器匹配、组件勾选、环境变量这些最劝退新人的环节拆开揉碎。无论你是刚接触 Qt 的小白还是以前用 MinGW 现在被迫切到 MSVC 的开发者或者只是想在自己电脑上把 Qt 环境快速捣鼓出来的学生党这篇文章都能当作一份可以直接照着抄的作业。1. 安装前的关键抉择先理清三件事再说下一步很多人的 Qt 安装失败其实不是手滑而是从一开始就选错了方案。安装 Qt 不像装微信装完就能用它必须解决“版本、编译器、开发工具链”这三个相互咬合的问题。这三个问题没想清楚后面每一步都会踩坑。1.1 版本怎么选LTS、经典版与新版之间的取舍Qt 的版本策略比较特殊它不搞“最新就是最好”那一套。官方每年都会发布新的功能版本比如 6.4、6.5、6.8但真正被工业界广泛使用的往往是 LTS长期支持版本因为 LTS 意味着官方会持续修复安全漏洞和关键 bug而且社区资源沉淀得足够厚。在 Windows 开发圈里5.15.2 是一个非常特殊的存在。它算是 Qt5 系列里口碑最好、兼容性最稳的版本之一很多教材、公司内部项目模板、开源项目的文档都基于它编写。即便 Qt6 发布好几年了你依然能在热词榜上看到大量“qt 5.15.2 下载安装”“qt 5.15.2 离线下载”的搜索说明这个版本的存量用户极其庞大。选版本时我给一个非常务实的建议如果只是自己学习、跟着书敲代码选 5.15.2 或 6.2 LTS 都行但优先 5.15.2因为遇到问题时代码一搜就能找到一堆答案如果是做新产品且不依赖老模块可以直接上 6.5 之后的 LTS如果项目已经定了版本那就别犹豫老老实实装指定版本不要擅自升级Qt 的模块差异和编译配置差异会让项目出现大量无谓的报错。1.2 编译器选择MinGW 还是 MSVC决定了你后面绕多少弯路Qt 官方在 Windows 平台上提供两套编译工具链MinGW 和 MSVC。这两者的区别不仅是编译器名字不同而是整个构建生态的差异。MinGW 是 GCC 在 Windows 上的移植版本优点是安装简单不需要额外装 Visual Studio下载 Qt 安装包时勾选一个 MinGW 编译器就能自己玩。对于初学者MinGW 的体验确实友好得多教材里“新建工程、点运行、弹出窗口”的流程它最符合。MSVC 是微软的 C 编译器它在 Windows 平台上的系统调用兼容性、调试器能力、性能调优方面都更强。很多商业项目、涉及 Windows 特有 API 的项目、还有需要接第三方 Windows SDK 的项目都会强制要求 MSVC 版本。但代价是你必须在机器上先装好 Visual Studio 或 Build Tools然后 Qt 才能识别到这套编译器。经常有人问能不能先装 MinGW 版以后需要了再装 MSVC可以但这两套工具链的代码不能混用同一个工程用 MinGW 编完的产物MSVC 认不了。我见过不少人两个都装了结果 Kit 选错编译时报一堆莫名其妙的头文件错误最后才反应过来是编译套件的问题。所以装之前先问自己我的项目后续方向是什么如果只是学习MinGW 足够如果是跟着公司项目走直接问清项目用哪套然后只装那一套别给自己制造选择题。1.3 在线安装器还是离线包时效、体积与网络环境之间的平衡Qt 的 Windows 安装包其实分成两种在线安装器安装时实时下载和离线安装包一次性下载完成后本地安装。很多人光顾着下载没搞清楚这两者区别以至于高速下错。在线安装器是一个很小的 exe运行后自己选择组件、版本然后边下载边装。它适合网络条件好、不介意等待的人而且组件选择灵活想装哪个模块随时可以再运行维护工具添加。但缺点也很明显国内网络环境下拖动官方服务器动辄几 KB一个大模块装几小时毫不夸张而且安装过程中断线后恢复不一定顺畅。离线安装包体积很大Qt 5.15.2 完整版离线包在 2GB 上下但它一次到位后续安装过程中不会因为网络波动卡死。离线包在下载时可以通过国内镜像站拉取比如清华源、中科大源这类正规开源镜像站一般都能跑满带宽。我的习惯是优先离线包尤其是要装 5.15.2 这个经典版本离线包只要校验好 SHA 哈希整个安装过程非常可控。2. Windows 环境下的完整安装实操推荐路线明确了版本和编译器之后下面这段是 Windows 下最顺滑的安装路线。我会以 Qt 5.15.2 离线包 MinGW 为主要示例同时在 2.4 节补充纯命令行工具用户需要的配置方式。2.1 下载离线包并校验文件别省这五分钟从镜像站下载时注意认准文件名格式官方离线包命名通常是qt-opensource-windows-x86-5.15.2.exe。如果你看到的是qt-unified-windows-x64-online-x.x.x.exe那是在线安装器别下错。下载完别急着双击先做两步。第一步核对文件大小如果镜像站标注了文件大小和 SHA-1 / MD5 哈希用工具校验一下避免下载过程损坏。第二步确认当前磁盘空间足够Qt 5.15.2 完整安装后占用大约 8-10GB如果你只选常用组件通常 3-5GB 也够但我建议至少预留 10GB因为后续还要缓存编译中间文件。安装路径的问题我多说一句虽然现在的 Qt 对中文路径容错好了很多但传统经验是尽量放在纯英文、无空格的路径下比如D:\Qt\5.15.2。有些第三方工具、CMake 脚本、脚本自动化工具对路径中的空格和中文处理不当一旦遇到那种“明明代码没错但编译产出异常”的问题排查一次的成本够你重装三遍 Qt。2.2 组件勾选对照表哪个必须装哪个可以跳过离线包双击后会弹出组件勾选界面。很多新手看到一串串英文复选框直接懵要么全选装到磁盘爆掉要么只勾了第一个装完发现连 Qt Creator 都没有。我整理一份经验导向的勾选清单以 5.15.2 为例组件分类建议勾选说明Qt Core / GUI / Widgets必选这三项是所有桌面应用的基础不装等于没装Qt QML / Quick学习中建议选如果你学 QML 界面开发勾上纯 Widgets 开发可以跳过以节省空间Qt Charts / Data Visualization按需画图表、三维可视化才需要很多开发向导类项目会用到Qt WebEngine不建议勾除非明确需要体积巨大编译也慢纯桌面应用基本用不上Developer and Designer Tools必选 Qt CreatorMinGW 按工具链需求选这里的 MinGW 版本是给你当编译器用的装了 MinGW 工具链就需要对应勾选CMake / Ninja建议勾上新版 Qt 越来越依赖 CMake装上省得后补勾选组件时有几个点容易踩坑。第一Qt Creator 和编译工具链是分开的如果你只勾了 Qt 库本身没勾 Qt Creator装完也找不到 IDE。第二如果你需要 MSVC 编译环境安装器里其实不会给你装 Visual Studio它只能带着识别已有的 VS 工具链所以 MSVC 用户必须先装好 VS 或 Build Tools 再装 Qt。第三同一个 Qt 版本下可以勾多个编译套件比如同时勾 MinGW 和 MSVC但这容易让后续 Kit 选择变得复杂新手建议先只勾一个。2.3 安装后的三个自检动作qmake、Qt Creator、示例工程安装完成后先别急着写代码花五分钟做三个检查能帮你在源头排除八成环境问题。第一步打开命令行输入qmake -v正常情况下能看到 qmake 版本和它基于的 Qt 版本。如果提示“不是内部或外部命令”说明 qmake 没进 PATH或者你还没把 Qt 的bin目录手动加进去。对于离线包和在线安装器Qt 通常会在自己的目录里写配置文件让 Qt Creator 能自己找到 qmake但命令行工具需要的 PATH 得自己处理。第二步打开 Qt Creator在“工具 - 选项 - Kits - 编译器”里确认能看到对应编译器。如果 Kits 页面显示“No suitable kits found”那基本可以确定是编译器没被识别。第三步新建一个默认的Qt Widgets Application点“构建”如果能顺利编译出一个空窗口并运行那环境就算立住了。不要直接拿别人的工程试第一轮先用官方模板验证环境才能把“环境问题”和“代码问题”分开。2.4 不需要 IDE纯命令行工具集的手动配置方式有些人不想用 Qt Creator只想用 Qt 库加自己的代码编辑器比如 VS Code那只需要把 Qt 的bin目录加入系统环境变量然后用 qmake 和编译器直接操作。具体做法右键“此电脑 - 属性 - 高级系统设置 - 环境变量”在用户变量的Path里追加D:\Qt\5.15.2\mingw81_64\bin路径根据你实际安装目录调整。如果你用 MSVC 工具链还需要在命令行里先执行 vcvars64.bat 初始化编译环境然后再用 nmake 或 jom 构建。这里有个小技巧同一台机器如果装了好几个 Qt 版本不建议把多个版本的bin都塞进 PATH否则 qmake 到底指向谁全看环境变量顺序。更规范的做法是每种项目在 Qt Creator 里指定单独的 Kit命令行开发则在每次编译前临时添加 PATH用完就关互不干扰。3. 编译器工具链补全与经典报错排查Qt 本体装好只算完成一半另一半在于编译器工具链的匹配。这一节重点聊 MSVC 场景下的工具链安装以及一个在网上被搜索了无数次的经典报错:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwid...。3.1 安装 MSVC 编译工具链Build Tools 还是完整版 Visual Studio如果你选的是 MSVC 工具链必须先决定装完整版 Visual Studio 还是只装 Build Tools独立编译工具集。两者的核心区别在于完整 VS 体积大、启动慢但内置 IDE、调试器、C 开发组件一应俱全Build Tools 则是“轻量编译器”只装命令行编译能力配 Qt Creator 足够。如果你是纯 Qt 开发装 Build Tools 更合适省得被 VS 那庞大的界面和自动更新拖累。下载时在 Visual Studio 安装器里勾选“使用 C 的桌面开发”工作负载即可。注意 Qt 5.15.2 官方包对应的是msvc2019_64也就是说官方预编译库是用 VS2019 工具集编的。如果你机器上装的是 VS2022虽然大多数情况下能通过设置打开 Qt 5.15.2 项目但最稳妥的做法是安装 VS2019 的编译工具集保证 mkspec 和运行库完全对齐。热词里出现的“vs2022 qt solutions”其实指的是 Qt 官方提供的 Visual Studio 集成插件。如果你坚持用 VS 做 Qt 开发可以给 VS 装上 Qt VS Tools 扩展用它来配置 Qt 版本路径。本质上它还是调用 Qt 的 qmake 和编译工具链只是把 CMake 配置、跟随文件生成这些步骤的复杂度替你处理掉了。3.2 破解经典 Qt 依赖报错那个长长的 dependent include 到底在说什么搜“qt 安装”进来的朋友很多人其实是被这一类报错逼来的。报错长这样:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets/qstyleoption.h does not exist.很多人一眼看到qt\5.15.2\msvc2019_64\include\qtwid...以为是不是自己的 Qt 安装坏了或者文件缺失。我用一句大白话解释这个报错说的是“编译器在按头文件依赖去找 Qt 头文件时跑到了一个不存在的路径”。注意里面那个..\..\..的层级说明这个路径是通过相对路径拼出来的而相对路径的起点是编译器的当前工作目录。如果工作目录和你 Qt 安装路径的层级关系错位编译器就会拼出一个不存在的路径。这个报错最常见的触发原因是 Kit 选择不匹配。比如你安装的是 MinGW 版 Qt但 Kit 里误选了 MSVC 编译器或者你在 Qt Creator 里打开了一个为 MSVC 写的项目但当前 Kit 是 MinGW又或者项目工程文件里写死了某个 Qt 版本路径。编译器用 A 套的工具链去解析 B 套的 include 路径路径层级当然会乱。解决办法按优先级操作第一在 Qt Creator 右下角或左侧的“构建套件选择器”里切换到与实际编译器匹配的 Kit第二执行“清理项目”再重新 qmake因为旧的 Makefile 和.pro.user文件里可能缓存了错误路径第三如果还不行删除项目目录下的build文件夹和.pro.user文件让 Qt Creator 重新构建配置第四检查.pro文件里是否有人为写死的绝对路径把它改成相对路径。这里我特别提醒一点不要为了解决这类报错去手动改 Qt 安装目录里的文件结构。很多人一看 include 路径报错就想去把msvc2019_64文件夹改名或者把 Qt 往工程目录里复制结果越弄越乱。Qt 的头文件路径是 mkspec 和 qmake 自动推导的你手动改目录结构只会让 qmake 生成的路径更不符合预期。3.3 环境变量与路径规范化别让中文目录和空格成为隐患Windows 上 Qt 开发的首选路径就是全英文、无空格。这不是玄学而是编译工具链的现实约束。CMake 对路径中的空格处理得还行但一些老旧的 make 工具、NMake、还有部分 Qt 插件源码里拼路径的方式对空格非常敏感。我自己就遇到过一个项目放在D:\My Projects\Demo用 Qt Creator 编译一切正常但换到命令行手动 qmake 之后就报找不到文件原因就是路径中的空格没被正确转义。如果你的工作目录里已经带了中文或空格别着急重新装 Qt试验一下先把整个工程文件移动到一个D:\qtwork\demo之类的干净路径下再重新构建。很多时候问题一下就消失了。还有一个环境变量层面的细节Qt 的编译过程中会读QTDIR或QMAKE这类变量有些教程会教你把它们手动设到系统环境变量里。但对普通开发机来说这些变量不是必须的设了反而容易造成多个 Qt 版本之间的干扰。我更推荐的方式让 Qt Creator 通过 Kit 管理 Qt 路径命令行开发时在.bat脚本里临时设置环境变量用完自动失效。3.4 Qt 崩溃类问题的提前预警“qt崩溃”能上热词说明很多人在安装和开发阶段都触发了程序崩溃。我这里列几个高频场景给你提前做心理建设。场景一是 Qt Creator 本身启动崩溃。多半是 OpenGL 驱动兼容问题Qt Creator 默认使用显卡加速渲染界面老旧驱动或虚拟机环境容易崩。可以尝试在启动命令行加参数-software或者修改环境变量QT_OPENGLsoftware强制 Qt Creator 走软件渲染。场景二是自己写的 Qt 程序一运行就崩溃。最常见的原因是 Debug 和 Release 的 DLL 混用比如你用 Release 编译的程序运行时却把Qt5Cored.dllDebug 版和Qt5Core.dllRelease 版搞混了。排查方法很简单用程序目录下实际加载的 DLL 版本和编译模式对照看一下。场景三是 Qt 5.15.2 在特定 Windows 版本上弹“0xc000007b”错误。这个错误码通常表示 DLL 位数不匹配或缺少 VC 运行库。检查你的编译架构x64 vs x86是否和运行的 DLL 一致同时装好对应版本的 Visual C Redistributable。4. Ubuntu / Linux 平台安装与版本共存Linux 上装 Qt 有两条截然不同的路径一条是用发行版自带的包管理器一条是下载官方安装器。两条我都用过各自适合的场景差异很大。4.1 apt 安装 vs 官网安装器先看你要的版本在不在源里用 Ubuntu 的apt install装 Qt 非常省事但它有两个硬性限制第一源里的版本通常比官网慢很多比如 Ubuntu 20.04 的默认源里是 Qt 5.12 或 5.14如果你需要 5.15.2 这个版本源里大概率没有得通过其他方式补第二apt 源里只提供基础库比如qtbase5-dev、qtdeclarative5-dev插件和扩展模块得一个个手动装非常零散。所以我给 Linux 新手的建议是如果是快速搭一个能编译 Qt 项目的环境直接sudo apt install qtbase5-dev qt5-qmake qtbase5-dev-tools够用如果需要指定版本、指定组件比如 5.15.2 完整开发环境那直接下载官方安装器或离线包装到~/Qt下更靠谱。Linux 下 Qt 官方在线安装器的运行方式是先给安装文件加执行权限然后./qt-unified-linux-x64-online.run。它会弹图形界面流程和 Windows 基本一致。如果你的服务器是无桌面环境可以用它带的命令行模式./qt-unified-linux-x64-online.run --default-answer --accept-licenses --confirm-command install qt.qt5.5152.gcc_64这个方式对自动化部署很友好。4.2 Linux 下安装时的依赖补齐缺库报错怎么读Linux 上 Qt 安装出错十有八九是系统缺共享库。Qt 在图形界面模块会依赖 X11、OpenGL、xkb 等一堆底层库缺一个安装器就在启动或运行时报错。常见缺库报错长这样error while loading shared libraries: libxcb-xinerama.so.0。遇到这类报错别慌先按提示搜包名。比如缺libxcb-xinerama.so.0在 Ubuntu 上通常执行sudo apt install libxcb-xinerama0就能解决。我给一套覆盖面比较全的依赖安装命令直接复制执行基本能解决大多数缺库问题sudo apt update sudo apt install libgl1-mesa-dev libglu1-mesa-dev libxkbcommon-x11-0 libxcb-xinerama0 libxcb-cursor0 \ libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-render-util0 \ libxcb-image0 libxcb-randr0 libxcb-xkb1 libxkbcommon-dev libxcb-xfixes0 \ libxcb-xv0 libxcb-util1 libxcb-xinput0 \ libssl-dev libdbus-1-dev这里有个大坑要特别说明Ubuntu 新版本22.04上 Qt 5 的某些模块在运行时会提示qt.qpa.plugin: Could not load the Qt platform plugin xcb。这个报错经常让新手以为安装失败实际上是因为libxcb-cursor0没装Qt 6.2 之后的 QPA 插件硬性依赖这个库。装上之后问题立刻消失。4.3 多版本共存/opt、~/Qt 与 qtchooser 的管理哲学Linux 下装多版本 Qt 是一件很自然的事比如同时装了系统 apt 源里的 Qt 5.12 和官网的 Qt 5.15.2开发时需要在两者间切换。两个版本其实可以共存关键是不能让 qmake 的查找路径乱掉。官方安装器默认会装到~/Qt目录各版本各编译器按子目录放好~/Qt/5.15.2/gcc_64/bin/qmake。apt 方式装的一般在/usr/lib/x86_64-linux-gnu/qt5/bin/qmake。手动切换的方式是在~/.bashrc里定义别名export PATH$HOME/Qt/5.15.2/gcc_64/bin:$PATH export CMAKE_PREFIX_PATH$HOME/Qt/5.15.2/gcc_64但这样写死后换版本就得改.bashrc。如果你需要更灵活的切换可以用qtchooser工具把不同 qmake 注册到配置文件中然后用qtchooser -qt5.15.2 -run-toolqmake这种方式按需调用。不过我实测下来日常开发总是固定在一个版本反而没必要把切换搞得复杂。真正需要同时维护多版本的人多半是同时在编译多个项目的 CI 环境那种场景更推荐用 Docker 容器隔离。5. 高频问题排查与实用速查表把上面这些经验和踩坑经历浓缩成一份速查表建议收藏。以后安装或编译遇到类似问题直接对着排查。问题现象可能原因快速解决Qt Creator 里看不到可用编译器Kits 为灰色编译器没装或 Qt 版本与工具链不匹配确认装了 MinGW 或 VS Build Tools在“选项 - Kits - 编译器”里手动添加匹配 qmake 路径编译报dependent ..\..\qt\5.15.2\msvc2019_64\include\... does not existKit 选错或构建目录缓存了错误路径切换正确 Kit清理 build 目录删除.pro.user重新构建qmake不是内部或外部命令Qt 的 bin 目录未加入 PATH把 Qt 的 bin 目录如D:\Qt\5.15.2\mingw81_64\bin加入系统 PATH或使用 Qt Creator 内置命令工具运行程序时报0xc000007bDLL 位数不匹配或缺少 VC 运行库检查编译架构与 DLL 架构一致性安装对应 VC Redistributable用Dependencies工具检查 DLL 依赖Ubuntu 上程序无法启动报Could not load platform plugin xcb缺libxcb-cursor0或同名系统库sudo apt install libxcb-cursor0 libxcb-*按需补齐后重新运行编译时报Cannot find -lGL缺少 OpenGL 开发库Linux 执行sudo apt install libgl1-mesa-devWindows 检查显卡驱动确认 OpenGL 可用Qt Creator 启动闪退或黑屏OpenGL 渲染兼容问题用qtcreator -software强制软件渲染或配置QT_OPENGLsoftware加装 MSVC 工具链后旧工程编译报海量 error旧的构建缓存仍指向 MinGW删除工程 build 目录重新构建检查.pro文件中的QMAKE设置卸载 Qt 不彻底残留影响新版本安装卸载工具未正确清理注册表、用户配置用安装目录下MaintenanceTool.exe卸载清理~/.config/QtLinux或注册表中 Qt 相关项Windows再说一个容易被忽略的细节Qt 安装目录里都有MaintenanceTool.exe它不仅负责卸载还能让你随时增删组件、更新版本。很多人卸载 Qt 时直接手动删文件夹导致注册表和用户配置残留一大堆垃圾下次装新版反而被旧配置干扰。正确做法永远是从MaintenanceTool走官方卸载流程。最后分享一个我自己的工程习惯拿到任何一台新电脑我装 Qt 的顺序是固定的——先装编译器再装 Qt 库然后打开 Qt Creator 先配置 Kit最后才新建测试工程。如果新机器上遇到诡异的环境问题我第一步会看 Kit 选择和构建目录而不是去动 Qt 安装文件。这个顺序帮我避开了无数看起来像“Qt 坏了”但其实是工具链误配的问题。Qt 的安装从来不是单纯的“下载、双击、下一步”它本质上是一个依赖管理问题。搞懂了版本、编译器、组件这三个维度的匹配逻辑不管是 Windows 还是 Linux不管你用 MinGW 还是 MSVC你都能快速判断问题出在哪一环。希望这篇基于真实踩坑经验写出来的安装实践指南能让你在第一次面对 Qt 时少走几步弯路。