现代Qt开发——入门 · 环境搭建 · 00 · Qt6 安装踩坑指南

现代Qt开发——入门 · 环境搭建 · 00 · Qt6 安装踩坑指南相关仓库仍然已经开源正在积极火热的建设之中欢迎各位大佬提Issue和PR链接地址https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeQt1. 前言为什么装个 Qt 都能折腾半夜说实话我第一次装 Qt 的时候真的以为双击安装程序就能完事。结果呢光是一个编译器版本不对就让我折腾了三个小时。后来装了又卸、卸了又装差不多把能踩的坑都踩了一遍。所以这一篇我们不是在走过场而是真的要陪大家把这个环境彻底搭稳。我们会覆盖 Windows、Linux 原生、还有 WSL2 三种场景——因为我知道总有人会在 WSL2 里跑 Qt然后奇怪为什么界面弹不出来别笑我当年就是。现在我们要做的是先把地基打牢后面才能愉快地写代码。不然你会收获一个非常漂亮的编译错误列表然后对着屏幕发呆。2. 环境说明本教程基于Qt 6.9.1版本编写以下平台均已验证平台编译器要求测试状态Windows 10/11MSVC 2019/2022 或 MinGW 11.2✅ 已验证LinuxUbuntu 22.04GCC 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 账号就能免费用不用想太复杂。⚠️坑 #1国内下载龟速❌ 错误做法直接从官网下载然后盯着进度条发呆两小时✅ 正确做法使用国内镜像源或者找朋友分享离线安装包 后果你可能会以为自己网络炸了反复重启下载 一句话记住官方源在国外不用镜像就是在跟自己过不去3.2 安装器选项逐行解读打开安装器后第一步会让你登录。用你刚才注册的 Qt 账号登录就行跳不过。然后到了关键环节——选择安装组件。这里真的很多人会乱选一通要么装了一堆用不上的东西占几十个 G要么该装的没装。让我逐个说清楚基础必选无论如何都要装Qt 6.9.1 → DesktopMinGW 或 MSVCWindows 用户二选一MinGW 轻量MSVC 调试体验更好Linux/WSL2 用户这里选 Desktop (GCC)这是你写桌面应用的基础CMake勾上虽然你可能系统里已经有 CMake但 Qt 自带的版本是经过验证的版本对应 Qt 6.9 要求省心Qt Creator官方 IDE虽然后面我们也会教 VS Code 和 CLion至少装一个备用排错时很有用推荐安装根据需求选Qt 6.9.1 → Qt Quick 2D Renderer要做 QML 界面的话装上纯 Widgets 应用可以暂时跳过Qt 6.9.1 → Add-Ons → Qt Network Authorization做网络登录OAuth的话需要不做这个可以先不管Qt 5.15.15 → Qt Compatibility如果你要维护旧代码装个 5.15 兼容套件纯新项目可以不装冷门/可忽略Qt 6.9.1 → Android / iOS / WebAssembly除非你要做跨平台移动端否则别装装了会显著增加安装时间Qt 3D / Qt WebGL / Qt SCXML这些是特定场景用的真需要的时候再装不迟⚠️坑 #2路径别手滑❌ 错误做法装到C:\Program Files\Qt或其他带空格的路径✅ 正确做法装到C:\Qt或D:\Dev\Qt路径简单无空格 后果CMake 和某些构建工具会炸报错信息还特别迷 一句话记住路径别玩花活越简单越好3.3 安装过程验证安装完成先别急着关窗口我们简单验证一下打开命令行Windows 用 PowerShell 或 CMDLinux 用终端输入qmake --version或cmake --version如果能看到版本号输出说明 PATH 配置成功随堂测验口述回答用自己的话说说Qt Online Installer 里的「Desktop」组件是干什么的为什么 Windows 上有 MinGW 和 MSVC 两个版本(请先自己想一下再往下滑看答案)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━答案参考Desktop 组件是开发桌面应用的编译工具链和库MinGW 是基于 GCC 的 Windows 编译器开源免费MSVC 是微软的编译器与 Visual Studio 集成更好━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━4. Windows 专题4.1 编译器配置如果你选了 MinGW安装器会帮你顺带装好 MinGW 编译器基本不用额外配置。但如果你选了 MSVC你需要确保Visual Studio 2019/2022 已安装并且勾选了「使用 C 的桌面开发」工作负载Windows SDK 已安装在 VS Installer 里找到单个组件搜索「Windows SDK」选一个最新版装上⚠️坑 #3VS 没装对的症状❌ 错误做法只装了 VS 主体没勾选 C 工作负载✅ 正确做法打开 VS Installer → 修改 → 勾选「使用 C 的桌面开发」 后果CMake 找不到 cl.exe构建时一脸懵逼 一句话记住装 Qt ≠ 装了 C 编译器两码事4.2 环境变量验证Windows 下安装器一般会自动配 PATH但万一没配上右键「此电脑」→ 属性 → 高级系统设置 → 环境变量在 PATH 里添加C:\Qt\6.9.1\mingw_64\binMinGW 版本或C:\Qt\6.9.1\msvc2019_64\binMSVC 版本重启命令行窗口再试qmake --version随堂测验代码填空补全以下 Windows PowerShell 命令验证 Qt 环境是否配置正确# 验证 qmake 版本______# 验证 CMake 版本______--version# 验证 Qt 库路径假设装在 C:\Qtls______ *(提示第一行用 qmake 命令第二行用 cmake第三行是目录路径)* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **答案参考** powershell qmake --version cmake --version ls C:\Qt\6.9.1\mingw_64\bin ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━5. Linux 专题5.1 系统依赖安装Ubuntu/Debian 下Qt 依赖一堆系统库。先装这些sudoaptupdatesudoaptinstall-ybuild-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 安装器可能需要可执行权限chmodx qt-unified-linux-x64-online.run ./qt-unified-linux-x64-online.run⚠️坑 #4缺少 libxcb 导致的迷之报错❌ 错误做法看到缺库就装一个然后反复编译失败✅ 正确做法一次性装完上面那串依赖真的我都替你踩过了 后果程序启动就崩溃日志里只有 “Failed to load platform plugin” 一句话记住Linux Qt 缺库不是开玩笑的一次装齐省心随堂测验调试挑战以下命令有问题请问哪里错了会导致什么后果# 想要安装 Qt 构建依赖sudoaptinstallbuild-essential libgl1-mesa-dev# 然后直接运行 Qt 安装器./qt-unified-linux-x64-online.run ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **答案参考** - 问题缺少大量 X11 和 xcb 相关依赖 - 后果Qt 应用能编译但无法运行GUI会报 Could not connect to display 或 Failed to load platform plugin xcb ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## 6. WSL2 专题GUI 的正确打开方式 WSL2 现在已经支持 GUI 了WSLg但默认配置下你可能遇到显示问题。 ### 6.1 确认 WSLg 可用 在 WSL2 终端里运行 bash # 检查 WSL 版本 wsl.exe --version # 简单测试 GUI echo export DISPLAY:0 ~/.bashrc如果你的 Windows 11 版本够新Build 22000WSLg 应该是默认启用的。6.2 Qt 环境配置WSL2 下推荐直接用 Windows 版的 Qt这样不用在 Linux 里再装一遍。在~/.bashrc添加exportPATH/mnt/c/Qt/6.9.1/mingw_64/bin:$PATHexportQT_QPA_PLATFORMxcb但要注意这样运行的是 Windows 编译的 Qt 程序如果你想在 WSL2 里原生编译 Linux 版还是得按 Linux 篇的流程来。⚠️坑 #5WSL2 DISPLAY 设置错误❌ 错误做法随便设一个 DISPLAY 值或者用旧的 X Server 方案✅ 正确做法确认 WSLg 已启用直接运行就行 后果GUI 程序启动失败显示 “could not connect to display” 一句话记住Win11 WSL2 时代不用折腾 X Server 了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 找不到编译器。检查WindowsMSVC 或 MinGW 是否在 PATH 里Linuxwhich g有输出吗WSL2同 Linux7.3 安装器卡在 “Downloading”网络问题科学上网或者换国内镜像源。8. 最终验证安装完成我们来打个收尾Windows / Linux / WSL2 通用验证# 1. 检查 qmakeqmake--version# 2. 检查 CMakecmake--version# 3. 最重要的一步——创建测试工程mkdirqt-testcdqt-test cmake-DCMAKE_PREFIX_PATH/path/to/Qt/6.9.1/gcc_64..# Windows 路径示例-DCMAKE_PREFIX_PATHC:/Qt/6.9.1/mingw_64如果以上都能顺利跑通恭喜你环境搞定了接下来就可以正式写 Qt 代码了。9. 练习项目练习项目Hello Qt 环境验证功能描述创建一个最小化的 Qt 工程编译运行后弹出一个空窗口标题显示 “Qt is alive!”。这个项目的目的不是学 Qt API而是验证你的开发环境真的能跑起来。✅完成标准工程能用 CMake 成功配置编译无报错运行后能看到一个空白窗口标题显示正确。如果这一步都跑不通说明环境还有问题别着急往后学。提示新建一个文件夹里面放main.cpp和CMakeLists.txtCMakeLists.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 代码了。如果你在这一步遇到任何奇怪的问题别慌——我也遇到过大概率是路径或编译器的问题对着上面的坑检查一遍基本能解决。相关阅读深入理解Linux模块——第1章 Hello World内核模块内核编程的第一步 - 相似度 60%通用GUI编程技术——Win32 原生编程实战二十二——GDI 位图操作BitBlt、StretchBlt 与图像处理 - 相似度 20%