在 Ubuntu 下搭建 qt 环境和安装 Qt Creator听起来就是把一个安装包拖进去点下一步的事实际上我在三个不同版本的 Ubuntu 上都做过每次都能遇到新问题要么 Qt Creator 打开后提示 no suitable kit要么项目编译到一半报一堆 xcb 错误还有一次是 qmake 装好了终端里却还是旧版本。后来把所有步骤按顺序整理清楚才发现大部分失败都出在“跳过了准备动作”和“装完没做验证”上。这篇文章就是一份完整到“照做就能跑通”的 Ubuntu Qt 搭建记录适合刚接触 Linux 想写 Qt 程序的人也适合被版本和环境变量折腾过、想彻底理清思路的老手。1. 一次成功的前提先把环境组成拆清楚别把Qt Creator当成全部很多新手以为装 Qt 就是装一个 Qt Creator装了它就有了开发环境然后一打开新建项目发现它让你选 Kit选的时候又说找不到 qmake 和编译器当场卡住。其实 Qt Creator 只是一个外壳真正干活的是下面这一套东西。1.1 环境里到底有哪几样东西各自负责什么先记住一个结论Qt Creator 不是 Qt 环境Qt 环境是一套各司其职的工具链。用一张表说明组件角色常见品牌/实现IDE写代码、调试、项目管理Qt Creator、VS CodeQt 库界面和功能框架Qt5、Qt6编译器把 C 源码变成可执行文件gcc/g、clang构建工具根据 .pro 或 CMakeLists 生成 Makefileqmake、CMake调试器断点、变量查看gdb如果在安装 Qt Creator 前没装编译器和 Qt 库Qt Creator 打开后就会提示缺少编译器或者找不到 qmake。这就像你买回来一个厨房锅碗瓢盆都齐全但是没有燃气灶和食材一样做不了饭。这个比喻可以再延伸一下Qt 库就是菜谱和食材gcc/g 是燃气灶qmake/CMake 是帮厨Qt Creator 是那个做饭的人。缺任何一个环节端上桌的都不可能是完整的 Qt 程序。为什么要区分得这么清楚因为后面排查问题时你需要知道报错来自哪一层。比如编译时报g: command not found问题出在编译器运行时报Could not load the Qt platform plugin xcb问题出在 Qt 库的图形依赖Qt Creator 里显示 kit 无效那就要去检查工具链和 qmake 的路径配置。分清楚层次你才能对症下药。1.2 Ubuntu版本与Qt版本怎么搭配选择哪个 Qt 版本首先要看你用什么 Ubuntu。Ubuntu 20.04 软件源里的 Qt 是 5.12.8很稳定但功能有点老。Ubuntu 22.04 默认提供 Qt 5.15.3属于 Qt5 系列的长期维护版本作为日常开发基本够用。Ubuntu 24.04 已经全面转向 Qt6软件源里有 qt6-base-dev同时也保留了 Qt5 的兼容包。我的建议很简单如果你只是刚起步、想先跑通环境优先用apt装系统自带版本省心如果项目依赖某一个具体的 Qt 版本比如必须 5.15.2 或者 6.5.3再用官方在线安装器装独立版本至于离线安装包适合没有 Qt 账号或者网络不稳定的场景。这里还要考虑项目类型。如果你写的是传统界面程序用 Qt Widgets那 Qt5 和 Qt6 的差别不算大挑一个稳定的系统版本就行。如果你要写 QML 或 Qt Quick我建议优先 Qt 6因为 QML 引擎在 Qt6 里有大量更成熟的特性而且新教程普遍以 Qt6 为主。反过来如果你正在跟一本老书或者一套老项目学里面的接口还是 Qt5 风格坚持用 Qt5 反而更顺不用一边改代码一边学环境。提示同一台机器上apt 版本和官方安装器版本可以共存但要注意环境变量和 qmake 指向这在第 6 章会专门讲。2. 安装前的三个准备动作直接影响后面能否一次跑通我踩过的最大的坑是装完 Qt Creator 之后发现系统里根本缺了一堆依赖导致安装器界面都起不来。所以无论你选哪种安装方式下面的准备动作都不能跳。2.1 换一个更快的软件源Ubuntu 默认的软件源服务器在国外安装大依赖时经常因为网络慢导致中断而依赖一旦没装全后面 Qt 编译时的报错非常难查。所以我习惯先把软件源换成一个速度快的公共镜像。以 Ubuntu 22.04 为例配置文件是/etc/apt/sources.list# 先备份后悔的时候有退路 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak # 把官方源替换为公共镜像源 sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update如果是 Ubuntu 24.04配置文件换成了/etc/apt/sources.list.d/ubuntu.sources操作思路一样打开文件后把URIs: http://archive.ubuntu.com/ubuntu一行里的域名替换成mirrors.aliyun.com即可。换源后运行sudo apt update确保列表刷新成功。这一步能省去后面 80% 的“下载依赖超时”问题。个人实测在同样网络条件下换源后安装 Qt 全家桶的时间至少能缩短一半尤其装libicu-dev这类体积较大的包时几乎不会因为断流而中断。2.2 把编译和运行依赖一次补齐Qt 程序不是纯命令行程序依赖很多图形库而且需要通过编译器编译源码所以下面这些包最好安装前一次装齐sudo apt update sudo apt install -y build-essential gdb make cmake \ libgl1-mesa-dev libfontconfig1-dev libfreetype6-dev \ libx11-dev libxkbcommon-x11-0 libxkbcommon-dev \ libxcb1-dev libxcb-util0-dev libxcb-icccm4-dev \ libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev \ libxcb-randr0-dev libxcb-xinerama0-dev libxcb-xfixes0-dev \ libxcb-cursor0 libdbus-1-dev libssl-dev libicu-dev这些包分别解决什么问题简单说build-essential包含 gcc、g、make是编译 C/C 程序的基座。libgl1-mesa-devOpenGL 开发库Qt 的很多窗口渲染都依赖它。libfontconfig1-dev、libfreetype6-dev字体渲染Qt 界面文字显示用的。libxcb-*系列X11 协议相关的 C 库Qt5 和 Qt6 的 xcb 插件依赖的就是这一组。libicu-devUnicode 和国际化支持。如果以后要做多语言界面这个库尤其重要。libssl-dev、libdbus-1-dev网络和桌面消息总线相关的开发头文件很多 Qt 模块会间接引用它们。注意这些包名字在不同 Ubuntu 版本里略有差异比如很老的版本里libxcb-util0-dev叫libxcb-util-dev如果遇到“无法定位软件包”的提示先执行apt search libxcb查找正确包名。2.3 磁盘空间、系统位数和基础图形栈的确认安装 Qt 全家桶前还要确认三件事。一是磁盘空间。Qt 5 加上 Qt Creator 大概需要 5~8 GBQt 6 多个模块装全甚至超过 10 GB。用df -h看一下根目录或主目录所在分区建议至少留 20 GB 可用空间再动手。我见过有人在只剩 2 GB 的小分区上直接装结果安装器写到一半磁盘满整个环境进入半残状态被迫重来。二是系统架构。uname -m输出x86_64表示 64 位系统下载 Qt 安装包时选 x86_64 / linux_x64 版本如果输出aarch64那就是 ARM 架构不能直接装普通 x64 安装包要选官方提供的 ARM 版本。三是图形环境类型。运行echo $XDG_SESSION_TYPE如果显示x11Qt 的 xcb 插件必须装好如果显示wayland则还需要qtwayland5或qt6-wayland这个模块否则部分 Qt 程序可能无法弹出窗口。如果你是在 WSL2 里跑 Ubuntu软件包的安装逻辑与真实 Ubuntu 一致但 Qt Creator 属于 GUI 程序需要 WSLg 或者外部 X Server 支持否则即使环境变量全对也起不来窗口这一点与真实 Ubuntu 桌面场景不同。3. 新手最稳的apt安装路线系统和软件源维护方帮你兜底如果你还在犹豫选哪个 Qt 版本我建议第一条路线直接用 apt 安装因为这是操作系统发行版维护的版本依赖关系处理得最好装完基本不会有玄学问题。3.1 终端命令三步完成安装在终端里依次执行sudo apt update sudo apt install -y qtbase5-dev qt5-qmake qtbase5-dev-tools qttools5-dev-tools qtcreator这里每个包的角色是qtbase5-devQt5 的核心开发包包含头文件、静态库和默认配置属于必装。qt5-qmakeQt5 的构建工具 qmake。没有它命令行下无法生成 Makefile。qtbase5-dev-tools包括 moc、uic、rcc 等工具Qt 项目的元对象编译全靠它们。qttools5-dev-tools一些辅助工具比如国际化用的 lupdate/lrelease。qtcreatorQt 官方 IDE也就是可视化开发界面。如果你想用 Qt6可以换成sudo apt install -y qt6-base-dev qt6-declarative-dev qt6-tools-dev-tools qtcreator但注意 20.04 和 22.04 默认仓库里的 Qt6 版本比较有限建议先apt search qt6-base-dev确认是否可用。在 Ubuntu 24.04 上qt6-base-dev就在主仓库里装起来会更顺畅。3.2 安装完如何验证以及这种方式的局限装完不要着急写代码先跑三个验证命令gcc --version qmake --version which qtcreatorqmake --version应该能看到类似QMake version 3.1, Using Qt version 5.15.3的输出。如果出现qmake: command not found说明qt5-qmake没装上用apt install qt5-qmake补装。apt 这条路线的优点非常明显省心。Qt 库自动安装到系统目录qmake 在/usr/bin/qmakeQt Creator 也在系统 PATH 里不需要配任何环境变量CMake 项目也能自动找到 Qt。而且在 Qt Creator 新建项目时套件选择页通常会直接识别出可用的 Desktop 套件不用手动指定编译器路径对新手极其友好。局限性也明显版本跟 Ubuntu 发布时绑定。比如 20.04 只能用 Qt 5.12.8无法直接用 apt 升级到 5.15此外一些新模块如 Qt Charts、Qt Data Visualization 需要额外安装或者根本不在仓库里。如果项目要求指定版本或者你需要某些仓库里没有的模块那就看下一章的官方在线安装器。4. 指定版本需求官方在线安装器的操作细节和组件取舍当项目要求“必须在 Qt 5.15.2 上开发”或者你想第一时间用上 Qt6 的新特性apt 路线就不够用了。这时候需要 Qt 官方在线安装器它最大的优势是可以同时装多个版本互不干扰也方便以后用维护工具增删组件。4.1 下载与启动安装器的准备工作先去 Qt 官网的下载页找到 Linux 版在线安装器文件名通常是qt-unified-linux-x64-online.run。下载完成后先赋执行权限chmod x qt-unified-linux-x64-online.run ./qt-unified-linux-x64-online.run如果双击没有任何反应多半是缺了图形库。回到第 2 章把那些依赖装齐再在终端里启动安装器终端会打印具体缺哪个.so文件缺什么补什么。启动后有一步登录 Qt 账号。开源用户用邮箱免费注册一个就行登录后选择开源版本使用渠道即可正常安装。这一步很多人会卡住其实不用有心理负担用个人邮箱注册即可不涉及付费选项。如果你完全不想注册账号可以跳到第 5 章看离线安装包方案。4.2 组件选择的黄金原则和推荐清单在线安装器会列出一棵巨大的组件树很多新手看到那么多模块直接全选结果磁盘爆了、安装时间超长或者反而漏掉了最关键的编译套件。我的原则是主版本下的编译器套件必选模块按需选Sources 基本可以不选。以安装 Qt 5.15.2 为例推荐勾选的内容如下Qt 5.15.2下的Desktop gcc 64-bit这是必选项它决定了/opt/Qt/5.15.2/gcc_64这个目录里面才包含 qmake 和 Qt 库。Developer and Designer Tools下的Qt Creator如果系统里没有装过 Qt Creator这里要勾上。Qt Debug Information Files需要深入查看 Qt 源码堆栈时再勾体积大一般调试用不上。各种附加模块如 Qt Charts、Qt WebEngine、Qt Network Authorization按项目实际需要勾选没必要全选。组件选好后安装器会让你确认安装路径默认是/opt/Qt。我的个人建议是如果这台机器完全归你自己用把路径改成~/Qt或/home/你的用户名/Qt这样后面创建项目和使用维护工具都不会遇到权限问题。如果装到/opt/Qt安装完成后需要额外执行一次sudo chown -R $USER:$USER /opt/Qt把目录归属从 root 改成当前用户否则 Qt Creator 在项目目录生成文件时会报权限错误。4.3 安装完成后验证和目录结构安装完成后检查目录结构ls /opt/Qt/5.15.2/gcc_64/bin/qmake /opt/Qt/5.15.2/gcc_64/bin/qmake -v同时/opt/Qt/Tools/QtCreator/bin/qtcreator是 Qt Creator 的启动入口。启动后在Tools → Options → Kits → Qt Versions里能看到安装器自动识别出来的 Qt 5.15.2qmake 路径指向/opt/Qt/5.15.2/gcc_64/bin/qmake。有一点要注意在线安装器不会自动把它的 qmake 加入系统的/usr/bin所以终端里直接敲qmake -v用的可能还是当初 apt 装的版本。想让终端默认使用官方安装器的版本要么用全路径要么修改 PATH这在第 6 章统一处理。5. 离线安装包没账号也能装特定Qt版本附权限处理有些同学不想注册 Qt 账号或者公司的网络环境不允许在线安装器长时间下载这时候离线安装包是最合适的。它把某个固定版本的所有组件打包好安装时不需要联网拉包速度比在线安装快得多。5.1 离线包获取与授权Qt 官方以及一些知名的软件镜像站都提供了离线安装包文件名类似qt-opensource-linux-x64-5.14.2.run。这里提醒一句.run文件是直接执行的来源一定要可靠。认准 Qt 官方域名或者你平时就信任的软件镜像站不要随便下载某个不知名博客挂出来的链接。拿到.run文件后先赋权限chmod x qt-opensource-linux-x64-5.14.2.run ./qt-opensource-linux-x64-5.14.2.run这里我特别提醒老版本的离线安装器在较新的 Ubuntu 上经常打不开报错大概率是缺少 xcb 系列库或者图形依赖。遇到这种情况先补这一组sudo apt install -y libxcb-cursor0 libxkbcommon-x11-0 libglu1-mesa-dev如果还不行执行安装器时加一个环境变量QT_QPA_PLATFORMoffscreen ./qt-opensource-linux-x64-5.14.2.run这个变量会让安装程序以无窗口模式运行虽然界面可能不显示但安装向导流程仍然可以走是个应急方案。不建议一上来就加这个变量因为无窗口模式下你看不到组件勾选界面容易漏选。5.2 装到 /opt 之后的两个隐藏问题离线安装包默认也把 Qt 装到/opt/Qt这里有两个新手必踩的坑。坑一是权限。安装过程用 root 权限写入了/opt/Qt之后你再用普通用户打开 Qt Creator在项目设置里切换 Kit 或者给 Qt 目录添加新组件时会提示Permission denied。解决办法是把 Qt 目录的所有者改回当前用户sudo chown -R $USER:$USER /opt/Qt坑二是维护工具。离线安装器会生成一个MaintenanceTool位于安装根目录千万别手痒把整个 Qt 目录手动删了。之后要增删组件、修复安装、卸载都要用它。正确操作是运行MaintenanceTool登录后选择添加或移除组件。手动删除目录会导致维护工具失效下次想装补丁只能从头再来。还有一个容易忽略的点不同的离线安装包对 Qt Creator 的处理方式不一样。有的包把 Qt 库和 Qt Creator 都包含在里面有的纯库版本不带 IDE。如果你装完发现系统里没有 Qt Creator直接sudo apt install qtcreator补一个就行IDE 版本不一定要和 Qt 库版本完全一致只要 Kit 里指定了正确的 qmake就能配套使用。6. 环境变量和Kit设置安装成功后最常见的翻车点环境装好了接下来最让人头大的就是“明明装了却找不到”“明明能找到却版本不对”。这一章把所有常见翻车点一次说清。6.1 qmake和PATH为什么会错位如果你同时用了 apt 安装和官方安装器或者装过多个 Qt 版本终端里执行qmake -v显示的很可能不是你想要的版本。因为qmake这个命令是按照 PATH 环境变量依次查找的/usr/bin/如果在/opt/Qt/5.15.2/gcc_64/bin前面找到的就是 apt 版本。解决思路很简单让系统优先找到目标版本。临时切换export PATH/opt/Qt/5.15.2/gcc_64/bin:$PATH qmake -v这样只对当前终端有效。想永久生效把这一行追加到~/.bashrcecho export PATH/opt/Qt/5.15.2/gcc_64/bin:$PATH ~/.bashrc source ~/.bashrcUbuntu 还提供了一个更优雅的工具qtchooser专门用于管理多个 qmake 版本qtchooser -l # 用别名选择 export QT_SELECT5.15.2 qmake -v我的经验是在终端里用 qmake 命令行时用绝对路径最保险在 Qt Creator 里写代码时直接在 Kit 里指定 qmake 路径不依赖终端 PATH。这样两边互不干扰能省掉很多“为什么终端对了、IDE 错了”的烦恼。6.2 CMake项目找不到Qt库的标准解法另一个高频报错是CMake Error at CMakeLists.txt:16 (find_package): Could not find a package configuration file named Qt5Widgets这个问题的本质是CMake 不知道 Qt 的头文件和库文件放在哪里。对于 apt 安装Qt 在系统目录/usr/libCMake 默认能找到对于官方安装器安装的独立版本Qt 在/opt/Qt/5.15.2/gcc_64必须显式告诉 CMake。命令行构建时这样处理cmake -DCMAKE_PREFIX_PATH/opt/Qt/5.15.2/gcc_64 ..在 Qt Creator 里打开项目后进入Projects → Build → CMake → Configuration点Add把CMAKE_PREFIX_PATH加进去。另一种办法是在CMakeLists.txt顶部直接写set(CMAKE_PREFIX_PATH /opt/Qt/5.15.2/gcc_64 CACHE STRING Qt path)这个办法适合固定开发机但团队协作时会覆盖别人本机的路径所以我更推荐在 Qt Creator 的 CMake 配置里单独设置而不是写死在项目文件里。7. 跑通第一个程序从命令行到Qt Creator再到运行报错排查环境配好之后别急着用 IDE先在命令行写一个最小的 Qt 程序把链路彻底跑通。这样一旦后面出问题你能立刻判断是 Qt 库的问题还是 Qt Creator 的问题。7.1 命令行三步法验证纯Qt环境在英文目录下创建hello.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello Qt on Ubuntu); label.resize(320, 120); label.show(); return app.exec(); }然后三步走qmake -project qmake make ./helloqmake -project会扫描当前目录生成一个.pro文件qmake根据.pro生成Makefilemake负责调用 g 完成编译。如果hello窗口弹出来说明 Qt 库、编译器和 qmake 三者都正常问题只可能出现在 Qt Creator 的配置上。这里有个小坑项目目录名尽量不要带中文和空格qmake -project对特殊字符的处理并不稳定。我第一次用中文目录名生成.pro结果 Makefile 里的路径全是乱码编译直接失败。换成~hello_demo这样简单的英文目录一次性就过了。7.2 Qt Creator新建项目的Kit选择从终端启动 Qt Creatorqtcreator或者直接点击应用图标。然后File → New Project → Application → Qt Widgets Application在 Kit 选择页会看到类似Desktop Qt 5.15.2 GCC 64bit的选项。如果这个 Kit 前面是红色感叹号说明 Kit 里某个环节没配置好。到Tools → Options → Kits检查Compilers标签页里是否已有GCC / C和GCC / C没有就手动添加/usr/bin/gcc、/usr/bin/g。Qt Versions标签页里是否已有 qmake 路径手动添加/opt/Qt/5.15.2/gcc_64/bin/qmake。Kits标签页新建一个 Desktop 套件把上面两个元素分别选上。Debugger选/usr/bin/gdb。全部配好后Kit 不再显示警告。之后编译项目时如果报 “could not find or load the Qt platform plugin”直接看下一节。7.3 运行时报xcb、GL类错误的排查顺序Qt 程序在 Linux 桌面端最经典的两个运行报错一个是 xcb一个是 OpenGL。xcb 报错长这样qt.qpa.plugin: Could not load the Qt platform plugin xcb in even though it was found.出现这个说明 Qt 的 xcb 平台插件libqxcb.so在加载时缺了依赖。排查顺序固定为三步第一步安装常见 xcb 补丁库sudo apt install -y libxcb-xinerama0 libxcb-cursor0 libxcb-icccm4 \ libxcb-keysyms1 libxcb-image0 libxcb-shm0 libxcb-render-util0第二步如果还不行用ldd查 qxcb 插件缺什么ldd /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not foundldd会列出它依赖的所有动态库标注not found的就是缺的包。然后根据包名apt search安装对应库。第三步检查QT_QPA_PLATFORM环境变量。默认情况下不要设置它让 Qt 自动选择 xcb乱设置成wayland会导致部分环境下无法启动。GL 报错通常是qt.qpa.gl: Could not initialize OpenGL在虚拟机和远程桌面里最常见。如果你是在 VMware 虚拟机的 Ubuntu 里跑 Qt先到虚拟机设置里开启 3D 加速再装libgl1-mesa-dev。临时想验证是不是缺少 GPU 加速可以先用软件渲染export QT_OPENGLsoftware ./hello能跑通说明真实环境缺少图形加速支持。换用 Xorg 会话或给虚拟机开启 3D 加速后问题基本消失。8. 装好之后值得做的几件事输入法、主题和日常开发体验环境跑通只是开始。真正在 Ubuntu 上用 Qt 写项目还有一些“装完才发现少了点什么”的小事提前处理能省很多心。8.1 中文输入法在Qt程序里打不出字的处理很多人在 Ubuntu 上装好搜狗输入法或 fcitx浏览器和编辑器里都能打中文一进 Qt Creator 或者自己写的 Qt 程序中文就打不进去了。原因很简单Qt 没有对应的输入法插件。如果是 fcitx 方案执行sudo apt install -y fcitx fcitx-frontend-qt5然后在/etc/environment里追加三行QT_IM_MODULEfcitx GTK_IM_MODULEfcitx XMODIFIERSimfcitx重启系统后生效。注意fcitx和ibus两套输入法框架不要同时开否则会和 Qt 的输入法插件互相抢解决了一个旧问题又冒出两个新问题。另外如果你想在 Ubuntu 上用合适的字体写代码我建议在 Qt Creator 的编辑器设置里换成等宽字体比如Source Code Pro或JetBrains Mono长时间盯代码会舒服不少。8.2 让Qt Creator更顺手的零散设置最后分享几个我每次装完 Qt Creator 都会立刻调整的选项。字体方面在Tools → Options → Environment → Font Colors里改等宽字体看代码更清晰。主题方面Qt Creator 支持深色模式在Environment → Theme里选Flat Dark长时间盯屏幕没那么累。快捷键方面可以到Environment → Keyboard里按自己的习惯调整比如我习惯把“查找符号”绑定到 CtrlShiftF。构建方面保持 Shadow Build 默认开启它会把编译产物放到底下的build-项目名-Desktop_Qt_5_15_2_GCC_64bit-Debug目录不会污染源码目录。很多新手看到项目目录里一堆 Makefile 和 .o 文件以为出了问题其实只是没开 Shadow Build。还有一个小技巧Qt Creator 的配置都保存在~/.config/QtProject目录重装系统之前把这个目录备份一下新机器装好 Qt Creator 后直接放回去主题、快捷键、代码风格全回来了。包括之前说的环境变量、依赖安装命令我习惯把它们整理成一个setup_qt.sh脚本存到自己的配置目录里。重装系统后跑一遍脚本基本十分钟就能恢复原来的 Qt 开发环境。装环境这种事情最怕的就是临时去网上翻一条命令复制一条顺序一乱报错就跟着来了。先把准备动作做好后面每一步都是顺水推舟。 
长河君 · 2026/10/3 7:58:23 · 阅读 1.2k Ubuntu下搭建Qt开发环境完整指南：从apt到官方安装器一次搞定
在 Ubuntu 下搭建 qt 环境和安装 Qt Creator听起来就是把一个安装包拖进去点下一步的事实际上我在三个不同版本的 Ubuntu 上都做过每次都能遇到新问题要么 Qt Creator 打开后提示 no suitable kit要么项目编译到一半报一堆 xcb 错误还有一次是 qmake 装好了终端里却还是旧版本。后来把所有步骤按顺序整理清楚才发现大部分失败都出在“跳过了准备动作”和“装完没做验证”上。这篇文章就是一份完整到“照做就能跑通”的 Ubuntu Qt 搭建记录适合刚接触 Linux 想写 Qt 程序的人也适合被版本和环境变量折腾过、想彻底理清思路的老手。1. 一次成功的前提先把环境组成拆清楚别把Qt Creator当成全部很多新手以为装 Qt 就是装一个 Qt Creator装了它就有了开发环境然后一打开新建项目发现它让你选 Kit选的时候又说找不到 qmake 和编译器当场卡住。其实 Qt Creator 只是一个外壳真正干活的是下面这一套东西。1.1 环境里到底有哪几样东西各自负责什么先记住一个结论Qt Creator 不是 Qt 环境Qt 环境是一套各司其职的工具链。用一张表说明组件角色常见品牌/实现IDE写代码、调试、项目管理Qt Creator、VS CodeQt 库界面和功能框架Qt5、Qt6编译器把 C 源码变成可执行文件gcc/g、clang构建工具根据 .pro 或 CMakeLists 生成 Makefileqmake、CMake调试器断点、变量查看gdb如果在安装 Qt Creator 前没装编译器和 Qt 库Qt Creator 打开后就会提示缺少编译器或者找不到 qmake。这就像你买回来一个厨房锅碗瓢盆都齐全但是没有燃气灶和食材一样做不了饭。这个比喻可以再延伸一下Qt 库就是菜谱和食材gcc/g 是燃气灶qmake/CMake 是帮厨Qt Creator 是那个做饭的人。缺任何一个环节端上桌的都不可能是完整的 Qt 程序。为什么要区分得这么清楚因为后面排查问题时你需要知道报错来自哪一层。比如编译时报g: command not found问题出在编译器运行时报Could not load the Qt platform plugin xcb问题出在 Qt 库的图形依赖Qt Creator 里显示 kit 无效那就要去检查工具链和 qmake 的路径配置。分清楚层次你才能对症下药。1.2 Ubuntu版本与Qt版本怎么搭配选择哪个 Qt 版本首先要看你用什么 Ubuntu。Ubuntu 20.04 软件源里的 Qt 是 5.12.8很稳定但功能有点老。Ubuntu 22.04 默认提供 Qt 5.15.3属于 Qt5 系列的长期维护版本作为日常开发基本够用。Ubuntu 24.04 已经全面转向 Qt6软件源里有 qt6-base-dev同时也保留了 Qt5 的兼容包。我的建议很简单如果你只是刚起步、想先跑通环境优先用apt装系统自带版本省心如果项目依赖某一个具体的 Qt 版本比如必须 5.15.2 或者 6.5.3再用官方在线安装器装独立版本至于离线安装包适合没有 Qt 账号或者网络不稳定的场景。这里还要考虑项目类型。如果你写的是传统界面程序用 Qt Widgets那 Qt5 和 Qt6 的差别不算大挑一个稳定的系统版本就行。如果你要写 QML 或 Qt Quick我建议优先 Qt 6因为 QML 引擎在 Qt6 里有大量更成熟的特性而且新教程普遍以 Qt6 为主。反过来如果你正在跟一本老书或者一套老项目学里面的接口还是 Qt5 风格坚持用 Qt5 反而更顺不用一边改代码一边学环境。提示同一台机器上apt 版本和官方安装器版本可以共存但要注意环境变量和 qmake 指向这在第 6 章会专门讲。2. 安装前的三个准备动作直接影响后面能否一次跑通我踩过的最大的坑是装完 Qt Creator 之后发现系统里根本缺了一堆依赖导致安装器界面都起不来。所以无论你选哪种安装方式下面的准备动作都不能跳。2.1 换一个更快的软件源Ubuntu 默认的软件源服务器在国外安装大依赖时经常因为网络慢导致中断而依赖一旦没装全后面 Qt 编译时的报错非常难查。所以我习惯先把软件源换成一个速度快的公共镜像。以 Ubuntu 22.04 为例配置文件是/etc/apt/sources.list# 先备份后悔的时候有退路 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak # 把官方源替换为公共镜像源 sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update如果是 Ubuntu 24.04配置文件换成了/etc/apt/sources.list.d/ubuntu.sources操作思路一样打开文件后把URIs: http://archive.ubuntu.com/ubuntu一行里的域名替换成mirrors.aliyun.com即可。换源后运行sudo apt update确保列表刷新成功。这一步能省去后面 80% 的“下载依赖超时”问题。个人实测在同样网络条件下换源后安装 Qt 全家桶的时间至少能缩短一半尤其装libicu-dev这类体积较大的包时几乎不会因为断流而中断。2.2 把编译和运行依赖一次补齐Qt 程序不是纯命令行程序依赖很多图形库而且需要通过编译器编译源码所以下面这些包最好安装前一次装齐sudo apt update sudo apt install -y build-essential gdb make cmake \ libgl1-mesa-dev libfontconfig1-dev libfreetype6-dev \ libx11-dev libxkbcommon-x11-0 libxkbcommon-dev \ libxcb1-dev libxcb-util0-dev libxcb-icccm4-dev \ libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev \ libxcb-randr0-dev libxcb-xinerama0-dev libxcb-xfixes0-dev \ libxcb-cursor0 libdbus-1-dev libssl-dev libicu-dev这些包分别解决什么问题简单说build-essential包含 gcc、g、make是编译 C/C 程序的基座。libgl1-mesa-devOpenGL 开发库Qt 的很多窗口渲染都依赖它。libfontconfig1-dev、libfreetype6-dev字体渲染Qt 界面文字显示用的。libxcb-*系列X11 协议相关的 C 库Qt5 和 Qt6 的 xcb 插件依赖的就是这一组。libicu-devUnicode 和国际化支持。如果以后要做多语言界面这个库尤其重要。libssl-dev、libdbus-1-dev网络和桌面消息总线相关的开发头文件很多 Qt 模块会间接引用它们。注意这些包名字在不同 Ubuntu 版本里略有差异比如很老的版本里libxcb-util0-dev叫libxcb-util-dev如果遇到“无法定位软件包”的提示先执行apt search libxcb查找正确包名。2.3 磁盘空间、系统位数和基础图形栈的确认安装 Qt 全家桶前还要确认三件事。一是磁盘空间。Qt 5 加上 Qt Creator 大概需要 5~8 GBQt 6 多个模块装全甚至超过 10 GB。用df -h看一下根目录或主目录所在分区建议至少留 20 GB 可用空间再动手。我见过有人在只剩 2 GB 的小分区上直接装结果安装器写到一半磁盘满整个环境进入半残状态被迫重来。二是系统架构。uname -m输出x86_64表示 64 位系统下载 Qt 安装包时选 x86_64 / linux_x64 版本如果输出aarch64那就是 ARM 架构不能直接装普通 x64 安装包要选官方提供的 ARM 版本。三是图形环境类型。运行echo $XDG_SESSION_TYPE如果显示x11Qt 的 xcb 插件必须装好如果显示wayland则还需要qtwayland5或qt6-wayland这个模块否则部分 Qt 程序可能无法弹出窗口。如果你是在 WSL2 里跑 Ubuntu软件包的安装逻辑与真实 Ubuntu 一致但 Qt Creator 属于 GUI 程序需要 WSLg 或者外部 X Server 支持否则即使环境变量全对也起不来窗口这一点与真实 Ubuntu 桌面场景不同。3. 新手最稳的apt安装路线系统和软件源维护方帮你兜底如果你还在犹豫选哪个 Qt 版本我建议第一条路线直接用 apt 安装因为这是操作系统发行版维护的版本依赖关系处理得最好装完基本不会有玄学问题。3.1 终端命令三步完成安装在终端里依次执行sudo apt update sudo apt install -y qtbase5-dev qt5-qmake qtbase5-dev-tools qttools5-dev-tools qtcreator这里每个包的角色是qtbase5-devQt5 的核心开发包包含头文件、静态库和默认配置属于必装。qt5-qmakeQt5 的构建工具 qmake。没有它命令行下无法生成 Makefile。qtbase5-dev-tools包括 moc、uic、rcc 等工具Qt 项目的元对象编译全靠它们。qttools5-dev-tools一些辅助工具比如国际化用的 lupdate/lrelease。qtcreatorQt 官方 IDE也就是可视化开发界面。如果你想用 Qt6可以换成sudo apt install -y qt6-base-dev qt6-declarative-dev qt6-tools-dev-tools qtcreator但注意 20.04 和 22.04 默认仓库里的 Qt6 版本比较有限建议先apt search qt6-base-dev确认是否可用。在 Ubuntu 24.04 上qt6-base-dev就在主仓库里装起来会更顺畅。3.2 安装完如何验证以及这种方式的局限装完不要着急写代码先跑三个验证命令gcc --version qmake --version which qtcreatorqmake --version应该能看到类似QMake version 3.1, Using Qt version 5.15.3的输出。如果出现qmake: command not found说明qt5-qmake没装上用apt install qt5-qmake补装。apt 这条路线的优点非常明显省心。Qt 库自动安装到系统目录qmake 在/usr/bin/qmakeQt Creator 也在系统 PATH 里不需要配任何环境变量CMake 项目也能自动找到 Qt。而且在 Qt Creator 新建项目时套件选择页通常会直接识别出可用的 Desktop 套件不用手动指定编译器路径对新手极其友好。局限性也明显版本跟 Ubuntu 发布时绑定。比如 20.04 只能用 Qt 5.12.8无法直接用 apt 升级到 5.15此外一些新模块如 Qt Charts、Qt Data Visualization 需要额外安装或者根本不在仓库里。如果项目要求指定版本或者你需要某些仓库里没有的模块那就看下一章的官方在线安装器。4. 指定版本需求官方在线安装器的操作细节和组件取舍当项目要求“必须在 Qt 5.15.2 上开发”或者你想第一时间用上 Qt6 的新特性apt 路线就不够用了。这时候需要 Qt 官方在线安装器它最大的优势是可以同时装多个版本互不干扰也方便以后用维护工具增删组件。4.1 下载与启动安装器的准备工作先去 Qt 官网的下载页找到 Linux 版在线安装器文件名通常是qt-unified-linux-x64-online.run。下载完成后先赋执行权限chmod x qt-unified-linux-x64-online.run ./qt-unified-linux-x64-online.run如果双击没有任何反应多半是缺了图形库。回到第 2 章把那些依赖装齐再在终端里启动安装器终端会打印具体缺哪个.so文件缺什么补什么。启动后有一步登录 Qt 账号。开源用户用邮箱免费注册一个就行登录后选择开源版本使用渠道即可正常安装。这一步很多人会卡住其实不用有心理负担用个人邮箱注册即可不涉及付费选项。如果你完全不想注册账号可以跳到第 5 章看离线安装包方案。4.2 组件选择的黄金原则和推荐清单在线安装器会列出一棵巨大的组件树很多新手看到那么多模块直接全选结果磁盘爆了、安装时间超长或者反而漏掉了最关键的编译套件。我的原则是主版本下的编译器套件必选模块按需选Sources 基本可以不选。以安装 Qt 5.15.2 为例推荐勾选的内容如下Qt 5.15.2下的Desktop gcc 64-bit这是必选项它决定了/opt/Qt/5.15.2/gcc_64这个目录里面才包含 qmake 和 Qt 库。Developer and Designer Tools下的Qt Creator如果系统里没有装过 Qt Creator这里要勾上。Qt Debug Information Files需要深入查看 Qt 源码堆栈时再勾体积大一般调试用不上。各种附加模块如 Qt Charts、Qt WebEngine、Qt Network Authorization按项目实际需要勾选没必要全选。组件选好后安装器会让你确认安装路径默认是/opt/Qt。我的个人建议是如果这台机器完全归你自己用把路径改成~/Qt或/home/你的用户名/Qt这样后面创建项目和使用维护工具都不会遇到权限问题。如果装到/opt/Qt安装完成后需要额外执行一次sudo chown -R $USER:$USER /opt/Qt把目录归属从 root 改成当前用户否则 Qt Creator 在项目目录生成文件时会报权限错误。4.3 安装完成后验证和目录结构安装完成后检查目录结构ls /opt/Qt/5.15.2/gcc_64/bin/qmake /opt/Qt/5.15.2/gcc_64/bin/qmake -v同时/opt/Qt/Tools/QtCreator/bin/qtcreator是 Qt Creator 的启动入口。启动后在Tools → Options → Kits → Qt Versions里能看到安装器自动识别出来的 Qt 5.15.2qmake 路径指向/opt/Qt/5.15.2/gcc_64/bin/qmake。有一点要注意在线安装器不会自动把它的 qmake 加入系统的/usr/bin所以终端里直接敲qmake -v用的可能还是当初 apt 装的版本。想让终端默认使用官方安装器的版本要么用全路径要么修改 PATH这在第 6 章统一处理。5. 离线安装包没账号也能装特定Qt版本附权限处理有些同学不想注册 Qt 账号或者公司的网络环境不允许在线安装器长时间下载这时候离线安装包是最合适的。它把某个固定版本的所有组件打包好安装时不需要联网拉包速度比在线安装快得多。5.1 离线包获取与授权Qt 官方以及一些知名的软件镜像站都提供了离线安装包文件名类似qt-opensource-linux-x64-5.14.2.run。这里提醒一句.run文件是直接执行的来源一定要可靠。认准 Qt 官方域名或者你平时就信任的软件镜像站不要随便下载某个不知名博客挂出来的链接。拿到.run文件后先赋权限chmod x qt-opensource-linux-x64-5.14.2.run ./qt-opensource-linux-x64-5.14.2.run这里我特别提醒老版本的离线安装器在较新的 Ubuntu 上经常打不开报错大概率是缺少 xcb 系列库或者图形依赖。遇到这种情况先补这一组sudo apt install -y libxcb-cursor0 libxkbcommon-x11-0 libglu1-mesa-dev如果还不行执行安装器时加一个环境变量QT_QPA_PLATFORMoffscreen ./qt-opensource-linux-x64-5.14.2.run这个变量会让安装程序以无窗口模式运行虽然界面可能不显示但安装向导流程仍然可以走是个应急方案。不建议一上来就加这个变量因为无窗口模式下你看不到组件勾选界面容易漏选。5.2 装到 /opt 之后的两个隐藏问题离线安装包默认也把 Qt 装到/opt/Qt这里有两个新手必踩的坑。坑一是权限。安装过程用 root 权限写入了/opt/Qt之后你再用普通用户打开 Qt Creator在项目设置里切换 Kit 或者给 Qt 目录添加新组件时会提示Permission denied。解决办法是把 Qt 目录的所有者改回当前用户sudo chown -R $USER:$USER /opt/Qt坑二是维护工具。离线安装器会生成一个MaintenanceTool位于安装根目录千万别手痒把整个 Qt 目录手动删了。之后要增删组件、修复安装、卸载都要用它。正确操作是运行MaintenanceTool登录后选择添加或移除组件。手动删除目录会导致维护工具失效下次想装补丁只能从头再来。还有一个容易忽略的点不同的离线安装包对 Qt Creator 的处理方式不一样。有的包把 Qt 库和 Qt Creator 都包含在里面有的纯库版本不带 IDE。如果你装完发现系统里没有 Qt Creator直接sudo apt install qtcreator补一个就行IDE 版本不一定要和 Qt 库版本完全一致只要 Kit 里指定了正确的 qmake就能配套使用。6. 环境变量和Kit设置安装成功后最常见的翻车点环境装好了接下来最让人头大的就是“明明装了却找不到”“明明能找到却版本不对”。这一章把所有常见翻车点一次说清。6.1 qmake和PATH为什么会错位如果你同时用了 apt 安装和官方安装器或者装过多个 Qt 版本终端里执行qmake -v显示的很可能不是你想要的版本。因为qmake这个命令是按照 PATH 环境变量依次查找的/usr/bin/如果在/opt/Qt/5.15.2/gcc_64/bin前面找到的就是 apt 版本。解决思路很简单让系统优先找到目标版本。临时切换export PATH/opt/Qt/5.15.2/gcc_64/bin:$PATH qmake -v这样只对当前终端有效。想永久生效把这一行追加到~/.bashrcecho export PATH/opt/Qt/5.15.2/gcc_64/bin:$PATH ~/.bashrc source ~/.bashrcUbuntu 还提供了一个更优雅的工具qtchooser专门用于管理多个 qmake 版本qtchooser -l # 用别名选择 export QT_SELECT5.15.2 qmake -v我的经验是在终端里用 qmake 命令行时用绝对路径最保险在 Qt Creator 里写代码时直接在 Kit 里指定 qmake 路径不依赖终端 PATH。这样两边互不干扰能省掉很多“为什么终端对了、IDE 错了”的烦恼。6.2 CMake项目找不到Qt库的标准解法另一个高频报错是CMake Error at CMakeLists.txt:16 (find_package): Could not find a package configuration file named Qt5Widgets这个问题的本质是CMake 不知道 Qt 的头文件和库文件放在哪里。对于 apt 安装Qt 在系统目录/usr/libCMake 默认能找到对于官方安装器安装的独立版本Qt 在/opt/Qt/5.15.2/gcc_64必须显式告诉 CMake。命令行构建时这样处理cmake -DCMAKE_PREFIX_PATH/opt/Qt/5.15.2/gcc_64 ..在 Qt Creator 里打开项目后进入Projects → Build → CMake → Configuration点Add把CMAKE_PREFIX_PATH加进去。另一种办法是在CMakeLists.txt顶部直接写set(CMAKE_PREFIX_PATH /opt/Qt/5.15.2/gcc_64 CACHE STRING Qt path)这个办法适合固定开发机但团队协作时会覆盖别人本机的路径所以我更推荐在 Qt Creator 的 CMake 配置里单独设置而不是写死在项目文件里。7. 跑通第一个程序从命令行到Qt Creator再到运行报错排查环境配好之后别急着用 IDE先在命令行写一个最小的 Qt 程序把链路彻底跑通。这样一旦后面出问题你能立刻判断是 Qt 库的问题还是 Qt Creator 的问题。7.1 命令行三步法验证纯Qt环境在英文目录下创建hello.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello Qt on Ubuntu); label.resize(320, 120); label.show(); return app.exec(); }然后三步走qmake -project qmake make ./helloqmake -project会扫描当前目录生成一个.pro文件qmake根据.pro生成Makefilemake负责调用 g 完成编译。如果hello窗口弹出来说明 Qt 库、编译器和 qmake 三者都正常问题只可能出现在 Qt Creator 的配置上。这里有个小坑项目目录名尽量不要带中文和空格qmake -project对特殊字符的处理并不稳定。我第一次用中文目录名生成.pro结果 Makefile 里的路径全是乱码编译直接失败。换成~hello_demo这样简单的英文目录一次性就过了。7.2 Qt Creator新建项目的Kit选择从终端启动 Qt Creatorqtcreator或者直接点击应用图标。然后File → New Project → Application → Qt Widgets Application在 Kit 选择页会看到类似Desktop Qt 5.15.2 GCC 64bit的选项。如果这个 Kit 前面是红色感叹号说明 Kit 里某个环节没配置好。到Tools → Options → Kits检查Compilers标签页里是否已有GCC / C和GCC / C没有就手动添加/usr/bin/gcc、/usr/bin/g。Qt Versions标签页里是否已有 qmake 路径手动添加/opt/Qt/5.15.2/gcc_64/bin/qmake。Kits标签页新建一个 Desktop 套件把上面两个元素分别选上。Debugger选/usr/bin/gdb。全部配好后Kit 不再显示警告。之后编译项目时如果报 “could not find or load the Qt platform plugin”直接看下一节。7.3 运行时报xcb、GL类错误的排查顺序Qt 程序在 Linux 桌面端最经典的两个运行报错一个是 xcb一个是 OpenGL。xcb 报错长这样qt.qpa.plugin: Could not load the Qt platform plugin xcb in even though it was found.出现这个说明 Qt 的 xcb 平台插件libqxcb.so在加载时缺了依赖。排查顺序固定为三步第一步安装常见 xcb 补丁库sudo apt install -y libxcb-xinerama0 libxcb-cursor0 libxcb-icccm4 \ libxcb-keysyms1 libxcb-image0 libxcb-shm0 libxcb-render-util0第二步如果还不行用ldd查 qxcb 插件缺什么ldd /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not foundldd会列出它依赖的所有动态库标注not found的就是缺的包。然后根据包名apt search安装对应库。第三步检查QT_QPA_PLATFORM环境变量。默认情况下不要设置它让 Qt 自动选择 xcb乱设置成wayland会导致部分环境下无法启动。GL 报错通常是qt.qpa.gl: Could not initialize OpenGL在虚拟机和远程桌面里最常见。如果你是在 VMware 虚拟机的 Ubuntu 里跑 Qt先到虚拟机设置里开启 3D 加速再装libgl1-mesa-dev。临时想验证是不是缺少 GPU 加速可以先用软件渲染export QT_OPENGLsoftware ./hello能跑通说明真实环境缺少图形加速支持。换用 Xorg 会话或给虚拟机开启 3D 加速后问题基本消失。8. 装好之后值得做的几件事输入法、主题和日常开发体验环境跑通只是开始。真正在 Ubuntu 上用 Qt 写项目还有一些“装完才发现少了点什么”的小事提前处理能省很多心。8.1 中文输入法在Qt程序里打不出字的处理很多人在 Ubuntu 上装好搜狗输入法或 fcitx浏览器和编辑器里都能打中文一进 Qt Creator 或者自己写的 Qt 程序中文就打不进去了。原因很简单Qt 没有对应的输入法插件。如果是 fcitx 方案执行sudo apt install -y fcitx fcitx-frontend-qt5然后在/etc/environment里追加三行QT_IM_MODULEfcitx GTK_IM_MODULEfcitx XMODIFIERSimfcitx重启系统后生效。注意fcitx和ibus两套输入法框架不要同时开否则会和 Qt 的输入法插件互相抢解决了一个旧问题又冒出两个新问题。另外如果你想在 Ubuntu 上用合适的字体写代码我建议在 Qt Creator 的编辑器设置里换成等宽字体比如Source Code Pro或JetBrains Mono长时间盯代码会舒服不少。8.2 让Qt Creator更顺手的零散设置最后分享几个我每次装完 Qt Creator 都会立刻调整的选项。字体方面在Tools → Options → Environment → Font Colors里改等宽字体看代码更清晰。主题方面Qt Creator 支持深色模式在Environment → Theme里选Flat Dark长时间盯屏幕没那么累。快捷键方面可以到Environment → Keyboard里按自己的习惯调整比如我习惯把“查找符号”绑定到 CtrlShiftF。构建方面保持 Shadow Build 默认开启它会把编译产物放到底下的build-项目名-Desktop_Qt_5_15_2_GCC_64bit-Debug目录不会污染源码目录。很多新手看到项目目录里一堆 Makefile 和 .o 文件以为出了问题其实只是没开 Shadow Build。还有一个小技巧Qt Creator 的配置都保存在~/.config/QtProject目录重装系统之前把这个目录备份一下新机器装好 Qt Creator 后直接放回去主题、快捷键、代码风格全回来了。包括之前说的环境变量、依赖安装命令我习惯把它们整理成一个setup_qt.sh脚本存到自己的配置目录里。重装系统后跑一遍脚本基本十分钟就能恢复原来的 Qt 开发环境。装环境这种事情最怕的就是临时去网上翻一条命令复制一条顺序一乱报错就跟着来了。先把准备动作做好后面每一步都是顺水推舟。