Linux 安装 Qt 开发环境完整教程（Ubuntu
Linux 安装 Qt 开发环境完整教程（Ubuntu）
本文记录在 Ubuntu 环境下搭建 Qt C++ 开发环境的完整过程。
从 Qt 安装、Qt Creator 配置，到 CMake、环境变量配置，以及安装过程中遇到的问题解决。
最终实现：
- Qt Creator 正常运行
- Qt Widgets 项目可以编译运行
- CMake 正常构建
- Vim + Qt 项目开发
1. 环境介绍
本文使用环境：
系统：
Ubuntu Desktop
编译器：
gcc / g++
Qt版本：
Qt 6.11.2
构建工具：
CMake + Ninja
IDE：
Qt Creator
编辑器：
Vim
Qt 官方现在更加推荐：
CMake + Qt Creator
而不是传统的 qmake。
因此本文主要使用 CMake。
2. 安装前准备
2.1 更新软件源
打开终端：
sudo apt update
sudo apt upgrade
2.2 安装基础开发工具
安装 gcc、g++、cmake 等：
sudo apt install build-essential cmake ninja-build
查看版本：
gcc：
gcc --version
g++：
g++ --version
cmake：
cmake --version
注意：
CMake 查看版本使用：
cmake --version
不是：
cmake -v
因为 CMake 不支持 -v 参数。
3. 下载 Qt
进入 Qt 官网：
https://www.qt.io/download-open-source
下载：
Qt Online Installer
Linux版本：
qt-online-installer-linux-x64
4. 安装 Qt
给安装程序执行权限：
chmod +x qt-online-installer-linux-x64.run
运行：
./qt-online-installer-linux-x64.run
4.1 登录 Qt Account
安装过程中需要：
Qt Account
登录。
如果网络连接失败：
可以使用国内镜像：
例如：
https://mirrors.ustc.edu.cn/qtproject
运行：
./MaintenanceTool --mirror https://mirrors.ustc.edu.cn/qtproject
5. Qt组件选择
安装时选择：
Qt
Qt 6.11.2
Desktop gcc_64
也就是：
Qt 6.11.2 Desktop
不要选择：
- Android
- WebAssembly
除非有对应需求。
同时安装：
Developer Tools
Qt Creator
安装完成后目录类似：
~/Qt
├── 6.11.2
│ └── gcc_64
│
└── Tools
└── QtCreator
6. 安装 OpenGL 开发环境（重要）
Ubuntu 默认可能缺少 Qt 所需的 OpenGL 开发库。
如果 CMake 出现：
Could NOT find OpenGL
Qt6Gui could not be found
Qt6Widgets could not be found
不要急着重新安装 Qt。
原因通常是：
OpenGL缺失
↓
QtGui失败
↓
QtWidgets失败
↓
CMake配置失败
解决：
sudo apt install libgl1-mesa-dev libopengl-dev
安装完成后重新配置 CMake。
7. 打开 Qt Creator
Qt Creator 默认不会加入 PATH。
可以直接运行：
~/Qt/Tools/QtCreator/bin/qtcreator
或者配置环境变量。
8. 配置环境变量
编辑：
vim ~/.bashrc
加入：
export PATH=$PATH:$HOME/Qt/Tools/QtCreator/bin
export PATH=$PATH:$HOME/Qt/6.11.2/gcc_64/bin
保存。
刷新：
source ~/.bashrc
测试：
Qt Creator
qtcreator
qmake
qmake -v
输出：
QMake version 3.1
Using Qt version 6.11.2
说明成功。
CMake
查看：
cmake --version
9. 创建第一个 Qt 项目
打开 Qt Creator：
File
→ New Project
→ Qt Widgets Application
→ CMake
→ Desktop Qt 6.11.2
生成：
project
├── CMakeLists.txt
├── main.cpp
├── mainwindow.cpp
├── mainwindow.h
└── mainwindow.ui
点击：
Run
出现窗口：
Hello World
说明环境搭建完成。
10. Qt项目为什么不能直接写一个cpp？
很多初学者会直接：
vim main.cpp
然后：
#include <QApplication>
但是无法编译。
原因：
Qt程序不仅需要源码，还需要：
- Qt头文件路径
- Qt库链接
- moc处理
- CMake配置
例如：
main.cpp
|
|
CMakeLists.txt
|
|
Qt Core
Qt Gui
Qt Widgets
所以正确流程：
Qt Creator创建项目
↓
Vim修改代码
↓
CMake编译
11. 使用Vim开发Qt项目
推荐：
Qt Creator负责：
- 创建项目
- CMake配置
- 调试
Vim负责：
- 编写代码
- 快速修改
进入项目：
cd 项目目录
打开：
vim main.cpp
修改后：
回到 Qt Creator：
重新构建即可。
12. CMake常见配置
Qt项目中的：
find_package(Qt6 REQUIRED COMPONENTS Core Widgets)
表示寻找：
Qt Core
Qt Widgets
链接：
target_link_libraries(
project
Qt6::Core
Qt6::Widgets
)
如果 CMake 找不到 Qt：
可以设置：
CMAKE_PREFIX_PATH
例如：
/home/yuyang/Qt/6.11.2/gcc_64
它会自动寻找：
lib/cmake/Qt6
13. 常见问题总结
13.1 qtcreator 找不到
错误：
command qtcreator not found
原因：
没有加入 PATH。
解决：
export PATH=$PATH:$HOME/Qt/Tools/QtCreator/bin
13.2 qmake找不到
解决：
export PATH=$PATH:$HOME/Qt/6.11.2/gcc_64/bin
13.3 Qt6Widgets找不到
错误：
Could NOT find Qt6Widgets
不要直接重装Qt。
检查：
sudo apt install libgl1-mesa-dev libopengl-dev
13.4 Wayland提示
启动Qt Creator：
出现：
Ignoring WAYLAND_DISPLAY
这是 Ubuntu GNOME + Wayland 的提示。
一般不影响开发。
如果想使用X11：
export QT_QPA_PLATFORM=xcb
14. 最终环境检查
执行：
qtcreator
成功打开。
执行：
qmake -v
输出Qt版本。
执行：
cmake --version
输出CMake版本。
Qt项目：
创建成功
编译成功
运行成功
总结
Linux 下 Qt 开发环境搭建核心就是：
gcc/g++
+
Qt
+
Qt Creator
+
CMake
+
OpenGL开发库
推荐开发流程：
Qt Creator 创建项目
↓
Vim 编写代码
↓
CMake 构建
↓
运行程序
配置完成后，Linux 下的 Qt 开发体验与 Windows 基本一致，同时更加接近真实工程开发环境。
浙公网安备 33010602011771号