现代Qt开发教程（新手篇）0.0——Qt6 安装踩坑指南¶
1. 前言：为什么装个 Qt 都能折腾半夜¶
说实话，我第一次装 Qt 的时候真的以为双击安装程序就能完事。结果呢？光是一个编译器版本不对就让我折腾了三个小时。后来装了又卸、卸了又装，差不多把能踩的坑都踩了一遍。
所以这一篇我们不是在走过场，而是真的要陪大家把这个环境彻底搭稳。我们会覆盖 Windows、Linux 原生、还有 WSL2 三种场景——因为我知道总有人会在 WSL2 里跑 Qt，然后奇怪为什么界面弹不出来（别笑，我当年就是）。
现在我们要做的是：先把地基打牢，后面才能愉快地写代码。不然你会收获一个非常漂亮的编译错误列表，然后对着屏幕发呆。
2. 环境说明¶
本教程基于 Qt 6.9.1 版本编写，以下平台均已验证：
| 平台 | 编译器要求 | 测试状态 |
|---|---|---|
| Windows 10/11 | MSVC 2019/2022 或 MinGW 11.2+ | 已验证 |
| Linux（Ubuntu 22.04+） | GCC 11+ | 已验证 |
| WSL2 + WSLg | 同 Linux | 已验证 |
Qt 6.9 对 CMake 最低版本要求是 3.26，额，其实是我猜测的，当然，Qt的确不支持低版本的CMake，我的建议是为什么不支持新的呢？
3. Qt Online Installer 详解¶
3.1 第一步——获取安装程序¶
我们要用的是 Qt 官方的在线安装器，它是统一入口，不管你是哪个平台都用它。
官方下载地址：https://www.qt.io/download-qt-installer
你可能会看到两个版本：Open Source 和 Commercial。对我们学习和个人项目来说，选 Open Source 就行，它是 LGPL 协议的，商业友好。注册个 Qt 账号就能免费用，不用想太复杂。
这里有个非常容易踩的坑——如果你直接从官网下载，大概率会盯着进度条发呆两个小时。国内网络环境下必须用镜像源，不然就是在跟自己过不去。你可以找找国内各大镜像站的 Qt 离线安装包，或者让科学上网的朋友帮你下一份。
3.2 安装器选项逐行解读¶
打开安装器后，第一步会让你登录。用你刚才注册的 Qt 账号登录就行，跳不过。
然后到了关键环节——选择安装组件。这里真的很多人会乱选一通，要么装了一堆用不上的东西占几十个 G，要么该装的没装。让我逐个说清楚。
首先说无论如何都要装的。Qt 6.9.1 下的 Desktop 组件是核心中的核心——Windows 用户在 MinGW 和 MSVC 之间二选一就行，MinGW 轻量但 MSVC 调试体验更好；Linux 和 WSL2 用户选 Desktop (GCC)。CMake 也要勾上，虽然你系统里可能已经有了，但 Qt 自带的版本是经过验证的，版本对应 Qt 6.9 要求，省心。Qt Creator 是官方 IDE，虽然后面我们也会教 VS Code 和 CLion 的用法，但至少装一个备用，排错的时候很有用。
然后是根据需求选的。如果你要做 QML 界面，装上 Qt 6.9.1 里的 Qt Quick 2D Renderer，纯 Widgets 应用可以暂时跳过。做网络登录（OAuth）的话需要 Qt Network Authorization。如果你要维护旧代码，装个 Qt 5.15 兼容套件，纯新项目可以不装。
至于 Android / iOS / WebAssembly 这些，除非你要做跨平台移动端，否则别装——装了会显著增加安装时间。Qt 3D / Qt WebGL / Qt SCXML 之类也是特定场景才用到的，真需要的时候再装不迟。
还有一件事千万别手滑——安装路径别带空格。装到 C:\Qt 或 D:\Dev\Qt 这种简单路径就好，别搞什么 C:\Program Files\Qt。CMake 和某些构建工具遇到空格路径会炸，而且报错信息还特别迷惑，你可能都想不到是路径的问题。
3.3 安装过程验证¶
安装完成先别急着关窗口，我们简单验证一下。打开命令行（Windows 用 PowerShell 或 CMD，Linux 用终端），输入 qmake --version 或 cmake --version，如果能看到版本号输出，说明 PATH 配置成功。
说到这里，你可能会问：Qt Online Installer 里的 Desktop 组件到底是干什么的？为什么 Windows 上有 MinGW 和 MSVC 两个版本？简单来说，Desktop 组件就是开发桌面应用的编译工具链和库。MinGW 是基于 GCC 的 Windows 编译器，开源免费；MSVC 是微软的编译器，与 Visual Studio 集成更好。选哪个看你的实际情况——如果已经装了 Visual Studio，用 MSVC 体验会更好。
4. Windows 专题¶
4.1 编译器配置¶
如果你选了 MinGW，安装器会帮你顺带装好 MinGW 编译器，基本不用额外配置。
但如果你选了 MSVC，你需要确保两件事：一是 Visual Studio 2019 或 2022 已经安装，并且勾选了「使用 C++ 的桌面开发」工作负载；二是 Windows SDK 已安装，在 VS Installer 里找到单个组件，搜索「Windows SDK」，选一个最新版装上。
这一点真的坑了我半天——很多人以为装了 Qt 就等于装了 C++ 编译器，两码事。如果你只装了 VS 主体但没勾 C++ 工作负载，CMake 会找不到 cl.exe，构建的时候一脸懵逼，报错信息还不会直接告诉你"你没装 C++ 组件"。所以一定要打开 VS Installer → 修改 → 确认「使用 C++ 的桌面开发」已经勾上。
4.2 环境变量验证¶
Windows 下安装器一般会自动配 PATH，但万一没配上，就得手动来。右键「此电脑」→ 属性 → 高级系统设置 → 环境变量，在 PATH 里添加你的 Qt bin 目录：MinGW 版本加 C:\Qt\6.9.1\mingw_64\bin，MSVC 版本加 C:\Qt\6.9.1\msvc2019_64\bin。加完之后重启命令行窗口，再试 qmake --version。
来验证一下环境是否正确：在 PowerShell 里跑 qmake --version 看 Qt 版本，跑 cmake --version 看 CMake 版本，再 ls C:\Qt\6.9.1\mingw_64\bin 确认 Qt 库文件都在。三条命令都有正常输出，环境就没问题。
5. Linux 专题¶
5.1 系统依赖安装¶
Ubuntu/Debian 下，Qt 依赖一堆系统库。先装这些：
sudo apt update
sudo apt install -y build-essential libgl1-mesa-dev libxkbcommon-x11-0 \
libfontconfig1-dev libfreetype6-dev libx11-dev libxext-dev libxfixes-dev \
libxi-dev libxrender-dev libxcb1-dev libx11-xcb-dev libxcb-glx0-dev \
libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev \
libxcb-sync0-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev \
libxcb-util-dev libxcb-xinerama0-dev libxcb-xkb-dev libxcb-cursor0-dev
我知道这串命令看着很长，但缺任何一个都可能编译失败。别偷懒，一次跑完。
5.2 安装器权限问题¶
Linux 下运行 Qt 安装器可能需要可执行权限：
这里有个大坑——如果你看到缺库就装一个然后反复编译，大概率会一直失败。Linux Qt 缺 libxcb 不是开玩笑的，最典型的症状就是程序启动就崩溃，日志里只有一句 "Failed to load platform plugin xcb"。上面那串依赖我真的替你踩过了，一次装齐省心。别想着只装 build-essential 和 libgl1-mesa-dev 就够了——你确实能编译通过，但运行 GUI 的时候会直接报 "Could not connect to display" 或 "Failed to load platform plugin xcb"。
6. WSL2 专题：GUI 的正确打开方式¶
WSL2 现在已经支持 GUI 了（WSLg），但默认配置下你可能遇到显示问题。
6.1 确认 WSLg 可用¶
在 WSL2 终端里运行：
如果你的 Windows 11 版本够新（Build 22000+），WSLg 应该是默认启用的。
6.2 Qt 环境配置¶
WSL2 下推荐直接用 Windows 版的 Qt，这样不用在 Linux 里再装一遍。
在 ~/.bashrc 添加：
但要注意：这样运行的是 Windows 编译的 Qt 程序，如果你想在 WSL2 里原生编译 Linux 版，还是得按 Linux 篇的流程来。
Win11 + WSL2 时代，不用折腾 X Server 了。以前那套 VcXsrv、X410 的方案可以丢掉了，直接确认 WSLg 已启用就行。随便设一个 DISPLAY 值或者用旧的 X Server 方案，只会收获一个 "could not connect to display" 的报错。
7. 常见安装报错与修复¶
7.1 "Error while loading module dependencies"¶
这个问题常见于 Windows，通常是三个原因之一：缺少 Visual C++ Redistributable、路径里有中文字符、或者杀毒软件拦截。解决方法就是装最新的 VC++ Redistributable，把安装路径改成纯英文，临时关闭杀毒软件。
7.2 "CMake was unable to find a build program"¶
CMake 找不到编译器。Windows 上检查 MSVC 或 MinGW 是否在 PATH 里，Linux 和 WSL2 上跑一下 which g++ 看看有没有输出。
7.3 安装器卡在 "Downloading"¶
网络问题，科学上网或者换国内镜像源。
8. 最终验证¶
安装完成，我们来打个收尾。Windows、Linux、WSL2 通用的验证流程：
# 1. 检查 qmake
qmake --version
# 2. 检查 CMake
cmake --version
# 3. 最重要的一步——创建测试工程
mkdir qt-test && cd qt-test
cmake -DCMAKE_PREFIX_PATH=/path/to/Qt/6.9.1/gcc_64 ..
# Windows 路径示例：-DCMAKE_PREFIX_PATH=C:/Qt/6.9.1/mingw_64
如果以上都能顺利跑通，恭喜你，环境搞定了！接下来就可以正式写 Qt 代码了。
9. 练习项目¶
练习项目：Hello Qt 环境验证
创建一个最小化的 Qt 工程，编译运行后弹出一个空窗口，标题显示 "Qt is alive!"。这个项目的目的不是学 Qt API，而是验证你的开发环境真的能跑起来。
完成标准：工程能用 CMake 成功配置，编译无报错，运行后能看到一个空白窗口标题显示正确。如果这一步都跑不通，说明环境还有问题，别着急往后学。
具体来说，新建一个文件夹，里面放 main.cpp 和 CMakeLists.txt。CMakeLists.txt 里 find_package Qt6 的 Core 和 Widgets 模块，main.cpp 里创建一个 QApplication 和一个空 QWidget，调用 show()。然后用命令行 cmake -B build && cmake --build build 来编译。
10. 官方文档参考¶
Qt 官方安装指南 · 包含各平台的详细安装说明 Qt 6.9.1 平台要求 · 确认你的系统是否被支持 CMake 与 Qt 配置 · CMake 集成的最佳实践
（链接已验证，2026-03-17 可访问）
到这里就大功告成了！ 环境搭好，下一章我们就能愉快地写第一行 Qt 代码了。如果你在这一步遇到任何奇怪的问题，别慌——我也遇到过，大概率是路径或编译器的问题，对着上面的坑检查一遍基本能解决。