很多人第一次接触桌面开发都是从“拖个按钮、点一下弹个窗”开始的。Qt 恰好就是那个能让你在半天之内把想法变成窗口程序的框架。它跨平台、文档全、生态稳无论是做上位机、工控界面、医疗仪器面板还是快速搭一个内部工具Qt 都是绕不开的选择。你搜“Qt 第一个程序”大概率已经装好了 Qt Creator或者正对着安装向导发愁。这篇文章不跟你扯虚的我把自己带新人时反复讲的那套流程完整写下来从选版本、装组件到新建工程、改代码、编译运行再到打包发布和踩坑排查。不管你是刚学 C 的学生还是从嵌入式转过来的工程师只要跟着走一遍就能得到一个真正能跑起来的 Qt 窗口程序并且知道每一步为什么这么做。1. Qt 开发环境搭建与版本选择1.1 选哪个 Qt 版本5.15.2 还是 6.x离线包和在线安装怎么挑打开 Qt 官网你首先会懵5.15.2、6.2、6.5、6.8还有 LTS 和普通版到底下哪个我的建议很直接如果你不是给特定老项目维护代码优先用 Qt 5.15.2 或 Qt 6.5 LTS。为什么不是最新版因为 Qt 6 改了不少底层网上大量教程、第三方库比如 QChart 的某些旧写法、串口模块的示例还是基于 Qt 5 的新手用最新版容易遇到“照着教程敲却编译不过”的尴尬。Qt 5.15.2 是 5 系列的最后一个长期支持版稳定、资料多、兼容性好很多公司内部工具至今还在用。如果你明确要学 QML、Quick 或者需要新版的多媒体模块那就直接上 Qt 6.5别犹豫。离线安装包和在线安装的区别也得说清楚。在线安装器需要登录 Qt 账号而且默认从境外服务器拉数据国内下载速度可能很慢中途断线就得重来。离线包则是一次性下载完整安装文件比如qt-opensource-windows-x86-5.15.2.exe体积大概 2 到 3 GB装的时候不需要联网。我通常推荐新手先用离线包把 5.15.2 装好跑通第一个程序再去折腾在线安装器。另外网上常说的“qt 国内镜像”确实存在比如某些高校镜像站会同步 Qt 的在线安装源但镜像站的状态不稳定不一定有你要的版本。最稳的办法还是找官方离线包或者用别人已经验证过的下载链接。注意不要随便从不知名的小站下载 exe安装包被篡改的风险很高。安装时组件选择是另一个大坑。Windows 下你会看到 MinGW 和 MSVC 两大阵营。MinGW 是 Qt 自带的编译器套件装完就能用不需要额外装 Visual Studio对新手最友好。MSVC 则需要你先装 Visual Studio 并勾选 C 开发负载好处是能调用 Windows 原生 API、调试信息更全、和某些第三方库兼容更好。我建议第一个程序用MinGW省去配置 VS 的麻烦。具体勾选Qt 版本下选MinGW 8.1.0 64-bit或者MinGW 11.2.0取决于 Qt 版本另外把Qt Creator、Qt Debug Information Files也勾上。如果你以后要做串口、图表再补装Qt Serial Port、Qt Charts等模块。注意安装路径不要带中文和空格比如D:\Qt\Qt5.15.2就很好C:\Program Files\Qt在某些情况下会因为权限和空格导致编译失败。装完后在开始菜单找到 Qt Creator 并打开如果能看到欢迎界面环境就算初步就绪。1.2 Windows 下安装 Qt Creator 的详细步骤与验证下载好离线包后双击运行第一步是登录 Qt 账号。如果你没有账号可以点“Skip”跳过离线安装允许跳过登录。接着选择安装目录建议单独建一个Qt文件夹。组件页面会列出很多分类新手只需要关注Qt下面的版本号展开后勾选对应的编译器套件。以 5.15.2 为例勾选MinGW 8.1.0 64-bit下面还有Qt Charts、Qt Quick 3D等可选模块第一个程序暂时不用但Qt Charts以后画曲线会用到硬盘够大就一起勾上。Developer and Designer Tools里默认会勾选 Qt Creator保持默认即可。安装过程大概 10 到 20 分钟取决于硬盘速度。装完后打开 Qt Creator第一件事是验证编译器。点击菜单工具-选项-构建和运行在构建套件(Kit)标签页里应该能看到一个自动检测到的Desktop Qt 5.15.2 MinGW 64-bit套件前面有个绿色对勾或者没有警告图标。如果显示黄色感叹号说明编译器路径没配好可以手动检查编译器标签页里的 C 编译器路径是否指向Qt\Tools\mingw810_64\bin\g.exe。这一步很关键很多“无法构建”的问题都出在 Kit 配置上。接下来做一个命令行验证。打开 Qt 自带的命令行工具在开始菜单里叫Qt 5.15.2 (MinGW 8.1.0 64-bit)或者叫Qt Command Prompt。输入qmake -v如果输出类似QMake version 3.1和Using Qt version 5.15.2说明环境变量和 Qt 版本都正常。再输入g --version能看到 MinGW 的版本信息就说明编译器也通了。这两条命令能跑通后面创建项目基本不会因为环境问题卡住。如果你用 MSVC则应该在“x64 Native Tools Command Prompt for VS”里运行qmake -v并且 Kit 要选 MSVC 套件。实操心得安装时如果网络中断导致组件缺失可以重新运行安装包选择“添加或移除组件”它会自动检测已安装的部分不用全部重来。另外Qt Creator 的默认编码是 UTF-8但 Windows 控制台默认是 GBK后面写中文输出时可能会乱码这个我们放到常见问题里讲。2. 创建第一个 Qt 程序从 Hello World 到窗口2.1 新建项目时三种模板怎么选Widgets、Console、Quick打开 Qt Creator点击文件-新建文件或项目。你会看到几个分类Application (Qt)、Library、其他项目。在Application (Qt)下面常用的有三个模板Qt Widgets Application、Qt Console Application、Qt Quick Application。第一个程序选哪个我的答案是Qt Widgets Application。原因很简单Widgets 是基于 C 的传统桌面控件你能直观地看到窗口、按钮、文本框代码结构清晰适合理解 Qt 的对象模型和信号槽。Console Application 是纯控制台程序没有界面适合测试算法或学习基础类但对“第一个 Qt 程序”来说少了点成就感。Quick Application 是基于 QML 的声明式 UI更适合做触屏、动画、移动端风格界面但需要理解 QML 语法新手容易迷失。选Qt Widgets Application后项目名称填HelloQt路径选一个纯英文、无空格的目录比如D:\QtProjects\HelloQt。构建系统会问你用qmake还是CMake。Qt 5 时代默认 qmakeQt 6 开始推荐 CMake。如果你用的是 5.15.2直接选 qmake因为资料最多、.pro文件简单直观。选 CMake 也不是不行但新手容易被CMakeLists.txt里的各种命令绕晕。基类选择默认的QMainWindow即可它自带菜单栏、工具栏、状态栏以后扩展方便。如果你只想做个简单对话框可以选QDialog但第一个程序用QMainWindow更通用。生成项目后Qt Creator 会自动打开项目视图左侧是项目文件树。你会看到HelloQt.pro、main.cpp、mainwindow.h、mainwindow.cpp、mainwindow.ui这几个文件。别急着改代码先点左下角的绿色三角形“运行”按钮。如果一切正常会弹出一个空白窗口标题是HelloQt。恭喜你的第一个 Qt 程序已经跑起来了。但如果报错比如“找不到 Kit”或“unknown module”先别慌后面第 4 章会专门排查。2.2 项目目录结构详解.pro、main.cpp、mainwindow 三件套先看.pro文件它是 qmake 的工程描述文件相当于告诉 Qt 要编译哪些源文件、链接哪些库、用 C 哪个标准。一个典型的HelloQt.pro内容如下QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET HelloQt TEMPLATE app DEFINES QT_DEPRECATED_WARNINGS SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h FORMS \ mainwindow.ui逐行解释QT core gui表示引入 QtCore 和 QtGui 模块greaterThan(QT_MAJOR_VERSION, 4): QT widgets是说如果 Qt 主版本大于 4就加上 widgets 模块因为 Qt 5 把控件独立成了 QtWidgets。TARGET是生成的可执行文件名TEMPLATE app表示这是一个应用程序。SOURCES、HEADERS、FORMS分别列出源文件、头文件和 UI 文件。以后你要加串口功能就得在这里加QT serialport否则编译时会报unknown module(s) in qt: serialport。再看main.cpp它是程序入口#include mainwindow.h #include QApplication int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; w.show(); return a.exec(); }QApplication管理整个应用程序的生命周期、事件循环和全局资源。每个 Qt Widgets 程序有且只有一个QApplication对象。MainWindow是我们自己的窗口类继承自QMainWindow。w.show()让窗口显示出来a.exec()进入事件循环程序会一直等待用户操作直到窗口关闭。这段代码虽然短但包含了 Qt 程序最核心的骨架应用对象、窗口对象、事件循环。mainwindow.h和mainwindow.cpp是窗口类的声明和实现。默认生成的MainWindow类里只有一个Ui::MainWindow *ui指针它指向通过.ui文件生成的界面对象。.ui文件是 XML 格式的界面描述Qt Designer 可以可视化编辑qmake 会调用uic工具把它转换成 C 代码。你可以双击mainwindow.ui打开设计器拖一个Label到窗口上写上“Hello Qt”然后运行就能看到文字显示在窗口里。这就是 Qt 的分离式设计界面和逻辑可以分开也可以手写代码完全不用.ui。2.3 手写代码 vs 使用 UI 设计器两种方式对比很多新手纠结到底该用 Qt Designer 拖控件还是纯代码创建界面我的经验是第一个程序用 Designer 找感觉第二个程序开始尝试手写布局。Designer 的好处是直观拖拽就能看到效果适合快速原型和简单界面。但它的局限也很明显复杂动态界面、自定义控件、需要根据数据生成大量重复控件时手写代码更灵活。而且面试或实际工作中经常需要你直接看代码就能理解界面结构纯 Designer 生成的代码反而不好维护。拿“点击按钮改变标签文字”这个功能举例。用 Designer 的做法拖一个Push Button和一个Label右键按钮选“转到槽”选择clicked()信号Qt Creator 会自动生成槽函数on_pushButton_clicked()你在里面写ui-label-setText(你好Qt);即可。纯代码的做法在MainWindow构造函数里创建QPushButton和QLabel用connect连接按钮的clicked信号到自定义槽函数再设置布局。两种方式最终效果一样但纯代码让你更清楚对象树、父子关系和信号槽的连接过程。提示如果你用 Designerui-setupUi(this)这行代码必须在构造函数里最先调用它会根据.ui文件创建所有控件并设置好布局。如果你在手写代码里又重复创建了同名控件可能会导致界面错乱。另外ui指针指向的控件对象归MainWindow管理不需要手动 deleteQt 的父子对象机制会自动释放。我建议第一个程序这样练先用 Designer 做一个带按钮和标签的窗口实现点击改变文字然后新建一个纯代码项目不用.ui文件手动写出同样的界面。两次下来你对 Qt 的控件创建、布局管理和信号槽会有完全不同的理解。别怕麻烦这一步省了后面做复杂界面时还是要补课。2.4 代码逐行解析与信号槽初体验信号槽是 Qt 最核心的机制没有之一。简单说信号signal是对象发出的通知槽slot是接收通知的函数。比如按钮被点击时会发出clicked()信号你可以把它连接到一个槽函数槽函数就会自动执行。连接方式有两种旧版宏SIGNAL和SLOT新版函数指针语法。Qt 5 之后推荐用函数指针因为编译期就能检查参数类型出错更容易发现。看一个完整的纯代码示例。假设我们不用.ui在mainwindow.cpp里这样写#include mainwindow.h #include QPushButton #include QLabel #include QVBoxLayout #include QWidget MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { QWidget *central new QWidget(this); setCentralWidget(central); QLabel *label new QLabel(原始文字, central); QPushButton *button new QPushButton(点我, central); QVBoxLayout *layout new QVBoxLayout(central); layout-addWidget(label); layout-addWidget(button); connect(button, QPushButton::clicked, this, []() { label-setText(你点击了按钮); }); }这段代码做了什么首先创建一个QWidget作为中央窗口部件setCentralWidget把它设为QMainWindow的中心区域。然后创建标签和按钮父对象都设为central这样它们会显示在central上。QVBoxLayout是垂直布局管理器把标签和按钮从上到下排列。最后用connect把按钮的clicked信号连接到一个 lambda 表达式lambda 里修改标签文字。[]表示按值捕获外部变量这里捕获了label指针。点击按钮时Qt 的事件循环检测到鼠标点击按钮发出信号信号触发槽函数标签文字就变了。这里有个关键点信号和槽的参数必须匹配或者槽的参数可以比信号少。clicked()信号没有参数所以槽函数也不能有参数。如果你连接的是textChanged(const QString)信号槽函数就可以接收一个QString参数。另外connect的第四个参数是连接类型默认是AutoConnection在同一个线程里就是直连跨线程会自动变成队列连接。跨线程更新 UI 是 Qt 新手常犯的错误后面第 4 章会讲。实操心得用 lambda 写槽函数很方便但要注意捕获方式。如果捕获了this而对象在信号发出前被销毁就会崩溃。稳妥的做法是使用QPointer或者确保对象的生命周期覆盖连接。对于第一个程序直接用this作为接收者Qt 会在this销毁时自动断开连接所以connect(button, QPushButton::clicked, this, [](){...})是安全的。3. 编译、运行与调试的完整流程3.1 构建套件 Kit 的配置与常见错误Qt Creator 的构建套件Kit是编译、运行、调试三者的组合。一个 Kit 包含编译器、调试器、Qt 版本和构建工具。你装好 Qt 后Qt Creator 通常会自动检测到可用的 Kit。打开工具-选项-构建和运行-构建套件(Kit)你会看到列表。每个 Kit 前面有图标绿色对勾表示完全可用黄色感叹号表示缺少某些组件。如果你看到Desktop Qt 5.15.2 MinGW 64-bit显示黄色点开它检查Qt version是否指向D:\Qt\5.15.2\mingw81_64\bin\qmake.exeC compiler是否指向D:\Qt\Tools\mingw810_64\bin\g.exeDebugger是否指向gdb.exe。如果某个路径为空手动浏览选择即可。常见错误一“未找到 Kit”。这通常是因为 Qt 版本没有正确注册。在Qt Versions标签页点击“添加”选择qmake.exe路径然后回到 Kit 页面重新选择。常见错误二“无法启动进程找不到 mingw32-make”。检查构建和运行-构建套件里的CMake Tool或Make Tool是否配置了mingw32-make.exe。常见错误三编译时报“unknown module(s) in qt: serialport”。这说明你在.pro里加了QT serialport但安装 Qt 时没有勾选Qt Serial Port模块。解决办法是重新运行 Qt 安装包在组件里找到对应版本的Qt Serial Port并安装。如果不想重装也可以单独下载模块源码编译但对新手不推荐。还有一个很隐蔽的问题Kit 选错了。比如你装了 MinGW 和 MSVC 两个套件项目默认选了 MSVC但你的代码里用了 MinGW 专有的头文件或者环境变量没配好就会报奇怪的错误。点左下角的构建套件选择器明确选Desktop Qt 5.15.2 MinGW 64-bit。如果项目是从别人那里拷来的.pro.user文件里可能记录了旧的 Kit 路径删掉.pro.user文件重新打开项目让 Qt Creator 重新生成配置往往能解决“明明装了却用不了”的问题。3.2 qmake 与 CMake 构建系统选择Qt 5 默认用 qmakeQt 6 主推 CMake。两者有什么区别qmake 是 Qt 自家的构建工具语法简单.pro文件几行就能描述项目。CMake 是跨平台构建系统功能更强大生态更广但配置文件CMakeLists.txt写起来更啰嗦。对于第一个程序用 qmake 足够了。如果你用的是 Qt 6 并且选了 CMake生成的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)AUTOUIC、AUTOMOC、AUTORCC分别自动处理.ui文件、包含Q_OBJECT宏的头文件和资源文件。find_package找到 Qt6 的 Widgets 模块target_link_libraries把它链接到可执行文件。如果你用 qmake这些工作由 qmake 自动完成不需要手动写。所以新手第一个项目强烈建议 qmake。等你需要集成第三方 CMake 库或者做跨平台大型项目时再切 CMake 也不迟。编译时Qt Creator 默认使用影子构建Shadow build也就是把编译生成的中间文件和可执行文件放在项目目录之外的构建目录里比如build-HelloQt-Desktop_Qt_5_15_2_MinGW_64_bit-Debug。这样做的好处是源码目录保持干净切换 Debug 和 Release 不会互相干扰。你可以在项目-构建设置里看到构建目录。如果编译失败先看“编译输出”窗口的红色错误信息从第一条错误开始改因为后面的错误往往是第一条引起的连锁反应。3.3 运行第一个程序窗口显示与调试输出点击左下角的绿色三角形或者按CtrlRQt Creator 会先编译再运行。如果编译成功会弹出你的窗口。如果窗口一闪而过说明程序在main函数里提前退出了检查w.show()和a.exec()是否都写了。如果窗口显示但标题不对检查setWindowTitle或者.pro里的TARGET。运行后你可以在应用程序输出窗口看到qDebug()打印的信息。比如在main.cpp里加一句qDebug() 程序启动;运行后就能在输出窗口看到。qDebug()是 Qt 的调试输出宏比std::cout更方便支持 Qt 类型而且在 Release 模式下可以通过QT_NO_DEBUG_OUTPUT禁用。调试方面Qt Creator 集成了 GDBMinGW或 CDBMSVC。在代码行号旁边点击可以设置断点然后按F5进入调试模式。程序会在断点处暂停你可以查看变量值、调用栈、内存。对于第一个程序你可以试试在按钮的槽函数里设断点点击按钮后观察程序是否停在断点处label的文本是什么。调试是排查问题的利器但新手往往只用qDebug()。两者结合最好简单流程用qDebug()打日志复杂逻辑用断点单步跟踪。注意在 Windows 上如果程序运行后没有窗口但任务管理器里有进程可能是窗口被创建在了屏幕外或者被其他窗口遮挡。检查是否在构造函数里移动了窗口位置。另一个常见问题是中文乱码如果你用qDebug()输出中文控制台可能显示乱码这是因为 Qt Creator 的应用程序输出窗口默认用 UTF-8而 Windows 控制台用 GBK。解决办法是在main.cpp里设置编码或者直接用QString::fromLocal8Bit转换。不过对于界面上的中文只要源文件保存为 UTF-8一般不会乱码。3.4 程序打包发布windeployqt 的使用程序编译好了你想发给别人用直接拷 exe 过去对方双击很可能报错“缺少 Qt5Core.dll”。因为 Qt 程序依赖很多动态库必须把它们一起打包。Qt 提供了一个工具windeployqt专门用来复制依赖库。用法很简单先编译 Release 版本找到生成的HelloQt.exe把它单独复制到一个空文件夹比如D:\Release\HelloQt。然后打开 Qt 命令行工具切换到该目录执行windeployqt HelloQt.exe它会自动扫描 exe 的依赖把需要的 DLL、插件、翻译文件复制到当前目录。完成后整个文件夹就可以打包发给别人了。注意windeployqt需要和编译时使用的 Qt 版本一致比如你用 MinGW 5.15.2 编译的就要用对应命令行里的windeployqt。如果你用 MSVC则在 VS 命令行里运行。打包后可以先在本机测试把文件夹移到另一个没有 Qt 环境的路径双击运行看是否正常。如果程序还依赖第三方库比如 FFmpeg、Halconwindeployqt不会自动复制它们需要手动把对应的 DLL 放到 exe 旁边。另外Release 版本通常比 Debug 版本小很多发布时一定要用 Release。你可以在 Qt Creator 左下角切换构建配置为Release然后重新构建。打包后的文件夹里会有一个platforms子文件夹里面是qwindows.dll这个不能删否则程序无法启动。如果目标电脑是 32 位系统而你编译的是 64 位程序也无法运行需要对应位数编译。4. 常见问题排查与避坑经验4.1 编译报错unknown module(s) in qt: serialport 等模块缺失这是 Qt 新手最常见的一类错误。你在.pro里写了QT serialport或者代码里#include QSerialPort编译时却提示unknown module(s) in qt: serialport。原因很简单安装 Qt 时没有勾选Qt Serial Port模块。Qt 的模块是可选安装的默认只装核心模块。解决办法找到 Qt 安装目录下的MaintenanceTool.exe运行它登录后选择“添加或移除组件”展开对应 Qt 版本勾选Qt Serial Port然后点击更新。安装完成后重新打开 Qt Creator重新构建项目通常就能通过。如果是QT charts报错同理需要安装Qt Charts。有些模块在 Qt 5 和 Qt 6 里名字不同比如QtCharts在 Qt 6 里可能需要用find_package(Qt6 COMPONENTS Charts)。另外如果你用 CMake需要把find_package和target_link_libraries都写对只加QT 是 qmake 的语法CMake 里无效。排查时先确认三件事模块是否安装、.pro或CMakeLists.txt是否声明、Kit 是否匹配。如果还不行在 Qt Creator 的项目-构建设置里点“执行 qmake”或“重新构建”强制刷新配置。避坑技巧不要手动去改 Qt 安装目录里的文件也不要从网上下载单独的 DLL 往编译器目录里塞。模块缺失就用 MaintenanceTool 补装这是最干净的方式。另外如果你在 Linux 下比如 Ubuntu 20.04安装 Qt 交叉编译环境时串口模块可能叫libqt5serialport5-dev需要用包管理器安装而不是 Qt 安装器。4.2 版本冲突cannot mix incompatible Qt library 的解法这个错误信息非常典型cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)。意思是程序在运行时加载了两个不同小版本的 Qt 库。常见原因是你的系统 PATH 环境变量里有另一个 Qt 版本的 bin 目录或者你拷贝了别人的 DLL 混用。Qt 对版本非常敏感5.15.2 和 5.15.3 虽然只差一个小版本但二进制不兼容。解决办法检查系统环境变量把不需要的 Qt 路径删掉如果程序依赖某个第三方库而那个库链接了另一个 Qt 版本唯一的办法是统一版本重新编译第三方库或者换用同版本的预编译包。在 Qt Creator 里这种情况通常不会出现因为 Kit 会隔离环境。但当你手动运行 exe或者用windeployqt打包时如果 PATH 里存在其他 Qt可能会优先加载错。打包时windeployqt会复制正确的 DLL 到 exe 旁边Windows 加载 DLL 的顺序是exe 所在目录优先于 PATH所以打包后的程序通常没问题。但如果你在开发机上直接运行 Debug 版 exe而 PATH 里有其他 Qt就可能冲突。最简单的排查方法用Process Explorer或Dependency Walker查看程序实际加载的 Qt5Core.dll 路径确认版本。另一个相关问题是Qt 5.15.3和Qt 5.15.2的插件不兼容。比如你用了 5.15.2 的qwindows.dll却加载了 5.15.3 的Qt5Core.dll程序启动时会直接崩溃没有太多提示。所以永远保持 Qt 版本、编译器、插件三者一致。如果你从别人那里拿到一个项目先问清楚他用的 Qt 版本和编译器然后在本机装一模一样的 Kit不要试图用新版本直接打开旧项目除非你准备好处理兼容性问题。4.3 中文乱码、图标不显示、DLL 缺失的快速排查表下面这张表是我自己排错时总结的覆盖了第一个 Qt 程序最容易遇到的几个问题现象可能原因排查方法解决方式界面中文显示为乱码源文件编码不是 UTF-8用记事本另存为查看编码在 Qt Creator 里设置默认编码为 UTF-8文件开头加#pragma execution_character_set(utf-8)MSVC控制台 qDebug 中文乱码控制台编码与 Qt 输出编码不一致看输出窗口是否正常控制台是否乱码在main里用QTextCodec::setCodecForLocale(QTextCodec::codecForName(GBK))程序图标不显示没有设置.rc文件或资源未编译检查.pro里是否有RC_FILE创建.rc文件写入IDI_ICON1 ICON app.ico在.pro里加RC_FILE app.rc双击 exe 提示缺少 Qt5Core.dll没有打包依赖库用 Dependency Walker 查看缺失 DLL用windeployqt复制依赖或把 Qt bin 目录加入 PATH窗口不显示或一闪而过没有调用show()或exec()检查main.cpp确保w.show()和return a.exec();都存在按钮点击无反应信号槽未连接或连接失败在connect后加qDebug()检查返回值确认信号和槽参数匹配检查connect的返回值是否为 true中文乱码问题特别值得展开。Qt 5 默认使用 UTF-8 编码源文件但 Windows 的 MSVC 编译器可能把源文件当成 GBK导致中文字符串字面量出错。最稳的做法是在.pro里加QMAKE_CXXFLAGS /utf-8MSVC或者确保文件保存为带 BOM 的 UTF-8。MinGW 通常没这个问题但如果你在代码里用std::cout输出中文控制台还是可能乱码这时用qDebug()更省心。图标问题则要求你准备一个.ico文件然后用 RC 文件嵌入不要直接把 png 改成 ico格式不对会导致编译失败。4.4 快捷键与效率技巧开发时少点鼠标Qt Creator 有很多快捷键熟练之后能省大量时间。最常用的几个CtrlR编译并运行CtrlB只编译F5开始调试F9设置或取消断点F10单步跳过F11单步进入ShiftF11单步跳出。CtrlK打开定位器可以快速搜索文件、类、函数输入:加行号还能跳转到指定行。CtrlShiftR是全局重命名改类名或变量名时非常方便。Alt0切换侧边栏Alt1打开项目视图Alt4打开构建输出。代码编辑方面Ctrl/注释或取消注释当前行CtrlShiftEnter在上方插入空行CtrlEnter在下方插入空行。CtrlD删除当前行CtrlShiftV从历史剪贴板粘贴。如果你用 Designer 拖界面CtrlShiftF可以格式化代码CtrlShiftS保存所有文件。还有一个隐藏技巧在.pro文件里右键选择“执行 qmake”可以在不重新构建整个项目的情况下刷新工程文件添加新文件或修改模块后很有用。实操心得我习惯把CtrlR改成F5之外的按键不用改默认就好。但有一个设置建议打开工具-选项-环境-键盘搜索“运行”看看当前绑定。另外Qt Creator 的“伪造历史”功能F2 跳转到符号定义在阅读大型项目时非常有用。如果你从 Visual Studio 转过来可能会觉得 Qt Creator 的调试器界面简陋但它的表达式求值和内存查看其实够用而且启动速度比 VS 快很多。5. 从第一个程序延伸下一步该学什么5.1 信号槽深入与自定义信号第一个程序里你用的是按钮自带的clicked()信号连到 lambda 或普通函数。实际项目中你经常需要自定义信号比如一个数据接收类收到完整数据后发出dataReady(QByteArray)信号让界面更新。自定义信号写在类声明里用signals:关键字标记不需要实现。槽函数用public slots:或private slots:声明需要实现。连接时发送者对象发出信号接收者对象的槽被调用。信号可以带参数参数类型需要注册到 Qt 元对象系统基本类型和 Qt 类型都支持。一个典型的自定义信号示例class Worker : public QObject { Q_OBJECT public: explicit Worker(QObject *parent nullptr) : QObject(parent) {} signals: void progressChanged(int percent); public slots: void doWork() { for (int i 0; i 100; i 10) { emit progressChanged(i); QThread::msleep(100); } } };注意Q_OBJECT宏必须写在类声明开头否则信号槽和元对象功能都不生效。emit是 Qt 的关键字用来发出信号其实它只是个宏不写也能编译但建议保留以增强可读性。如果要在不同线程间传递信号参数类型需要是可拷贝的并且连接方式要选Qt::QueuedConnection或使用默认的AutoConnection。跨线程更新 UI 时绝对不能直接在子线程里调用ui-label-setText()必须通过信号槽让主线程来更新。这是 Qt 线程安全的基本规则违反会导致程序随机崩溃。5.2 界面布局与绘图从静态窗口到动态图表掌握了基本控件后下一步是学习布局管理器。Qt 提供了QHBoxLayout、QVBoxLayout、QGridLayout、QFormLayout等。布局管理器让控件随窗口大小自动调整比手动设置坐标强大得多。你可以用 Designer 拖布局也可以纯代码嵌套布局。一个经验不要给控件设置固定的setGeometry除非你明确知道窗口不会缩放。用布局管理器配合setStretch和setSizePolicy可以做出自适应的界面。如果你要做数据监控或曲线显示Qt Charts模块是首选。它提供了QChartView、QLineSeries、QValueAxis等类可以画折线图、柱状图、饼图。使用前需要在.pro里加QT charts并在代码里#include QtCharts。对于大量数据点的实时刷新直接把所有点都加到QLineSeries里会导致界面卡顿。优化方法使用QChart::setAnimationOptions(QChart::NoAnimation)关闭动画只保留最近 N 个点或者用QVectorQPointF批量替换。如果曲线刷新频率很高可以考虑把数据采集放在子线程通过信号把数据块发给主线程更新图表这样界面不会卡死。另一个常用的是QCustomPlot这是一个第三方绘图库只有一个头文件和源文件集成简单性能也不错。很多人从 Qt Charts 转到 QCustomPlot就是因为它在大量数据刷新时更流畅。选择哪个取决于你的需求Qt Charts 官方维护、风格统一、和 Qt 集成好QCustomPlot 轻量、灵活、社区示例多。如果你只是画几条曲线Qt Charts 足够如果要画几十万点的实时波形QCustomPlot 或 OpenGL 绘图更合适。5.3 文件操作与 JSON 读写让程序能存配置实际程序很少是孤立的总需要读写文件。Qt 的QFile、QTextStream、QDataStream提供了跨平台的文件操作。读文本文件QFile file(config.txt); if (file.open(QIODevice::ReadOnly | QIODevice::Text)) { QTextStream in(file); while (!in.atEnd()) { QString line in.readLine(); // 处理每一行 } file.close(); }写文件类似用QIODevice::WriteOnly或Append。注意QTextStream默认编码在 Qt 5 是本地编码Qt 6 是 UTF-8处理中文时最好显式设置编码。对于配置文件JSON 是现在最常用的格式。Qt 提供了QJsonDocument、QJsonObject、QJsonArray来解析和生成 JSON。例如QJsonObject obj; obj[name] HelloQt; obj[version] 1.0; QJsonArray arr {1, 2, 3}; obj[values] arr; QJsonDocument doc(obj); QFile file(config.json); file.open(QIODevice::WriteOnly); file.write(doc.toJson()); file.close();读取时用QJsonDocument::fromJson解析然后通过object()和array()获取数据。JSON 读写非常直观适合保存程序设置、用户数据、网络接口返回结果。如果你需要更复杂的配置可以考虑QSettings它能自动把配置存到注册表Windows或 plistmacOS或 ini 文件Linux跨平台且无需手动解析。不过QSettings不适合存大量结构化数据JSON 更灵活。5.4 项目实战建议从小工具开始别一上来就做 IDE学完第一个程序很多人热血沸腾想做个“全能工具箱”或者“仿 QQ 界面”。我的建议是先做 3 到 5 个微型项目每个只解决一个小问题比如一个带按钮的计时器点击开始后标签每秒更新练习QTimer和信号槽。一个简单的文本编辑器能打开、保存、另存为练习QFileDialog和文件读写。一个串口调试助手能扫描串口、发送和接收数据练习QSerialPort和线程。一个图片查看器能打开文件夹、上一张下一张练习QDir、QPixmap和布局。一个 JSON 格式化工具粘贴 JSON 后高亮显示练习QPlainTextEdit和语法高亮。每个项目控制在 300 行代码以内做完后写一篇简短的笔记记录遇到的坑和解决办法。这样积累下来你对 Qt 的常用模块、事件循环、对象树、内存管理会有肌肉记忆。之后再去做复杂项目比如上位机、数据采集系统就不会因为基础不牢而卡住。另外多读 Qt 自带的示例代码在 Qt Creator 的欢迎界面点击“示例”里面有大量可运行的项目从calculator到chart都有这是最好的学习资料。最后再分享一个小技巧遇到不懂的类把光标放在类名上按F1Qt Creator 会打开帮助文档里面不仅有 API 说明还有示例代码。Qt 的帮助文档是离线的非常完整养成查文档的习惯比到处搜博客更靠谱。另外Qt 的源码也是开源的如果你想知道某个函数内部怎么实现的按住Ctrl点击函数名就能跳转到源码这对深入理解 Qt 非常有帮助。我个人在带新人的时候最看重的不是他写了多少行代码而是他有没有把第一个程序真正跑通、打包、发给别人运行。这个过程会逼着你解决环境配置、依赖库、版本冲突、编码等一系列问题这些才是实际开发中真正花时间的地方。第一个 Qt 程序只是一个起点后面还有信号槽的线程安全、模型视图架构、QML 与 C 交互、跨平台部署等一大堆内容等着你。别急一个一个来每解决一个问题你对 Qt 的理解就深一层。 Qt第一个程序完整指南：从环境搭建到打包发布
很多人第一次接触桌面开发都是从“拖个按钮、点一下弹个窗”开始的。Qt 恰好就是那个能让你在半天之内把想法变成窗口程序的框架。它跨平台、文档全、生态稳无论是做上位机、工控界面、医疗仪器面板还是快速搭一个内部工具Qt 都是绕不开的选择。你搜“Qt 第一个程序”大概率已经装好了 Qt Creator或者正对着安装向导发愁。这篇文章不跟你扯虚的我把自己带新人时反复讲的那套流程完整写下来从选版本、装组件到新建工程、改代码、编译运行再到打包发布和踩坑排查。不管你是刚学 C 的学生还是从嵌入式转过来的工程师只要跟着走一遍就能得到一个真正能跑起来的 Qt 窗口程序并且知道每一步为什么这么做。1. Qt 开发环境搭建与版本选择1.1 选哪个 Qt 版本5.15.2 还是 6.x离线包和在线安装怎么挑打开 Qt 官网你首先会懵5.15.2、6.2、6.5、6.8还有 LTS 和普通版到底下哪个我的建议很直接如果你不是给特定老项目维护代码优先用 Qt 5.15.2 或 Qt 6.5 LTS。为什么不是最新版因为 Qt 6 改了不少底层网上大量教程、第三方库比如 QChart 的某些旧写法、串口模块的示例还是基于 Qt 5 的新手用最新版容易遇到“照着教程敲却编译不过”的尴尬。Qt 5.15.2 是 5 系列的最后一个长期支持版稳定、资料多、兼容性好很多公司内部工具至今还在用。如果你明确要学 QML、Quick 或者需要新版的多媒体模块那就直接上 Qt 6.5别犹豫。离线安装包和在线安装的区别也得说清楚。在线安装器需要登录 Qt 账号而且默认从境外服务器拉数据国内下载速度可能很慢中途断线就得重来。离线包则是一次性下载完整安装文件比如qt-opensource-windows-x86-5.15.2.exe体积大概 2 到 3 GB装的时候不需要联网。我通常推荐新手先用离线包把 5.15.2 装好跑通第一个程序再去折腾在线安装器。另外网上常说的“qt 国内镜像”确实存在比如某些高校镜像站会同步 Qt 的在线安装源但镜像站的状态不稳定不一定有你要的版本。最稳的办法还是找官方离线包或者用别人已经验证过的下载链接。注意不要随便从不知名的小站下载 exe安装包被篡改的风险很高。安装时组件选择是另一个大坑。Windows 下你会看到 MinGW 和 MSVC 两大阵营。MinGW 是 Qt 自带的编译器套件装完就能用不需要额外装 Visual Studio对新手最友好。MSVC 则需要你先装 Visual Studio 并勾选 C 开发负载好处是能调用 Windows 原生 API、调试信息更全、和某些第三方库兼容更好。我建议第一个程序用MinGW省去配置 VS 的麻烦。具体勾选Qt 版本下选MinGW 8.1.0 64-bit或者MinGW 11.2.0取决于 Qt 版本另外把Qt Creator、Qt Debug Information Files也勾上。如果你以后要做串口、图表再补装Qt Serial Port、Qt Charts等模块。注意安装路径不要带中文和空格比如D:\Qt\Qt5.15.2就很好C:\Program Files\Qt在某些情况下会因为权限和空格导致编译失败。装完后在开始菜单找到 Qt Creator 并打开如果能看到欢迎界面环境就算初步就绪。1.2 Windows 下安装 Qt Creator 的详细步骤与验证下载好离线包后双击运行第一步是登录 Qt 账号。如果你没有账号可以点“Skip”跳过离线安装允许跳过登录。接着选择安装目录建议单独建一个Qt文件夹。组件页面会列出很多分类新手只需要关注Qt下面的版本号展开后勾选对应的编译器套件。以 5.15.2 为例勾选MinGW 8.1.0 64-bit下面还有Qt Charts、Qt Quick 3D等可选模块第一个程序暂时不用但Qt Charts以后画曲线会用到硬盘够大就一起勾上。Developer and Designer Tools里默认会勾选 Qt Creator保持默认即可。安装过程大概 10 到 20 分钟取决于硬盘速度。装完后打开 Qt Creator第一件事是验证编译器。点击菜单工具-选项-构建和运行在构建套件(Kit)标签页里应该能看到一个自动检测到的Desktop Qt 5.15.2 MinGW 64-bit套件前面有个绿色对勾或者没有警告图标。如果显示黄色感叹号说明编译器路径没配好可以手动检查编译器标签页里的 C 编译器路径是否指向Qt\Tools\mingw810_64\bin\g.exe。这一步很关键很多“无法构建”的问题都出在 Kit 配置上。接下来做一个命令行验证。打开 Qt 自带的命令行工具在开始菜单里叫Qt 5.15.2 (MinGW 8.1.0 64-bit)或者叫Qt Command Prompt。输入qmake -v如果输出类似QMake version 3.1和Using Qt version 5.15.2说明环境变量和 Qt 版本都正常。再输入g --version能看到 MinGW 的版本信息就说明编译器也通了。这两条命令能跑通后面创建项目基本不会因为环境问题卡住。如果你用 MSVC则应该在“x64 Native Tools Command Prompt for VS”里运行qmake -v并且 Kit 要选 MSVC 套件。实操心得安装时如果网络中断导致组件缺失可以重新运行安装包选择“添加或移除组件”它会自动检测已安装的部分不用全部重来。另外Qt Creator 的默认编码是 UTF-8但 Windows 控制台默认是 GBK后面写中文输出时可能会乱码这个我们放到常见问题里讲。2. 创建第一个 Qt 程序从 Hello World 到窗口2.1 新建项目时三种模板怎么选Widgets、Console、Quick打开 Qt Creator点击文件-新建文件或项目。你会看到几个分类Application (Qt)、Library、其他项目。在Application (Qt)下面常用的有三个模板Qt Widgets Application、Qt Console Application、Qt Quick Application。第一个程序选哪个我的答案是Qt Widgets Application。原因很简单Widgets 是基于 C 的传统桌面控件你能直观地看到窗口、按钮、文本框代码结构清晰适合理解 Qt 的对象模型和信号槽。Console Application 是纯控制台程序没有界面适合测试算法或学习基础类但对“第一个 Qt 程序”来说少了点成就感。Quick Application 是基于 QML 的声明式 UI更适合做触屏、动画、移动端风格界面但需要理解 QML 语法新手容易迷失。选Qt Widgets Application后项目名称填HelloQt路径选一个纯英文、无空格的目录比如D:\QtProjects\HelloQt。构建系统会问你用qmake还是CMake。Qt 5 时代默认 qmakeQt 6 开始推荐 CMake。如果你用的是 5.15.2直接选 qmake因为资料最多、.pro文件简单直观。选 CMake 也不是不行但新手容易被CMakeLists.txt里的各种命令绕晕。基类选择默认的QMainWindow即可它自带菜单栏、工具栏、状态栏以后扩展方便。如果你只想做个简单对话框可以选QDialog但第一个程序用QMainWindow更通用。生成项目后Qt Creator 会自动打开项目视图左侧是项目文件树。你会看到HelloQt.pro、main.cpp、mainwindow.h、mainwindow.cpp、mainwindow.ui这几个文件。别急着改代码先点左下角的绿色三角形“运行”按钮。如果一切正常会弹出一个空白窗口标题是HelloQt。恭喜你的第一个 Qt 程序已经跑起来了。但如果报错比如“找不到 Kit”或“unknown module”先别慌后面第 4 章会专门排查。2.2 项目目录结构详解.pro、main.cpp、mainwindow 三件套先看.pro文件它是 qmake 的工程描述文件相当于告诉 Qt 要编译哪些源文件、链接哪些库、用 C 哪个标准。一个典型的HelloQt.pro内容如下QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET HelloQt TEMPLATE app DEFINES QT_DEPRECATED_WARNINGS SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h FORMS \ mainwindow.ui逐行解释QT core gui表示引入 QtCore 和 QtGui 模块greaterThan(QT_MAJOR_VERSION, 4): QT widgets是说如果 Qt 主版本大于 4就加上 widgets 模块因为 Qt 5 把控件独立成了 QtWidgets。TARGET是生成的可执行文件名TEMPLATE app表示这是一个应用程序。SOURCES、HEADERS、FORMS分别列出源文件、头文件和 UI 文件。以后你要加串口功能就得在这里加QT serialport否则编译时会报unknown module(s) in qt: serialport。再看main.cpp它是程序入口#include mainwindow.h #include QApplication int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; w.show(); return a.exec(); }QApplication管理整个应用程序的生命周期、事件循环和全局资源。每个 Qt Widgets 程序有且只有一个QApplication对象。MainWindow是我们自己的窗口类继承自QMainWindow。w.show()让窗口显示出来a.exec()进入事件循环程序会一直等待用户操作直到窗口关闭。这段代码虽然短但包含了 Qt 程序最核心的骨架应用对象、窗口对象、事件循环。mainwindow.h和mainwindow.cpp是窗口类的声明和实现。默认生成的MainWindow类里只有一个Ui::MainWindow *ui指针它指向通过.ui文件生成的界面对象。.ui文件是 XML 格式的界面描述Qt Designer 可以可视化编辑qmake 会调用uic工具把它转换成 C 代码。你可以双击mainwindow.ui打开设计器拖一个Label到窗口上写上“Hello Qt”然后运行就能看到文字显示在窗口里。这就是 Qt 的分离式设计界面和逻辑可以分开也可以手写代码完全不用.ui。2.3 手写代码 vs 使用 UI 设计器两种方式对比很多新手纠结到底该用 Qt Designer 拖控件还是纯代码创建界面我的经验是第一个程序用 Designer 找感觉第二个程序开始尝试手写布局。Designer 的好处是直观拖拽就能看到效果适合快速原型和简单界面。但它的局限也很明显复杂动态界面、自定义控件、需要根据数据生成大量重复控件时手写代码更灵活。而且面试或实际工作中经常需要你直接看代码就能理解界面结构纯 Designer 生成的代码反而不好维护。拿“点击按钮改变标签文字”这个功能举例。用 Designer 的做法拖一个Push Button和一个Label右键按钮选“转到槽”选择clicked()信号Qt Creator 会自动生成槽函数on_pushButton_clicked()你在里面写ui-label-setText(你好Qt);即可。纯代码的做法在MainWindow构造函数里创建QPushButton和QLabel用connect连接按钮的clicked信号到自定义槽函数再设置布局。两种方式最终效果一样但纯代码让你更清楚对象树、父子关系和信号槽的连接过程。提示如果你用 Designerui-setupUi(this)这行代码必须在构造函数里最先调用它会根据.ui文件创建所有控件并设置好布局。如果你在手写代码里又重复创建了同名控件可能会导致界面错乱。另外ui指针指向的控件对象归MainWindow管理不需要手动 deleteQt 的父子对象机制会自动释放。我建议第一个程序这样练先用 Designer 做一个带按钮和标签的窗口实现点击改变文字然后新建一个纯代码项目不用.ui文件手动写出同样的界面。两次下来你对 Qt 的控件创建、布局管理和信号槽会有完全不同的理解。别怕麻烦这一步省了后面做复杂界面时还是要补课。2.4 代码逐行解析与信号槽初体验信号槽是 Qt 最核心的机制没有之一。简单说信号signal是对象发出的通知槽slot是接收通知的函数。比如按钮被点击时会发出clicked()信号你可以把它连接到一个槽函数槽函数就会自动执行。连接方式有两种旧版宏SIGNAL和SLOT新版函数指针语法。Qt 5 之后推荐用函数指针因为编译期就能检查参数类型出错更容易发现。看一个完整的纯代码示例。假设我们不用.ui在mainwindow.cpp里这样写#include mainwindow.h #include QPushButton #include QLabel #include QVBoxLayout #include QWidget MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { QWidget *central new QWidget(this); setCentralWidget(central); QLabel *label new QLabel(原始文字, central); QPushButton *button new QPushButton(点我, central); QVBoxLayout *layout new QVBoxLayout(central); layout-addWidget(label); layout-addWidget(button); connect(button, QPushButton::clicked, this, []() { label-setText(你点击了按钮); }); }这段代码做了什么首先创建一个QWidget作为中央窗口部件setCentralWidget把它设为QMainWindow的中心区域。然后创建标签和按钮父对象都设为central这样它们会显示在central上。QVBoxLayout是垂直布局管理器把标签和按钮从上到下排列。最后用connect把按钮的clicked信号连接到一个 lambda 表达式lambda 里修改标签文字。[]表示按值捕获外部变量这里捕获了label指针。点击按钮时Qt 的事件循环检测到鼠标点击按钮发出信号信号触发槽函数标签文字就变了。这里有个关键点信号和槽的参数必须匹配或者槽的参数可以比信号少。clicked()信号没有参数所以槽函数也不能有参数。如果你连接的是textChanged(const QString)信号槽函数就可以接收一个QString参数。另外connect的第四个参数是连接类型默认是AutoConnection在同一个线程里就是直连跨线程会自动变成队列连接。跨线程更新 UI 是 Qt 新手常犯的错误后面第 4 章会讲。实操心得用 lambda 写槽函数很方便但要注意捕获方式。如果捕获了this而对象在信号发出前被销毁就会崩溃。稳妥的做法是使用QPointer或者确保对象的生命周期覆盖连接。对于第一个程序直接用this作为接收者Qt 会在this销毁时自动断开连接所以connect(button, QPushButton::clicked, this, [](){...})是安全的。3. 编译、运行与调试的完整流程3.1 构建套件 Kit 的配置与常见错误Qt Creator 的构建套件Kit是编译、运行、调试三者的组合。一个 Kit 包含编译器、调试器、Qt 版本和构建工具。你装好 Qt 后Qt Creator 通常会自动检测到可用的 Kit。打开工具-选项-构建和运行-构建套件(Kit)你会看到列表。每个 Kit 前面有图标绿色对勾表示完全可用黄色感叹号表示缺少某些组件。如果你看到Desktop Qt 5.15.2 MinGW 64-bit显示黄色点开它检查Qt version是否指向D:\Qt\5.15.2\mingw81_64\bin\qmake.exeC compiler是否指向D:\Qt\Tools\mingw810_64\bin\g.exeDebugger是否指向gdb.exe。如果某个路径为空手动浏览选择即可。常见错误一“未找到 Kit”。这通常是因为 Qt 版本没有正确注册。在Qt Versions标签页点击“添加”选择qmake.exe路径然后回到 Kit 页面重新选择。常见错误二“无法启动进程找不到 mingw32-make”。检查构建和运行-构建套件里的CMake Tool或Make Tool是否配置了mingw32-make.exe。常见错误三编译时报“unknown module(s) in qt: serialport”。这说明你在.pro里加了QT serialport但安装 Qt 时没有勾选Qt Serial Port模块。解决办法是重新运行 Qt 安装包在组件里找到对应版本的Qt Serial Port并安装。如果不想重装也可以单独下载模块源码编译但对新手不推荐。还有一个很隐蔽的问题Kit 选错了。比如你装了 MinGW 和 MSVC 两个套件项目默认选了 MSVC但你的代码里用了 MinGW 专有的头文件或者环境变量没配好就会报奇怪的错误。点左下角的构建套件选择器明确选Desktop Qt 5.15.2 MinGW 64-bit。如果项目是从别人那里拷来的.pro.user文件里可能记录了旧的 Kit 路径删掉.pro.user文件重新打开项目让 Qt Creator 重新生成配置往往能解决“明明装了却用不了”的问题。3.2 qmake 与 CMake 构建系统选择Qt 5 默认用 qmakeQt 6 主推 CMake。两者有什么区别qmake 是 Qt 自家的构建工具语法简单.pro文件几行就能描述项目。CMake 是跨平台构建系统功能更强大生态更广但配置文件CMakeLists.txt写起来更啰嗦。对于第一个程序用 qmake 足够了。如果你用的是 Qt 6 并且选了 CMake生成的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)AUTOUIC、AUTOMOC、AUTORCC分别自动处理.ui文件、包含Q_OBJECT宏的头文件和资源文件。find_package找到 Qt6 的 Widgets 模块target_link_libraries把它链接到可执行文件。如果你用 qmake这些工作由 qmake 自动完成不需要手动写。所以新手第一个项目强烈建议 qmake。等你需要集成第三方 CMake 库或者做跨平台大型项目时再切 CMake 也不迟。编译时Qt Creator 默认使用影子构建Shadow build也就是把编译生成的中间文件和可执行文件放在项目目录之外的构建目录里比如build-HelloQt-Desktop_Qt_5_15_2_MinGW_64_bit-Debug。这样做的好处是源码目录保持干净切换 Debug 和 Release 不会互相干扰。你可以在项目-构建设置里看到构建目录。如果编译失败先看“编译输出”窗口的红色错误信息从第一条错误开始改因为后面的错误往往是第一条引起的连锁反应。3.3 运行第一个程序窗口显示与调试输出点击左下角的绿色三角形或者按CtrlRQt Creator 会先编译再运行。如果编译成功会弹出你的窗口。如果窗口一闪而过说明程序在main函数里提前退出了检查w.show()和a.exec()是否都写了。如果窗口显示但标题不对检查setWindowTitle或者.pro里的TARGET。运行后你可以在应用程序输出窗口看到qDebug()打印的信息。比如在main.cpp里加一句qDebug() 程序启动;运行后就能在输出窗口看到。qDebug()是 Qt 的调试输出宏比std::cout更方便支持 Qt 类型而且在 Release 模式下可以通过QT_NO_DEBUG_OUTPUT禁用。调试方面Qt Creator 集成了 GDBMinGW或 CDBMSVC。在代码行号旁边点击可以设置断点然后按F5进入调试模式。程序会在断点处暂停你可以查看变量值、调用栈、内存。对于第一个程序你可以试试在按钮的槽函数里设断点点击按钮后观察程序是否停在断点处label的文本是什么。调试是排查问题的利器但新手往往只用qDebug()。两者结合最好简单流程用qDebug()打日志复杂逻辑用断点单步跟踪。注意在 Windows 上如果程序运行后没有窗口但任务管理器里有进程可能是窗口被创建在了屏幕外或者被其他窗口遮挡。检查是否在构造函数里移动了窗口位置。另一个常见问题是中文乱码如果你用qDebug()输出中文控制台可能显示乱码这是因为 Qt Creator 的应用程序输出窗口默认用 UTF-8而 Windows 控制台用 GBK。解决办法是在main.cpp里设置编码或者直接用QString::fromLocal8Bit转换。不过对于界面上的中文只要源文件保存为 UTF-8一般不会乱码。3.4 程序打包发布windeployqt 的使用程序编译好了你想发给别人用直接拷 exe 过去对方双击很可能报错“缺少 Qt5Core.dll”。因为 Qt 程序依赖很多动态库必须把它们一起打包。Qt 提供了一个工具windeployqt专门用来复制依赖库。用法很简单先编译 Release 版本找到生成的HelloQt.exe把它单独复制到一个空文件夹比如D:\Release\HelloQt。然后打开 Qt 命令行工具切换到该目录执行windeployqt HelloQt.exe它会自动扫描 exe 的依赖把需要的 DLL、插件、翻译文件复制到当前目录。完成后整个文件夹就可以打包发给别人了。注意windeployqt需要和编译时使用的 Qt 版本一致比如你用 MinGW 5.15.2 编译的就要用对应命令行里的windeployqt。如果你用 MSVC则在 VS 命令行里运行。打包后可以先在本机测试把文件夹移到另一个没有 Qt 环境的路径双击运行看是否正常。如果程序还依赖第三方库比如 FFmpeg、Halconwindeployqt不会自动复制它们需要手动把对应的 DLL 放到 exe 旁边。另外Release 版本通常比 Debug 版本小很多发布时一定要用 Release。你可以在 Qt Creator 左下角切换构建配置为Release然后重新构建。打包后的文件夹里会有一个platforms子文件夹里面是qwindows.dll这个不能删否则程序无法启动。如果目标电脑是 32 位系统而你编译的是 64 位程序也无法运行需要对应位数编译。4. 常见问题排查与避坑经验4.1 编译报错unknown module(s) in qt: serialport 等模块缺失这是 Qt 新手最常见的一类错误。你在.pro里写了QT serialport或者代码里#include QSerialPort编译时却提示unknown module(s) in qt: serialport。原因很简单安装 Qt 时没有勾选Qt Serial Port模块。Qt 的模块是可选安装的默认只装核心模块。解决办法找到 Qt 安装目录下的MaintenanceTool.exe运行它登录后选择“添加或移除组件”展开对应 Qt 版本勾选Qt Serial Port然后点击更新。安装完成后重新打开 Qt Creator重新构建项目通常就能通过。如果是QT charts报错同理需要安装Qt Charts。有些模块在 Qt 5 和 Qt 6 里名字不同比如QtCharts在 Qt 6 里可能需要用find_package(Qt6 COMPONENTS Charts)。另外如果你用 CMake需要把find_package和target_link_libraries都写对只加QT 是 qmake 的语法CMake 里无效。排查时先确认三件事模块是否安装、.pro或CMakeLists.txt是否声明、Kit 是否匹配。如果还不行在 Qt Creator 的项目-构建设置里点“执行 qmake”或“重新构建”强制刷新配置。避坑技巧不要手动去改 Qt 安装目录里的文件也不要从网上下载单独的 DLL 往编译器目录里塞。模块缺失就用 MaintenanceTool 补装这是最干净的方式。另外如果你在 Linux 下比如 Ubuntu 20.04安装 Qt 交叉编译环境时串口模块可能叫libqt5serialport5-dev需要用包管理器安装而不是 Qt 安装器。4.2 版本冲突cannot mix incompatible Qt library 的解法这个错误信息非常典型cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)。意思是程序在运行时加载了两个不同小版本的 Qt 库。常见原因是你的系统 PATH 环境变量里有另一个 Qt 版本的 bin 目录或者你拷贝了别人的 DLL 混用。Qt 对版本非常敏感5.15.2 和 5.15.3 虽然只差一个小版本但二进制不兼容。解决办法检查系统环境变量把不需要的 Qt 路径删掉如果程序依赖某个第三方库而那个库链接了另一个 Qt 版本唯一的办法是统一版本重新编译第三方库或者换用同版本的预编译包。在 Qt Creator 里这种情况通常不会出现因为 Kit 会隔离环境。但当你手动运行 exe或者用windeployqt打包时如果 PATH 里存在其他 Qt可能会优先加载错。打包时windeployqt会复制正确的 DLL 到 exe 旁边Windows 加载 DLL 的顺序是exe 所在目录优先于 PATH所以打包后的程序通常没问题。但如果你在开发机上直接运行 Debug 版 exe而 PATH 里有其他 Qt就可能冲突。最简单的排查方法用Process Explorer或Dependency Walker查看程序实际加载的 Qt5Core.dll 路径确认版本。另一个相关问题是Qt 5.15.3和Qt 5.15.2的插件不兼容。比如你用了 5.15.2 的qwindows.dll却加载了 5.15.3 的Qt5Core.dll程序启动时会直接崩溃没有太多提示。所以永远保持 Qt 版本、编译器、插件三者一致。如果你从别人那里拿到一个项目先问清楚他用的 Qt 版本和编译器然后在本机装一模一样的 Kit不要试图用新版本直接打开旧项目除非你准备好处理兼容性问题。4.3 中文乱码、图标不显示、DLL 缺失的快速排查表下面这张表是我自己排错时总结的覆盖了第一个 Qt 程序最容易遇到的几个问题现象可能原因排查方法解决方式界面中文显示为乱码源文件编码不是 UTF-8用记事本另存为查看编码在 Qt Creator 里设置默认编码为 UTF-8文件开头加#pragma execution_character_set(utf-8)MSVC控制台 qDebug 中文乱码控制台编码与 Qt 输出编码不一致看输出窗口是否正常控制台是否乱码在main里用QTextCodec::setCodecForLocale(QTextCodec::codecForName(GBK))程序图标不显示没有设置.rc文件或资源未编译检查.pro里是否有RC_FILE创建.rc文件写入IDI_ICON1 ICON app.ico在.pro里加RC_FILE app.rc双击 exe 提示缺少 Qt5Core.dll没有打包依赖库用 Dependency Walker 查看缺失 DLL用windeployqt复制依赖或把 Qt bin 目录加入 PATH窗口不显示或一闪而过没有调用show()或exec()检查main.cpp确保w.show()和return a.exec();都存在按钮点击无反应信号槽未连接或连接失败在connect后加qDebug()检查返回值确认信号和槽参数匹配检查connect的返回值是否为 true中文乱码问题特别值得展开。Qt 5 默认使用 UTF-8 编码源文件但 Windows 的 MSVC 编译器可能把源文件当成 GBK导致中文字符串字面量出错。最稳的做法是在.pro里加QMAKE_CXXFLAGS /utf-8MSVC或者确保文件保存为带 BOM 的 UTF-8。MinGW 通常没这个问题但如果你在代码里用std::cout输出中文控制台还是可能乱码这时用qDebug()更省心。图标问题则要求你准备一个.ico文件然后用 RC 文件嵌入不要直接把 png 改成 ico格式不对会导致编译失败。4.4 快捷键与效率技巧开发时少点鼠标Qt Creator 有很多快捷键熟练之后能省大量时间。最常用的几个CtrlR编译并运行CtrlB只编译F5开始调试F9设置或取消断点F10单步跳过F11单步进入ShiftF11单步跳出。CtrlK打开定位器可以快速搜索文件、类、函数输入:加行号还能跳转到指定行。CtrlShiftR是全局重命名改类名或变量名时非常方便。Alt0切换侧边栏Alt1打开项目视图Alt4打开构建输出。代码编辑方面Ctrl/注释或取消注释当前行CtrlShiftEnter在上方插入空行CtrlEnter在下方插入空行。CtrlD删除当前行CtrlShiftV从历史剪贴板粘贴。如果你用 Designer 拖界面CtrlShiftF可以格式化代码CtrlShiftS保存所有文件。还有一个隐藏技巧在.pro文件里右键选择“执行 qmake”可以在不重新构建整个项目的情况下刷新工程文件添加新文件或修改模块后很有用。实操心得我习惯把CtrlR改成F5之外的按键不用改默认就好。但有一个设置建议打开工具-选项-环境-键盘搜索“运行”看看当前绑定。另外Qt Creator 的“伪造历史”功能F2 跳转到符号定义在阅读大型项目时非常有用。如果你从 Visual Studio 转过来可能会觉得 Qt Creator 的调试器界面简陋但它的表达式求值和内存查看其实够用而且启动速度比 VS 快很多。5. 从第一个程序延伸下一步该学什么5.1 信号槽深入与自定义信号第一个程序里你用的是按钮自带的clicked()信号连到 lambda 或普通函数。实际项目中你经常需要自定义信号比如一个数据接收类收到完整数据后发出dataReady(QByteArray)信号让界面更新。自定义信号写在类声明里用signals:关键字标记不需要实现。槽函数用public slots:或private slots:声明需要实现。连接时发送者对象发出信号接收者对象的槽被调用。信号可以带参数参数类型需要注册到 Qt 元对象系统基本类型和 Qt 类型都支持。一个典型的自定义信号示例class Worker : public QObject { Q_OBJECT public: explicit Worker(QObject *parent nullptr) : QObject(parent) {} signals: void progressChanged(int percent); public slots: void doWork() { for (int i 0; i 100; i 10) { emit progressChanged(i); QThread::msleep(100); } } };注意Q_OBJECT宏必须写在类声明开头否则信号槽和元对象功能都不生效。emit是 Qt 的关键字用来发出信号其实它只是个宏不写也能编译但建议保留以增强可读性。如果要在不同线程间传递信号参数类型需要是可拷贝的并且连接方式要选Qt::QueuedConnection或使用默认的AutoConnection。跨线程更新 UI 时绝对不能直接在子线程里调用ui-label-setText()必须通过信号槽让主线程来更新。这是 Qt 线程安全的基本规则违反会导致程序随机崩溃。5.2 界面布局与绘图从静态窗口到动态图表掌握了基本控件后下一步是学习布局管理器。Qt 提供了QHBoxLayout、QVBoxLayout、QGridLayout、QFormLayout等。布局管理器让控件随窗口大小自动调整比手动设置坐标强大得多。你可以用 Designer 拖布局也可以纯代码嵌套布局。一个经验不要给控件设置固定的setGeometry除非你明确知道窗口不会缩放。用布局管理器配合setStretch和setSizePolicy可以做出自适应的界面。如果你要做数据监控或曲线显示Qt Charts模块是首选。它提供了QChartView、QLineSeries、QValueAxis等类可以画折线图、柱状图、饼图。使用前需要在.pro里加QT charts并在代码里#include QtCharts。对于大量数据点的实时刷新直接把所有点都加到QLineSeries里会导致界面卡顿。优化方法使用QChart::setAnimationOptions(QChart::NoAnimation)关闭动画只保留最近 N 个点或者用QVectorQPointF批量替换。如果曲线刷新频率很高可以考虑把数据采集放在子线程通过信号把数据块发给主线程更新图表这样界面不会卡死。另一个常用的是QCustomPlot这是一个第三方绘图库只有一个头文件和源文件集成简单性能也不错。很多人从 Qt Charts 转到 QCustomPlot就是因为它在大量数据刷新时更流畅。选择哪个取决于你的需求Qt Charts 官方维护、风格统一、和 Qt 集成好QCustomPlot 轻量、灵活、社区示例多。如果你只是画几条曲线Qt Charts 足够如果要画几十万点的实时波形QCustomPlot 或 OpenGL 绘图更合适。5.3 文件操作与 JSON 读写让程序能存配置实际程序很少是孤立的总需要读写文件。Qt 的QFile、QTextStream、QDataStream提供了跨平台的文件操作。读文本文件QFile file(config.txt); if (file.open(QIODevice::ReadOnly | QIODevice::Text)) { QTextStream in(file); while (!in.atEnd()) { QString line in.readLine(); // 处理每一行 } file.close(); }写文件类似用QIODevice::WriteOnly或Append。注意QTextStream默认编码在 Qt 5 是本地编码Qt 6 是 UTF-8处理中文时最好显式设置编码。对于配置文件JSON 是现在最常用的格式。Qt 提供了QJsonDocument、QJsonObject、QJsonArray来解析和生成 JSON。例如QJsonObject obj; obj[name] HelloQt; obj[version] 1.0; QJsonArray arr {1, 2, 3}; obj[values] arr; QJsonDocument doc(obj); QFile file(config.json); file.open(QIODevice::WriteOnly); file.write(doc.toJson()); file.close();读取时用QJsonDocument::fromJson解析然后通过object()和array()获取数据。JSON 读写非常直观适合保存程序设置、用户数据、网络接口返回结果。如果你需要更复杂的配置可以考虑QSettings它能自动把配置存到注册表Windows或 plistmacOS或 ini 文件Linux跨平台且无需手动解析。不过QSettings不适合存大量结构化数据JSON 更灵活。5.4 项目实战建议从小工具开始别一上来就做 IDE学完第一个程序很多人热血沸腾想做个“全能工具箱”或者“仿 QQ 界面”。我的建议是先做 3 到 5 个微型项目每个只解决一个小问题比如一个带按钮的计时器点击开始后标签每秒更新练习QTimer和信号槽。一个简单的文本编辑器能打开、保存、另存为练习QFileDialog和文件读写。一个串口调试助手能扫描串口、发送和接收数据练习QSerialPort和线程。一个图片查看器能打开文件夹、上一张下一张练习QDir、QPixmap和布局。一个 JSON 格式化工具粘贴 JSON 后高亮显示练习QPlainTextEdit和语法高亮。每个项目控制在 300 行代码以内做完后写一篇简短的笔记记录遇到的坑和解决办法。这样积累下来你对 Qt 的常用模块、事件循环、对象树、内存管理会有肌肉记忆。之后再去做复杂项目比如上位机、数据采集系统就不会因为基础不牢而卡住。另外多读 Qt 自带的示例代码在 Qt Creator 的欢迎界面点击“示例”里面有大量可运行的项目从calculator到chart都有这是最好的学习资料。最后再分享一个小技巧遇到不懂的类把光标放在类名上按F1Qt Creator 会打开帮助文档里面不仅有 API 说明还有示例代码。Qt 的帮助文档是离线的非常完整养成查文档的习惯比到处搜博客更靠谱。另外Qt 的源码也是开源的如果你想知道某个函数内部怎么实现的按住Ctrl点击函数名就能跳转到源码这对深入理解 Qt 非常有帮助。我个人在带新人的时候最看重的不是他写了多少行代码而是他有没有把第一个程序真正跑通、打包、发给别人运行。这个过程会逼着你解决环境配置、依赖库、版本冲突、编码等一系列问题这些才是实际开发中真正花时间的地方。第一个 Qt 程序只是一个起点后面还有信号槽的线程安全、模型视图架构、QML 与 C 交互、跨平台部署等一大堆内容等着你。别急一个一个来每解决一个问题你对 Qt 的理解就深一层。