Qt Creator从零安装配置与CMake项目实战避坑指南

1. 为什么Qt Creator值得你花时间折腾

如果你正在看这篇文章，大概率是遇到了下面几种情况之一：想学C++但不知道用什么写代码，听说Qt能做出带界面的桌面软件但装了半天没跑起来，或者被Visual Studio那几十个G的安装包劝退了。我当初也是这么过来的，第一次装Qt的时候，下载器卡在百分之零不动，换了好几个版本才搞明白里面的门道。

Qt Creator是Qt官方提供的一个跨平台集成开发环境，说白了就是一个写代码、编译、调试、看运行结果的地方。它跟Visual Studio、CLion、VS Code是同一类东西，但它的特殊之处在于跟Qt框架绑定得非常紧。你用Qt Creator写C++，能直接拖控件做界面，能一键切换编译目标到Windows、Linux甚至移动端，这是其他IDE很难做到的。

这篇文章我会从零开始，把Qt Creator的下载、安装、环境配置、CMake项目创建、常见报错处理全部走一遍。不管你是刚学C++的新手，还是从其他IDE转过来的老手，跟着走一遍基本都能跑通。我踩过的坑你就不用再踩了，尤其是那些安装器卡死、编译器找不到、CMake报错的经典问题，后面都会一个一个拆开讲。

提示：Qt的安装器在国内网络环境下经常出现下载缓慢或卡住的情况，这不是你电脑的问题，后面会给出具体的应对方法。

2. 安装前的准备工作与版本选择

2.1 先搞清楚Qt的版本体系

很多人一上来就懵了，Qt的版本号看起来乱七八糟的。我简单梳理一下：Qt目前主要分两个大版本线，Qt 5和Qt 6。Qt 5的最后一个长期支持版本是5.15，Qt 6目前主流是6.5、6.6、6.7这几个。对于新手来说，我建议直接用Qt 6的较新版本，因为Qt 5已经停止公开更新了，新项目没必要从老版本开始。

但这里有个坑要注意：Qt 6对C++标准的要求是C++17起步，如果你的编译器太老，编译会直接报错。所以选版本的时候要跟你的编译器匹配。Windows上一般用MinGW或者MSVC，Linux上一般用系统自带的GCC。

另一个概念是在线安装器和离线安装包的区别。Qt官方现在主推在线安装器，你下载一个几MB的小程序，然后它再从服务器上拉取你勾选的组件。离线包是把所有东西打包成一个大的安装文件，下载完直接装。在线安装器的好处是灵活，坏处是网络不好的时候容易卡。离线包的好处是稳定，坏处是文件大、版本更新慢。

2.2 注册Qt账号这件事

从Qt 5.15开始，在线安装器要求你必须登录一个Qt账号才能继续。这个账号是免费的，注册过程也不复杂，但有一点要注意：注册时使用的邮箱尽量用常用的，因为后续如果要在Qt Creator里使用一些在线服务，会跟这个账号关联。

我遇到过有人注册完账号之后忘了密码，结果安装器卡在登录界面进不去。所以注册完最好把账号密码记一下，或者直接用浏览器记住密码。

2.3 磁盘空间和系统要求

Qt Creator本身不大，几百MB的事，但如果你勾选了好几个Qt版本和编译器，那占用的空间就上去了。我建议至少预留20GB的磁盘空间，因为：

• Qt Creator本体：约500MB
• 一个Qt 6版本的库文件：约2-3GB
• MinGW编译器：约1-2GB
• 源码和调试符号（可选）：约5-8GB
• 项目编译产生的中间文件：看项目大小，几个GB很正常

系统方面，Windows 10及以上、Ubuntu 20.04及以上、macOS 11及以上都没问题。内存建议8GB起步，16GB会更舒服，因为Qt Creator加上编译过程还是比较吃内存的。

3. 手把手完成Qt Creator安装

3.1 下载安装器的正确姿势

打开Qt官网的下载页面，找到“Download the Qt Online Installer”这个按钮。这里要注意，页面可能会根据你的操作系统自动推荐对应的安装器，Windows用户下载到的是.exe文件，Linux用户下载到的是.run文件，macOS用户下载到的是.dmg文件。

下载完成之后，Windows用户直接双击运行。但这里有个常见问题：安装器打开后界面一片空白或者一直转圈。这个问题的原因通常是安装器需要从服务器拉取组件列表，网络不通畅就会卡住。

我试过几种解决办法，最有效的是用命令行参数启动安装器，指定一个国内的镜像源。具体操作是：打开命令提示符，切换到安装器所在的目录，然后执行：

installer.exe --mirror https://mirrors.ustc.edu.cn/qtproject/

这个命令会让安装器从中科大的镜像站拉取组件列表，速度会快很多。如果中科大的镜像不稳定，也可以换成清华的：

installer.exe --mirror https://mirrors.tuna.tsinghua.edu.cn/qt/

Linux用户的操作类似，给.run文件加上执行权限后运行：

chmod +x qt-unified-linux-x64-online.run ./qt-unified-linux-x64-online.run --mirror https://mirrors.ustc.edu.cn/qtproject/

注意：镜像源地址可能会随时间变化，如果上面两个地址失效了，可以搜索“Qt镜像源”找最新的可用地址。

3.2 安装过程中的组件勾选

登录账号之后，安装器会让你选择安装路径。这里我建议不要装在C盘默认路径下，因为Qt的东西比较多，C盘空间紧张的话后面会很麻烦。我一般装在D:\Qt或者/opt/Qt这样的路径下，路径中不要有中文和空格，否则后面编译的时候可能出现莫名其妙的错误。

接下来是组件选择页面，这是最关键的一步。页面左侧是一个树形结构，你需要展开各个节点来勾选具体组件。我按重要性给你列一下：

这里重点说一下MinGW和MSVC的选择。MinGW是GCC在Windows上的移植版本，安装包小、配置简单，适合新手。MSVC是微软的编译器，跟Visual Studio配套，编译出来的程序性能可能稍好，但需要你先装Visual Studio。如果你电脑上已经有Visual Studio了，可以两个都选，后面在Qt Creator里可以切换。

还有一个容易忽略的点：Qt Creator的版本和Qt库的版本是分开的。你可以在Qt Creator里配置多个Qt版本，每个版本对应不同的编译器。所以安装的时候Qt Creator只需要装一个就行，不用每个Qt版本都配一个。

3.3 安装完成后的目录结构

安装完成后，你的Qt目录大概长这样：

Qt/ ├── Qt/ │ ├── 6.7.0/ │ │ ├── mingw_64/ │ │ ├── msvc2019_64/ │ │ └── ... │ └── Tools/ │ ├── CMake/ │ ├── Ninja/ │ ├── mingw1120_64/ │ └── QtCreator/ └── ...

Qt/6.7.0/mingw_64里面是Qt的库文件和头文件，Tools里面是各种工具。Qt Creator在Tools/QtCreator/bin下面，你可以直接运行qtcreator.exe启动。

4. 环境配置与编译器设置

4.1 首次启动Qt Creator的配置向导

第一次打开Qt Creator，它会自动检测你安装的Qt版本和编译器。正常情况下，它会弹出一个配置页面，列出检测到的Kit。Kit是Qt Creator里的一个核心概念，你可以把它理解成“一套编译环境”，包含Qt版本、编译器、调试器、构建工具这几个要素。

如果自动检测成功，你会看到类似“Desktop Qt 6.7.0 MinGW 64-bit”这样的Kit，前面有一个绿色的勾。如果显示的是灰色的或者有感叹号，说明某个组件没检测到，需要手动配置。

我遇到过最常见的情况是CMake没被自动检测到。这时候你需要手动指定CMake的路径，一般在Qt/Tools/CMake/bin/cmake.exe。同样的，Ninja的路径在Qt/Tools/Ninja/ninja.exe。

4.2 手动添加编译器和Qt版本

如果自动检测完全失败，你可以手动添加。步骤是：打开“工具”菜单，选择“选项”，然后找到“Kits”页面。

在“编译器”标签页里，点击“添加”，选择“GCC”或者“MinGW”，然后指定编译器的路径。MinGW的编译器在Qt/Tools/mingw1120_64/bin/gcc.exe和g++.exe。

在“Qt Versions”标签页里，点击“添加”，指定qmake的路径。qmake在Qt/6.7.0/mingw_64/bin/qmake.exe。

最后回到“Kits”标签页，点击“添加”，把刚才配置的编译器和Qt版本组合起来，再指定CMake和Ninja的路径，一个完整的Kit就配好了。

4.3 环境变量要不要配

很多人纠结要不要把Qt的bin目录加到系统环境变量PATH里。我的建议是：如果你只用Qt Creator开发，不需要配。Qt Creator启动的时候会自动设置好环境变量，你直接在IDE里点运行就能跑。

但如果你需要在命令行里用qmake或者windeployqt这些工具，那就需要配。配的时候注意，不要把多个Qt版本的bin目录同时加到PATH里，否则会出现版本冲突。我见过有人同时装了Qt 5和Qt 6，两个bin目录都在PATH里，结果命令行里运行qmake的时候调用了错误的版本，编译出来的程序跑不起来。

提示：如果你确实需要频繁在命令行使用Qt工具，可以写一个批处理脚本，临时设置PATH，而不是永久加到系统环境变量里。

5. 创建第一个CMake项目

5.1 为什么Qt 6默认用CMake

Qt 5的时代，qmake是官方主推的构建工具。但从Qt 6开始，CMake成了默认的构建系统。这个变化的原因很简单：CMake的生态更大，跨平台支持更好，而且很多第三方库都优先支持CMake。qmake虽然还在维护，但新项目建议直接用CMake。

CMake的工作方式是：你写一个CMakeLists.txt文件，描述你的项目需要哪些源文件、链接哪些库、生成什么目标。然后CMake根据这个文件生成对应平台的构建文件（Windows上是Makefile或者Ninja文件，Linux上是Makefile），最后调用编译器完成编译。

5.2 新建项目的完整流程

打开Qt Creator，点击“文件”菜单，选择“新建文件或项目”。在弹出的向导里，选择“Application (Qt)”下面的“Qt Widgets Application”，然后点“Choose”。

接下来几步分别是：

1. 项目名称和路径：名称用英文，路径不要有中文和空格。比如D:\Projects\HelloQt。
2. 构建系统：选择CMake。你会看到qmake也在选项里，但我们用CMake。
3. 类信息：基类选QMainWindow，类名用默认的MainWindow就行。这里会生成三个文件：mainwindow.h、mainwindow.cpp、mainwindow.ui。
4. 翻译文件：不需要，直接下一步。
5. Kit选择：勾选你之前配置好的Kit，比如“Desktop Qt 6.7.0 MinGW 64-bit”。
6. 版本控制：选“无”，新手用不上。

点击“完成”之后，Qt Creator会自动生成项目文件并打开。

5.3 CMakeLists.txt逐行解读

生成的CMakeLists.txt大概长这样：

cmake_minimum_required(VERSION 3.16) project(HelloQt VERSION 0.1 LANGUAGES CXX) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt6 REQUIRED COMPONENTS Widgets) add_executable(HelloQt main.cpp mainwindow.cpp mainwindow.h mainwindow.ui ) target_link_libraries(HelloQt PRIVATE Qt6::Widgets)

我逐行解释一下关键部分：

cmake_minimum_required(VERSION 3.16)指定了CMake的最低版本要求。Qt 6.7要求CMake至少3.16，如果你系统里的CMake版本太低，这里会报错。

project(HelloQt VERSION 0.1 LANGUAGES CXX)定义了项目名称和使用的语言。LANGUAGES CXX表示这是一个C++项目。

set(CMAKE_AUTOUIC ON)开启UI文件的自动处理。你修改.ui文件后，CMake会自动调用uic工具把它转换成C++头文件。

set(CMAKE_AUTOMOC ON)开启MOC的自动处理。Qt的信号槽机制需要MOC（元对象编译器）来处理带有Q_OBJECT宏的类，这个选项让CMake自动完成这一步。

set(CMAKE_AUTORCC ON)开启资源文件的自动处理。如果你有.qrc资源文件，CMake会自动调用rcc工具。

find_package(Qt6 REQUIRED COMPONENTS Widgets)查找Qt 6的Widgets模块。REQUIRED表示如果找不到就报错停止。

target_link_libraries(HelloQt PRIVATE Qt6::Widgets)把Widgets模块链接到你的可执行文件上。

5.4 编译运行与常见报错

点击左下角的绿色三角形按钮，Qt Creator会依次执行CMake配置、生成构建文件、编译、链接、运行。如果一切顺利，你会看到一个空白的窗口弹出来。

但第一次编译往往会遇到问题。我列几个最常见的：

报错一：fatal: cannot mix incompatible qt library (version ex50601) with this library

这个报错的意思是，你的程序在运行时加载了错误版本的Qt库。通常是因为系统PATH里有一个旧版本的Qt，而你的程序是用新版本编译的。解决办法是检查环境变量，把旧版本的Qt路径从PATH里移除，或者在Qt Creator的“项目”设置里，把“运行”配置中的环境变量调整一下，确保优先加载正确版本的库。

报错二：CMake Error at .../CMakeDetermineCompilerId.cmake:9

这个报错通常出现在Linux上，原因是CMake找不到可用的C++编译器。你需要确认系统里装了GCC和G++，可以用gcc --version和g++ --version检查。如果没装，用包管理器安装：

sudo apt install build-essential

报错三：qt.qpa.plugin: Could not find the Qt platform plugin "linuxfb"

这个报错说明Qt在运行时找不到平台插件。Linux上常见的平台插件是xcb，如果你在无图形界面的环境下运行，需要指定-platform offscreen参数。如果是正常桌面环境，检查Qt/6.7.0/gcc_64/plugins/platforms目录下是否有libqxcb.so文件。

6. 高频问题排查与避坑指南

6.1 安装器卡死与下载失败的应对

Qt在线安装器卡死是最常见的问题，没有之一。我总结了几种情况和对策：

如果在线安装器实在搞不定，可以考虑用离线安装包。Qt官方会不定期发布离线包，虽然版本可能不是最新的，但胜在稳定。另外，一些高校的镜像站也会提供离线包的下载。

6.2 编译器找不到的排查思路

Qt Creator提示“No compiler found”或者Kit前面有感叹号，排查步骤是这样的：

第一步，确认编译器是否真的安装了。去Qt/Tools目录下看看有没有mingw1120_64这样的文件夹。如果没有，说明安装的时候没勾选编译器组件，需要重新运行安装器补上。

第二步，确认Qt Creator里的编译器路径是否正确。打开“工具”→“选项”→“Kits”→“编译器”，看看列表里有没有对应的编译器。如果没有，手动添加，指定到gcc.exe和g++.exe。

第三步，确认Kit的配置是否完整。一个Kit需要同时指定编译器、Qt版本、CMake、Ninja、调试器。任何一项缺失都会导致Kit不可用。调试器一般在Qt/Tools/mingw1120_64/bin/gdb.exe。

6.3 CMake配置失败的典型场景

CMake报错的信息通常比较长，但关键信息一般在最后几行。我整理了几个典型场景：

场景一：找不到Qt6的包

Could not find a package configuration file provided by "Qt6"

原因是find_package(Qt6 ...)没有找到Qt的CMake配置文件。解决办法是在CMakeLists.txt里显式指定Qt的安装路径：

set(CMAKE_PREFIX_PATH "D:/Qt/6.7.0/mingw_64") find_package(Qt6 REQUIRED COMPONENTS Widgets)

或者在Qt Creator的Kit设置里，确认Qt版本指向了正确的qmake路径。

场景二：C++标准不匹配

error: 'auto' type specifier is not allowed in this context

这种报错说明编译器用的C++标准太低。在CMakeLists.txt里加上：

set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON)

场景三：Ninja找不到

CMake Error: CMake was unable to find a build program corresponding to "Ninja"

在Kit设置里指定Ninja的路径，一般在Qt/Tools/Ninja/ninja.exe。

6.4 代码编辑的实用技巧

Qt Creator的代码编辑器有一些很实用的功能，但默认配置可能不太顺手。我分享几个我常用的设置：

代码对齐快捷键：默认是Ctrl+I，但很多人反映不好用。你可以在“工具”→“选项”→“环境”→“键盘”里搜索“AutoIndent”或者“Format”，重新绑定一个顺手的快捷键。我一般绑成Ctrl+Shift+I。

代码补全：Qt Creator的补全默认是Ctrl+Space，但跟系统输入法切换冲突。可以在键盘设置里改成Alt+/。

快速切换头文件和源文件：快捷键是F4，在.h和.cpp之间快速跳转，非常方便。

查找符号：Ctrl+K可以快速定位到某个函数或类的定义。

6.5 关于Qt版本冲突的深入分析

前面提到的cannot mix incompatible qt library这个报错，值得单独展开讲一下。这个问题的本质是动态链接库的加载顺序问题。

你的程序在运行时，操作系统会按照一定的顺序查找依赖的DLL（Windows）或so（Linux）文件。在Windows上，查找顺序大致是：程序所在目录 → 系统目录 → PATH环境变量中的目录。如果你的PATH里有一个旧版本的Qt，而程序目录下没有对应的DLL，系统就会加载旧版本的库，导致版本不匹配。

解决办法有几种：

第一种，用windeployqt工具把需要的DLL复制到程序目录下。在Qt Creator的“项目”设置里，有一个“部署”步骤，可以配置自动执行windeployqt。

第二种，在Qt Creator的“运行”设置里，修改环境变量，把正确的Qt bin目录放在PATH的最前面。

第三种，在代码里用QCoreApplication::addLibraryPath()显式指定插件路径。

我一般用第一种，因为最省事，而且发布程序的时候也需要把DLL带上。

7. 从Qt Creator出发的后续学习路径

装好Qt Creator只是第一步，后面还有很多东西可以学。我简单说一下我自己的学习路径，供你参考。

第一阶段：熟悉Qt Widgets的基本控件。按钮、文本框、标签、布局管理器这些是最基础的。你可以试着做一个简单的计算器或者记事本，把信号槽机制用熟。

第二阶段：理解Qt的核心机制。信号槽、事件循环、内存管理（对象树）、元对象系统，这几个是Qt的根基。特别是信号槽，它是Qt区别于其他C++框架的最大特色。

第三阶段：学习CMake的进阶用法。多模块项目、第三方库集成、条件编译、安装规则，这些在实际项目中都会用到。比如你有一个顶层CMakeLists.txt，下面有多个子目录，每个子目录有自己的CMakeLists.txt，这种多模块结构在大型项目中很常见。

第四阶段：尝试Qt Quick/QML。如果你要做移动端或者现代化的界面，QML是更好的选择。它用声明式语法描述界面，跟C++后端通过信号槽或者属性绑定交互。

第五阶段：跨平台编译。Qt支持交叉编译到Android、iOS、嵌入式Linux等平台。比如你想编译一个Android的APK，需要配置Android NDK和SDK，然后在Qt Creator里添加对应的Kit。

提示：学习过程中遇到问题，优先查Qt的官方文档。Qt的文档质量在开源项目里算是很高的，每个类都有详细的说明和示例代码。

8. 我个人的几条实操心得

最后分享几条我在实际使用中总结的经验，都是文档里不会写的。

关于安装路径：不管你用Windows还是Linux，Qt的安装路径里绝对不要有中文和空格。我见过有人装在D:\软件\Qt下面，结果CMake配置的时候路径解析出错，排查了半天才发现是中文路径的问题。

关于多个Qt版本共存：如果你同时装了Qt 5和Qt 6，建议在Qt Creator里配置多个Kit，每个Kit对应一个版本。切换项目的时候在“项目”设置里选择对应的Kit就行，不要试图在一个Kit里混用两个版本。

关于编译速度：Qt项目编译慢是出了名的。开启并行编译可以显著提升速度。在Qt Creator的“项目”→“构建步骤”里，把Make或Ninja的参数改成-j8或者-j16，具体数字根据你CPU的核心数来定。我一般设成核心数的1.5倍。

关于调试：Qt Creator集成了GDB调试器，打断点、单步执行、查看变量都很方便。但要注意，Release模式下很多变量会被优化掉，调试的时候用Debug模式。另外，如果你用了CMake的CMAKE_BUILD_TYPE，确保Debug模式下是-g选项。

关于清理构建：有时候改了CMakeLists.txt之后，构建会出错。这时候不要只点“重新构建”，而是先“清理”再“重新构建”，或者直接手动删除构建目录。CMake的缓存有时候会残留旧配置，导致莫名其妙的错误。

关于Qt Creator的插件：Qt Creator支持插件扩展，但不要装太多。我见过有人装了一堆插件，结果IDE启动慢得要命，还经常崩溃。只装你真正需要的，比如Git集成、代码分析工具这些。

关于项目文件管理：Qt Creator会在项目目录下生成一个build-项目名- Kit名-Debug这样的构建目录。这个目录会越来越大，建议定期清理。你可以在“工具”→“选项”→“构建和运行”里，把构建目录设置到一个统一的临时目录下，方便管理。