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.15Qt 6目前主流是6.5、6.6、6.7这几个。对于新手来说我建议直接用Qt 6的较新版本因为Qt 5已经停止公开更新了新项目没必要从老版本开始。但这里有个坑要注意Qt 6对C标准的要求是C17起步如果你的编译器太老编译会直接报错。所以选版本的时候要跟你的编译器匹配。Windows上一般用MinGW或者MSVCLinux上一般用系统自带的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-3GBMinGW编译器约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这样的路径下路径中不要有中文和空格否则后面编译的时候可能出现莫名其妙的错误。接下来是组件选择页面这是最关键的一步。页面左侧是一个树形结构你需要展开各个节点来勾选具体组件。我按重要性给你列一下组件类别具体组件是否必选说明Qt版本Qt 6.x.x必选选最新的稳定版比如6.7编译器MinGW 11.2Windows必选跟Qt版本配套的GCC编译器编译器MSVC 2019/2022可选如果你装了Visual Studio可以选开发工具Qt Creator必选IDE本体默认会勾选开发工具CMake必选构建系统Qt 6默认用CMake开发工具Ninja必选配合CMake使用的构建工具附加库Qt Debug Information Files可选调试用占空间大新手可不选附加库Qt Charts可选画图表用的需要就选附加库Qt Multimedia可选多媒体功能需要就选这里重点说一下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默认用CMakeQt 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”。接下来几步分别是项目名称和路径名称用英文路径不要有中文和空格。比如D:\Projects\HelloQt。构建系统选择CMake。你会看到qmake也在选项里但我们用CMake。类信息基类选QMainWindow类名用默认的MainWindow就行。这里会生成三个文件mainwindow.h、mainwindow.cpp、mainwindow.ui。翻译文件不需要直接下一步。Kit选择勾选你之前配置好的Kit比如“Desktop Qt 6.7.0 MinGW 64-bit”。版本控制选“无”新手用不上。点击“完成”之后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在线安装器卡死是最常见的问题没有之一。我总结了几种情况和对策现象可能原因解决办法安装器打开后白屏无法连接服务器获取组件列表用--mirror参数指定国内镜像下载组件时进度条不动网络不稳定或镜像源失效换一个镜像源重试安装到一半报错退出磁盘空间不足或权限问题检查磁盘空间用管理员权限运行登录界面反复弹出账号验证失败检查网络确认账号密码正确如果在线安装器实在搞不定可以考虑用离线安装包。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的代码编辑器有一些很实用的功能但默认配置可能不太顺手。我分享几个我常用的设置代码对齐快捷键默认是CtrlI但很多人反映不好用。你可以在“工具”→“选项”→“环境”→“键盘”里搜索“AutoIndent”或者“Format”重新绑定一个顺手的快捷键。我一般绑成CtrlShiftI。代码补全Qt Creator的补全默认是CtrlSpace但跟系统输入法切换冲突。可以在键盘设置里改成Alt/。快速切换头文件和源文件快捷键是F4在.h和.cpp之间快速跳转非常方便。查找符号CtrlK可以快速定位到某个函数或类的定义。6.5 关于Qt版本冲突的深入分析前面提到的cannot mix incompatible qt library这个报错值得单独展开讲一下。这个问题的本质是动态链接库的加载顺序问题。你的程序在运行时操作系统会按照一定的顺序查找依赖的DLLWindows或soLinux文件。在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还是LinuxQt的安装路径里绝对不要有中文和空格。我见过有人装在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这样的构建目录。这个目录会越来越大建议定期清理。你可以在“工具”→“选项”→“构建和运行”里把构建目录设置到一个统一的临时目录下方便管理。