Qt 环境搭建 #
安装前的准备 #
在安装 Qt 之前，需要确保系统满足以下要求：
系统要求 #
text
┌─────────────────────────────────────────────────────────────┐
│ 系统要求 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Windows： │
│ - Windows 10/11 (64位) │
│ - 至少 4GB 内存 │
│ - 至少 10GB 磁盘空间 │
│ │
│ macOS： │
│ - macOS 10.15 或更高版本 │
│ - 至少 4GB 内存 │
│ - 至少 10GB 磁盘空间 │
│ │
│ Linux： │
│ - 主流发行版 (Ubuntu 20.04+, Fedora, etc.) │
│ - 至少 4GB 内存 │
│ - 至少 10GB 磁盘空间 │
│ │
└─────────────────────────────────────────────────────────────┘
编译器要求 #
| 平台 | 推荐编译器 |
|---|---|
| Windows | MSVC 2019+, MinGW 11.2+ |
| macOS | Xcode 13+, Clang |
| Linux | GCC 9+, Clang 10+ |
Windows 安装 #
方法一：在线安装器（推荐） #
text
步骤 1：下载安装器
┌─────────────────────────────────────────────────────────────┐
│ │
│ 访问 Qt 官方下载页面： │
│ https://www.qt.io/download-qt-installer │
│ │
│ 选择：qt-unified-windows-x64-online.exe │
│ │
└─────────────────────────────────────────────────────────────┘
步骤 2：运行安装器
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. 双击运行安装器 │
│ 2. 登录 Qt 账户（没有则注册） │
│ 3. 接受许可协议 │
│ 4. 选择安装路径 │
│ │
└─────────────────────────────────────────────────────────────┘
步骤 3：选择组件
┌─────────────────────────────────────────────────────────────┐
│ │
│ 推荐选择： │
│ │
│ Qt 6.x │
│ ├── MSVC 2019 64-bit │
│ ├── MinGW 11.2.0 64-bit │
│ ├── Sources │
│ └── Qt 5 Compatibility Module │
│ │
│ Developer and Designer Tools │
│ ├── Qt Creator │
│ ├── CMake │
│ ├── Ninja │
│ └── MinGW 11.2.0 64-bit │
│ │
└─────────────────────────────────────────────────────────────┘
方法二：离线安装包 #
text
适用于网络受限环境：
1. 下载离线安装包
- qt-opensource-windows-x86-6.x.x.exe
2. 运行安装程序
- 按向导完成安装
3. 手动配置编译器
- Qt Creator -> 工具 -> 选项 -> Kits
配置环境变量 #
text
添加到系统 PATH：
C:\Qt\6.x.x\msvc2019_64\bin
C:\Qt\Tools\CMake_64\bin
C:\Qt\Tools\Ninja
验证安装：
> qmake --version
QMake version 3.1
Using Qt version 6.x.x in C:/Qt/6.x.x/msvc2019_64/lib
macOS 安装 #
方法一：在线安装器 #
text
步骤 1：下载安装器
┌─────────────────────────────────────────────────────────────┐
│ │
│ 访问 Qt 官方下载页面： │
│ https://www.qt.io/download-qt-installer │
│ │
│ 选择：qt-unified-mac-x64-online.dmg │
│ │
└─────────────────────────────────────────────────────────────┘
步骤 2：安装 Xcode（必须）
┌─────────────────────────────────────────────────────────────┐
│ │
│ # 安装 Xcode Command Line Tools │
│ xcode-select --install │
│ │
│ # 或从 App Store 安装完整 Xcode │
│ │
└─────────────────────────────────────────────────────────────┘
步骤 3：运行 Qt 安装器
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. 挂载 DMG 文件 │
│ 2. 运行 Qt 安装器 │
│ 3. 登录 Qt 账户 │
│ 4. 选择组件 │
│ │
│ 推荐选择： │
│ Qt 6.x │
│ ├── macOS (clang 64-bit) │
│ └── Sources │
│ │
└─────────────────────────────────────────────────────────────┘
方法二：Homebrew 安装 #
bash
# 安装 Qt
brew install qt
# 安装 Qt Creator
brew install --cask qt-creator
# 配置路径
echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
验证安装 #
bash
# 检查 qmake
qmake --version
# 检查 Qt 安装路径
which qmake
Linux 安装 #
Ubuntu/Debian #
bash
# 安装依赖
sudo apt update
sudo apt install build-essential libgl1-mesa-dev
# 方法一：在线安装器
# 下载并运行
chmod +x qt-unified-linux-x64-online.run
./qt-unified-linux-x64-online.run
# 方法二：apt 安装（版本可能较旧）
sudo apt install qt6-base-dev qt6-tools-dev
sudo apt install qtcreator
Fedora #
bash
# 安装依赖
sudo dnf install @development-tools
sudo dnf install mesa-libGL-devel
# 安装 Qt
sudo dnf install qt6-qtbase-devel qt6-qttools-devel
sudo dnf install qt-creator
Arch Linux #
bash
# 安装 Qt 和 Qt Creator
sudo pacman -S qt6-base qt6-tools qtcreator
# 安装额外模块
sudo pacman -S qt6-multimedia qt6-networkauth
Qt Creator 配置 #
首次启动配置 #
text
┌─────────────────────────────────────────────────────────────┐
│ Qt Creator 配置 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 配置编译器 │
│ 工具 -> 选项 -> Kits -> 编译器 │
│ - 自动检测通常能找到已安装的编译器 │
│ - 手动添加编译器路径 │
│ │
│ 2. 配置 Qt 版本 │
│ 工具 -> 选项 -> Kits -> Qt Versions │
│ - 添加 qmake 路径 │
│ - 例如：C:\Qt\6.x.x\msvc2019_64\bin\qmake.exe │
│ │
│ 3. 配置构建套件 (Kit) │
│ 工具 -> 选项 -> Kits -> 构建套件 │
│ - 选择编译器 │
│ - 选择 Qt 版本 │
│ - 选择调试器 │
│ │
└─────────────────────────────────────────────────────────────┘
编辑器设置 #
text
推荐设置：
工具 -> 选项 -> 文本编辑器
├── 字体：Consolas / JetBrains Mono
├── 字号：10-12pt
├── 显示行号：启用
└── 代码折叠：启用
工具 -> 选项 -> C++
├── 代码风格：Qt
├── 自动缩进：启用
└── 括号自动补全：启用
工具 -> 选项 -> 环境
├── 语言：中文/English
├── 主题：Flat/Dark
└── 键盘快捷键：自定义
常用快捷键 #
| 功能 | Windows/Linux | macOS |
|---|---|---|
| 编译项目 | Ctrl+B | Cmd+B |
| 运行 | Ctrl+R | Cmd+R |
| 调试 | F5 | F5 |
| 单步执行 | F10 | F10 |
| 进入函数 | F11 | F11 |
| 查找 | Ctrl+F | Cmd+F |
| 全局搜索 | Ctrl+Shift+F | Cmd+Shift+F |
| 跳转到定义 | F2 | F2 |
| 格式化代码 | Ctrl+I | Cmd+I |
验证安装 #
创建测试项目 #
cpp
// main.cpp
#include <QApplication>
#include <QLabel>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QLabel label("Qt 安装成功！");
label.setWindowTitle("测试程序");
label.resize(300, 100);
label.setAlignment(Qt::AlignCenter);
label.show();
return app.exec();
}
编译运行 #
text
方法一：使用 Qt Creator
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. 文件 -> 新建项目 │
│ 2. 选择 Application -> Qt Widgets Application │
│ 3. 填写项目名称和路径 │
│ 4. 选择构建套件 │
│ 5. 点击运行按钮 (Ctrl+R) │
│ │
└─────────────────────────────────────────────────────────────┘
方法二：命令行编译
┌─────────────────────────────────────────────────────────────┐
│ │
│ # 生成 Makefile │
│ qmake -project │
│ qmake │
│ │
│ # 编译 │
│ make (Windows: mingw32-make) │
│ │
│ # 运行 │
│ ./your_program │
│ │
└─────────────────────────────────────────────────────────────┘
常见问题 #
问题 1：找不到编译器 #
text
解决方案：
Windows：
- 安装 Visual Studio (推荐 Community 版)
- 或安装 MinGW
macOS：
- 安装 Xcode Command Line Tools
xcode-select --install
Linux：
- 安装 build-essential
sudo apt install build-essential
问题 2：Qt Creator 无法找到 Qt 版本 #
text
解决方案：
1. 手动添加 Qt 版本
工具 -> 选项 -> Kits -> Qt Versions -> 添加
2. 指定 qmake 路径
Windows: C:\Qt\6.x.x\msvc2019_64\bin\qmake.exe
macOS: /Users/你的用户名/Qt/6.x.x/clang_64/bin/qmake
Linux: /home/你的用户名/Qt/6.x.x/gcc_64/bin/qmake
问题 3：缺少 OpenGL 库 #
text
解决方案：
Linux (Ubuntu/Debian)：
sudo apt install libgl1-mesa-dev
Linux (Fedora)：
sudo dnf install mesa-libGL-devel
问题 4：中文乱码 #
cpp
// 解决方案：使用 UTF-8 编码
// 在 main.cpp 开头添加
#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8"));
#endif
// 或在 .pro 文件中添加
// MSVC += -execution-charset:utf-8
下一步 #
环境搭建完成后，接下来学习 第一个 Qt 程序，创建你的第一个 Qt 应用！
最后更新：2026-03-29