如何步入 Qt，从下载 SDK 到学会使用说明文档再到实现第一个 Label 的 hello world

一、前言如果你是一名 C 程序员想做跨平台的桌面应用、带 GUI 的工具、或者嵌入式设备上的界面Qt 几乎是绕不开的选择。Qt 本身不是一个新语言而是基于 C 的一个库/框架。它提供了完整的 GUI 工具包以及网络、数据库、绘图、多线程等模块让一份代码可以同时跑在 Windows、macOS、Linux 上。但很多新手第一次接触 Qt 时会被这些绊住不知道去哪下载 SDK装完之后不知道从哪开始出了问题不会查文档看代码像看天书这篇文章就从零开始带你走完整个流程下载 → 安装 → 学会看文档 → 写出第一个 Label 的 Hello World。二、下载 Qt SDK这里要先说一个坑Qt 从 5.15 版本之后官方取消了离线安装包的下载。也就是说我们没法像以前那样直接下一个几百 MB 的 exe 双击装完。现在必须先下载 Qt 官方的在线下载器Online Installer再用它去拉取 SDK 本体。不过官方下载器服务器在国外直接从官网下可能很慢甚至下不动。国内推荐走镜像源速度会快很多清华镜像源Index of /qt/official_releases/online_installers/ | 清华大学开源软件镜像站 | Tsinghua Open Source Mirror阿里镜像源qt-official_releases-online_installers安装包下载-开源镜像站-阿里云这里以清华镜像为例进到镜像站后找到online_installers目录里面按系统Windows / macOS / Linux列出了各个版本的官方下载器挑自己对应的那个下就行。官方下载器地址网速好可以走这个Index of /official_releases/online_installers1. 注册 Qt 账号不管走哪个渠道下载前都得有一个 Qt 账号免费注册。后面维护、安装、更新都要用到。2. 选择对应系统的下载器根据自己的系统选Windowsqt-online-installer-windows-x64.exemacOSqt-online-installer-mac.dmgLinuxqt-online-installer-linux-x64.run三、安装 Qt1. 运行安装器双击 exe第一次会让你再登录一次。登录后进入组件选择界面。这里用上述注册的Qt账号登录即可不多展示。建议不要直接启动安装器可以在cmd中进行启动切换安装源至国内镜像站下载速度更快这里以阿里云镜像为例我们在cmd中输入对应指令注意此处指令不一定与我相同该指令含义为.\为运行后面无需空格紧跟所下载exe文件的路径重点此处需要根据自己情况进行调整随后空格输入--mirror https://mirrors.aliyun.com/qt切换下载源到阿里镜像。 至于如何调出cmdwinR输入cmd回车即可。2. 安装选项Qt安装目录默认是C:\Qt建议保持默认路径有空格后面会出怪问题。空间预留20~30 GB比较稳。这里包的选择可以选择两个桌面开发和自定义安装桌面开发可以帮我们自动勾选桌面开发的必备工具自定义方便我们进行Qt版本的选择。3. 选择组件这一步最关键进入组件选择页面后列表会分两大块Qt—— 核心框架、各个模块、源码Developer and Designer Tools—— 开发工具、IDE、编译器Developer and Designer Tools部分默认勾选Qt Creator和CMake基本不用管。Qt这块才是重点——展开某个 Qt 版本比如Qt 6.6.x会冒出一长串子选项。下面逐个解释。A. 编译器套件必选且 MSVC / MinGW 二选一选项含义是否必选MSVC 2019/2022 64-bit微软 Visual C 编译器套件。本机需已装对应版本的 Visual Studio跟 MinGW 二选一MinGW 11.2.0 / 13.1.0 64-bitGCC 在 Windows 上的移植版自带编译器不用装 VS新手最省事跟 MSVC 二选一Android给 Android 设备开发用桌面用不到iOS给 iOS / macOS 开发用Windows 装不了WebAssembly让 Qt 程序跑在浏览器里按需⚠️MSVC 和 MinGW 不要同时勾选工具链会冲突。如果你选了 MSVC还要在 Developer and Designer Tools 里再装一个 MinGW因为部分工具链会用到。B. Qt 模块按需勾选可多选选项作用是否必选SourcesQt 源码F12 能直接跳进去看实现强烈建议勾选Qt 5 Compatibility ModuleQt 5 → Qt 6 的兼容层老项目迁移用新项目不用Qt Charts二维图表折线、柱状、饼图按需Qt Data Visualization3D 图表三维柱状、曲面、热力图按需Qt 3D3D 场景与渲染游戏/3D 应用Qt Multimedia音视频播放、摄像头调用媒体类应用Qt WebEngine嵌入 Chromium 内核的浏览器网页嵌入类应用Qt Network AuthorizationOAuth 等网络授权协议按需Qt PDFPDF 文档渲染按需Qt PositioningGPS / 定位移动端Qt Sensors传感器陀螺仪、加速度计等移动端 / IoTQt Serial BusCAN、ModBus 等工业总线工控 / 嵌入式Qt Serial Port普通串口通信工控 / 嵌入式Qt Speech文字转语音TTS按需Qt Virtual Keyboard屏幕虚拟键盘嵌入式 / 触屏Qt Lottie AnimationLottie 动画播放按需Qt Remote Objects跨进程 / 跨设备对象通信分布式场景Qt Image Formats额外图片格式TIFF、MNG 等按需Qt SQL Drivers数据库驱动SQLite 默认带MySQL/PSQL/Others 按需勾数据库应用C. 新手最小必选套餐如果你只是想先把第一个 Hello World 跑起来按下面这套勾就够了这里以Qt6.8.3为例这里先搭起来大致骨架后面用到了某些其余部件可以再通过 MaintenanceTool 补装。新手建议选MinGW 路线不用再单独装 Visual Studio省一堆麻烦。等你熟悉了想用 MSVC 再切也行。4. 等待安装下载 2~5 GB 不等看网速。中间别关窗口。四、第一次打开 Qt Creator装完在开始菜单找到Qt Creator打开。欢迎界面你会看到Examples官方示例Tutorials教程Create Project创建项目先别急着创建项目——先学会查文档。五、学会使用 Qt 说明文档新手最重要的一步Qt 的官方文档是它做得最良心的地方没有之一。新手和老手的差距很大程度上就在会不会查文档。1. 三种文档入口入口一Qt Creator 内置帮助最常用在代码编辑器里把光标放到某个类比如QLabel上按F1右侧或下方会自动弹出这个类的完整文档。入口二在线文档访问 https://doc.qt.io/qt-6/ 搜类名、搜功能、查版本差异都很好用。入口三本地 Qt Assistant2. 文档怎么读以 QLabel 为例打开 QLabel 的文档页面从上到下你会看到这些区块区块看什么Detailed Description这个类是干嘛的、典型用法Public Types / Public Functions它能干什么公开方法Properties它的属性比如 text、alignment、pixmapSignals / Public Slots能发什么信号、能接收什么槽Inherits继承自谁能用哪些父类功能Examples官方示例代码Member List完整成员列表3. 看示例代码每个类的文档底部都有Examples链接点进去就是官方给出的实际用法片段比自己瞎试快十倍。4. 查继承关系类名旁边会写Inherits: QFrame → QWidget → QObject。这告诉你QLabel 能用 QFrame 的功能边框、形状能用 QWidget 的功能大小、位置、显示/隐藏最底层是 QObject信号槽、对象树都在这学会查文档比记住所有 API 重要一万倍。六、实现第一个 Label 的 Hello World理论讲完了现在动手。1. 创建项目打开 Qt Creator →File → New File or Project选Application → Qt Widgets Application项目名填HelloQt路径选个不带中文和空格的目录Build system 选qmake新手友好或CMake更主流一直 Next最后 Finish2. 项目结构HelloQt/ ├── HelloQt.pro # 项目文件qmake ├── main.cpp # 程序入口 ├── mainwindow.h ├── mainwindow.cpp ├── mainwindow.ui # 界面文件XML 描述 └── mainwindow.ui.h3. 用纯代码方式加一个 Label新手阶段建议先用代码写一次别直接拖控件。这样能看清底层到底发生了什么。打开mainwindow.cpp改成下面这样#include mainwindow.h #include ui_mainwindow.h // 头文件包含 #include QLabel MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); // 新建Label对象 QLabel *label new QLabel(this); // 设置Label文本 label-setText(hello world!); } MainWindow::~MainWindow() { delete ui; }4.用图形界面加一个Label除了纯代码的方式我们可以直接通过图像操作进行Label添加我们双击.ui文件或者点击设计会进入一下界面这里我们可以在左侧选择需要添加的控件比如我们选择Label并且拖动到指定位置就可以实现第一个 hello world程序的实现了5. 编译运行按Ctrl R或者左下角绿色三角按钮第一次会编译 1~2 分钟。编译成功会弹出一个窗口中间显示 hello world!这几个字。恭喜第一个 Qt 程序跑起来了。七、新手常见踩坑1. 编译报错 No rule to make target...删掉 build 目录重新编译或者菜单Build → Clean All Project再Rebuild2. 窗口不显示确认w.show()调用了main 函数里必须是QApplicationGUI 程序用这个不能用QCoreApplication3. 中文乱码Qt 5 默认按系统编码Qt 6 默认 UTF-8源文件保存为 UTF-8或者用QString::fromLocal8Bit(中文)4. 链接报错 undefined reference to vtable for...类里如果有Q_OBJECT宏必须重新 qmakeBuild → Run qmake再重新构建八、总结走完这条路你应该✅ 装好了 Qt Qt Creator✅ 知道按 F1 看文档、查示例✅ 写出了第一个带 Label 的窗口