很多刚开始用 Ubuntu 做开发的朋友第一步往往不是选编辑器而是被“怎么把 Qt 环境装好”这件事卡住。我不是说安装本身有多难——网上教程一抓一大把但十有八九只告诉你“点下一步下一步”从不解释为什么有些机子装完就能跑有些机子装上连qmake都找不到更不用说后面接踵而来的qt.qpa.plugin、cannot mix incompatible Qt library这类报错。这篇我就以 Linux 系统Ubuntu为例把 Qt 环境安装从选版本、选安装方式到配置验证、踩坑修复的完整链路讲清楚。想折腾嵌入式交叉编译的后面也有专门一节。内容也许不算“最短路径”但能让你少走几趟弯路。实话讲Qt 环境安装这件事本身不难真正坑人的是版本匹配和依赖缺失。Ubuntu 的 apt 仓库里有 Qt但版本往往不是最新Qt 官网的在线安装器会给你全套但你必须清楚自己勾了什么下载了离线包又会发现少了linuxfb之类的插件。我在不同机器上装过不下二十遍 Qt也算把常见雷区踩了个遍。下面这些内容都是我实际操作的记录和排查思路希望能给你省点时间。1. 动手前先把版本、组件和“安装哲学”弄清楚1.1 为什么是 Qt以及 Ubuntu 版本怎么选Qt 在 Linux 桌面领域的分量不用多讲KDE 桌面、WPS、一些汽车中控和工业 HMI 都能看到它的影子。选择 Qt 开发最大的好处是同一套 C 代码可以编译到 Windows、macOS、Linux甚至 Android 和嵌入式 Linux方便后期扩展。但在 Ubuntu 下装 Qt最容易被忽视的问题就是系统版本和 Qt 版本的搭配。以 Ubuntu 20.04、22.04、24.04 为例系统自带的 GCC 版本分别是 9.x、11.x、13.x。Qt 5.15 是最后支持较老 GCC 的长期支持版本而 Qt 6.5 通常更推荐在新系统上使用。我个人的经验是如果你只是学习或者做小工具Ubuntu 22.04 Qt 5.15 是非常稳妥的组合资料多、坑少如果你要新项目建议直接 Ubuntu 22.04/24.04 Qt 6.5/6.7因为 Qt 6 对高版本屏幕缩放、Wayland 的支持明显更好。另外需要先确认系统架构。绝大多数 PC 是 x86_64用uname -m看一下即可。如果输出是aarch64比如树莓派、飞腾等 ARM 开发板那么后续选择安装包时一律要选 ARM64 版本否则会出现“架构不匹配”的奇奇怪怪问题。别笑真有人拿着 x86 的 Qt 安装包往 ARM 板子上拷然后来问我为什么跑不起来。1.2 Qt 的两种“安装哲学”系统包管理器 vs 官方在线安装器在 Ubuntu 上装 Qt 环境大体有三条路安装方式优点缺点适合场景apt install qt5-default或qt6-base-dev简单快速依赖自动解决版本偏旧组件不全只需要基础库快速验证Qt 官方在线安装器版本新组件可挑选包含 Qt Creator体积大需要联网初学者容易选错组件常规开发、跨平台开发离线安装包可以断网安装版本明确下载一个安装包好几个 GB且后续更新麻烦内网环境、嵌入式开发在线安装器会让你登录 Qt 账号这步很多人嫌麻烦但它其实是官方认定的标准渠道因为 Qt 从 5.9 以后开始强化在线安装模式模块化的组件可以随时增删。而apt方式虽然老但真实开发中依然有相当多项目跑在 Ubuntu 20.04 的 Qt 5.12 上——工业界稳定性优先新版本反而未必敢用。我的建议是学习阶段用官方在线安装器尝鲜阶段用 apt内网/嵌入式用离线包。这样最能覆盖你的实际场景。1.3 依赖不装齐后面全是“鬼故事”这个问题我必须放在最前面讲因为 90% 的奇怪报错都源自缺了系统依赖。Qt 不是单靠那几个.so就能跑的它还需要一堆 OpenGL、X11、输入法相关的库。比如你在 Qt 编译时遇到找不到GL/gl.h通常就是因为没装libgl1-mesa-dev运行基于 Qt 的 GUI 程序时提示could not open xkb common多半是缺少libxkbcommon-x11-0之类的东西。所以安装 Qt 前建议先执行这样一组命令把常见依赖一次性补齐sudo apt update sudo apt install build-essential sudo apt install libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev sudo apt install libxkbcommon-x11-0 libxkbcommon0 sudo apt install libxcb-xinerama0 libxcb-cursor0 sudo apt install libdbus-1-dev libfontconfig1-dev libfreetype6-dev如果你是 64 位的 Ubuntu还建议装一下libgles2-mesa-dev因为 Qt 6 的 Quick 模块在很多环境下会使用 OpenGL ES。装完这些再装 Qt你会少踩一半的坑。当年我在 Ubuntu 20.04 上装 Qt 5.15就是因为开头少了一句libxcb-cursor0结果 Qt Creator 每次新建项目都要弹一个“无法加载平台插件”折腾了半天。2. 三条安装路线我把每一步操作都给你列全2.1 路线 Aapt 安装最省事但注意版本如果你只想快速在一个干净的 Ubuntu 上拥有 Qt 的开发编译能力用系统包管理器是最直接的。先更新索引sudo apt update sudo apt upgrade然后根据你的需求选包。Ubuntu 20.04 和 22.04 上Qt 5 的基础开发包可以这样装sudo apt install qt5-default sudo apt install qtcreator sudo apt install qtbase5-dev qtbase5-examples qtbase5-doc但注意qt5-default这个包只在 Ubuntu 20.04 中存在22.04 及之后已经被拆分成qtbase5-dev和qtchooser你直接装qtbase5-dev即可。如果还想用 Qt 6sudo apt install qt6-base-dev sudo apt install qt6-base-examples sudo apt install qt6-declarative-dev sudo apt install qtcreator用 apt 装的 Qtqmake命令会由qtchooser管理。有时候你装了 Qt5 又装了 Qt6直接敲qmake可能提示让你选择版本这时候可以用qtchooser -qt5或qtchooser -qt6来切换默认版本。很多人不知道这一点在终端里敲qmake报“command not found”然后以为安装失败其实是 qtchooser 没有默认项。可以通过这条命令查看qtchooser -list-versions2.2 路线 B官方在线安装器组件勾选是有门道的去 Qt 官网下载安装器时你会看到 “Qt Online Installer for Linux (x64)” 之类的链接。下载后先给执行权限chmod x qtonlineinstaller.run ./qtonlineinstaller.run在线安装器会先让你登录 Qt 账号没有可以注册一个。登录后进入组件选择界面这里最容易出现两类错误一是全选所有组件导致安装体积几十 GB浪费时间二是只选了基础包结果之后想用 Qt Designer 或者某个模块又得重新跑安装器。我建议勾选逻辑如下Qt 版本选一个 LTS 版本即可比如 Qt 6.5.3 或 5.15.2。不要同屏选多个版本既占用磁盘又容易让环境变量混乱。组件桌面平台一定勾选Qt Desktop下的对应编译器套件。如果你是 Ubuntu选Desktop gcc 64-bit。附加模块如果要做界面设计把Qt Debugger Tools和Additional Libraries里的Qt Creator选上。如果你用 QML务必把Qt Quick相关项勾上否则程序运行时会报Unknown module(s) in QT: qml这类错误。Qt Creator在 “Developer and Designer Tools” 分支里建议勾选Qt Creator和CMake。Qt 6 项目默认就用 CMake不装的话后面还得自己去搞 CMake。安装完成后它默认把 Qt 装到~/Qt/目录下。你会看到类似~/Qt/5.15.2/gcc_64/bin/qmake的路径。记住这个位置后面配置很有用。2.3 离线安装包适合内网和嵌入式准备网络受限的机器上官方在线安装器根本跑不起来。这时候你需要到 Qt 官网的“download archives”里找对应的离线安装包。这些包命名通常为qt-opensource-linux-x64-5.15.2.run或qt-opensource-linux-x86_64-6.5.3.run。下载后同样chmod x qt-opensource-linux-x64-5.15.2.run sudo ./qt-opensource-linux-x64-5.15.2.run离线安装包体积很大5.15 大约 3-4 GB6.5 更大。安装时同样可以自定义组件目录但注意它默认会安装到/opt/Qt或当前用户目录下需要 sudo 权限时路径权限要提前设置好。安装完没有桌面的快捷方式需要自己在~/.local/share/applications/下创建.desktop文件或者直接通过~/Qt/5.15.2/gcc_64/bin/qmake使用。3. 装完别急着写代码先确认环境是这个样子的3.1 qmake、qmlscene、Qt Creator 版本对不齐八成是 PATH 问题很多人在终端敲qmake --version发现显示的版本和自己装的 Qt 版本不一致。这时候不用想太复杂大概率是你的PATH里存在多个 Qt 版本系统优先找到了旧的那一个。你可以先查看 qmake 的真实路径which qmake如果显示的是/usr/bin/qmake说明用的是 apt 安装的 qtchooser 代理如果显示~/Qt/5.15.2/gcc_64/bin/qmake或/opt/Qt/6.5.3/gcc_64/bin/qmake说明官方安装器的路径已经在 PATH 中。想让终端优先使用你要的 qmake可以在~/.bashrc里加export PATH$HOME/Qt/6.5.3/gcc_64/bin:$PATH export PATH$HOME/Qt/Tools/CMake/bin:$PATH这里的路径按你的实际安装位置改。加完后source ~/.bashrc qmake --version看到Qt version 6.5.3之类的输出就成了。Qt Creator 内部也要设置正确的 Qt 版本。打开 Qt Creator依次进入 “Tools - Options - Kits - Qt Versions”点击 “Add”选择qmake可执行文件。如果这里报“The qmake executable could not be found”说明你选择的路径不对或该文件没有执行权限。Qt Creator 还需要一个编译器在 “Kits” 页面里确认“Compiler”那栏能看到GCC或G如果没有说明系统缺少build-essential回头把依赖补上。3.2 环境变量配置错误的经典事故与快速救援有人为了图省事直接把整个 Qt 的bin目录加进 PATH这本身没毛病问题出在加错文件或加错顺序。我见过最典型的事故是用户把 export 写进了/etc/profile结果因为路径里多了个空格或者引号不对导致终端每次打开都报bash: export:not a valid identifier。这时候系统里的很多命令都无法正常使用看上去像系统崩了。实际上你只需要找到那行错误的 export 并注释掉即可。如果连终端都打不开可以按Ctrl Alt F3切换到 tty3 纯命令行终端然后检查文件tail -n 20 /etc/profile nano /etc/profile找到错误行删掉或者用#注释再按Ctrl Alt F2回到图形界面重新登录。如果你把 export 加在了~/.bashrc里导致 shell 交互会话异常同样可以用 tty 渠道修复。这个操作看着简单但真的能救急建议收藏。除了 PATH另一个需要留意的环境变量是QT_PLUGIN_PATH。某些情况下程序运行时找不到平台插件就是因为这个变量指向了错误的目录。后面第三节详细说。3.3 三步小验证确认 Qt 环境已经“真的”好了装完之后不要急着写大项目先用三条命令确认基础环境没问题gcc --version cmake --version qmake --version注意如果你用的是 Qt 6官方推荐用 CMake 而不是 qmake。你还需要确认 CMake 能找到 Qtcmake --find-package -DnameQt6 -DCOMPILER_IDGNU或者写个最简CMakeLists.txt来验证。我比较喜欢的方式是直接用命令编译一个最简程序避免 Qt Creator 自动生成的工程把问题复杂化。在终端里创建文件hello.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello Qt on Ubuntu); label.show(); return app.exec(); }然后在终端敲qmake -project qmake make ./hello如果这三步都能顺利通过并弹出窗口说明你的 Qt 环境基本没问题。很多初学者第一次跑 Qt Creator 的新建项目会报“找不到头文件”就是因为没有先用这种小验证判断是环境问题还是项目配置问题。4. 第一个窗口跑起来之后最让我头疼的两个报错4.1 “fatal: cannot mix incompatible Qt library (version ex50601) with this library”到底想说什么这个报错英文看起来复杂翻译过来就是“当前链接的 Qt 库版本0x50601 5.6.1与其他库版本不兼容”。你在自己的 Ubuntu 上大概率不会看到 5.6.1 这个版本但如果你从网上下载了编译好的 Qt 第三方库或者项目里链接了两个不同版本的 Qt 库就会遇到cannot mix incompatible Qt library这类错误。举个例子你系统里用 Qt 6.5 编译了一个可执行程序然后往某个目录里丢了一个用 Qt 5.12 编译的.so。程序运行时去加载这个.so而它内部链接的 Qt 库是 5.12于是动态链接器就会拒绝继续运行报出这个致命错误。解决办法只有两个方向统一版本把第三方库重新用当前 Qt 版本编译或者把当前 Qt 环境换成第三方库对应的版本。隔离加载路径不要简单粗暴地把各种.so都丢进同一个PATH或LD_LIBRARY_PATH里。我在实际项目里遇到最多的情况是给一个老项目升级 Qt 版本时旧的build目录里残留了很多旧版本的.so然后LD_LIBRARY_PATH又指向了旧目录导致整个程序起不来。清理build目录并重新执行 qmake 后问题消失。所以遇到这类报错不要慌先用ldd ./your_app | grep qt看看程序到底链接了哪些 Qt 库版本一目了然。如果是动态库路径混乱慢慢把LD_LIBRARY_PATH里可疑的项去掉就行。4.2 平台插件报错could not find the qt platform plugin linuxfb是怎么回事这条报错在嵌入式 Linux 上极其常见在 PC 上偶尔也会碰到。先理解背景Qt 的 GUI 最后必须通过“平台插件platform plugin”来和系统交互。桌面 Linux 上你用的是xcb或wayland插件嵌入式设备上没有 X Server 时才会用linuxfb、eglfs这类插件。如果你的程序只编译了linuxfb插件而系统实际没有/dev/fb0这类帧缓冲设备运行时就会报找不到插件或者无法打开设备。如果你是在普通 Ubuntu 桌面上看到could not find the qt platform plugin linuxfb大概率是有人在环境变量里强行设置了QT_QPA_PLATFORMlinuxfb。你可以检查一下env | grep QT_QPA_PLATFORM如果输出里有 linuxfb把它去掉即可unset QT_QPA_PLATFORM如果是嵌入式设备上真的需要 linuxfb那么请确保你的 Qt 安装时带了linuxfb支持也就是编译选项里开启-qt-linuxfb或者在 Qt Creator 的 Kit 配置文件里勾选了对应插件。另外/dev/fb0这个设备必须存在而且当前用户应该属于video组sudo usermod -aG video 你的用户名然后重新登录。如果/dev/fb0都不存在看看内核模块fbdev是否有加载。4.3 桌面环境下最常见的xcb平台插件加载失败更普遍的报错其实是could not find the qt platform plugin xcb。刚开始我以为是 Qt 安装不完整折腾了很久才发现问题往往是 Qt 的xcb插件依赖的xcb 相关系统库版本不匹配。解决方式分两步确认插件的依赖是否完整ldd ~/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not found如果输出有not found说明缺少系统库。根据缺什么补什么常见的补法sudo apt install libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xkb1如果依赖完整还是报错注意查看报错信息里的具体库名比如libxcb-xinerama.so.0。这时用locate libxcb-xinerama看看到底在哪是不是 32 位/64 位混淆了。通常把上面这些装好Qt 的桌面 GUI 就能正常弹出来了。这个坑真的太普遍因为在线安装器里的 Qt 并不帮你把这些 xcb 依赖装好它假设你的系统已经有了。5. 收尾前再补几个新手经常问的周边问题5.1 Ubuntu 中文输入法在 Qt 程序里失效怎么办不少人在 Ubuntu 上装完 Qt Creator 后发现写代码时中文输入法能正常打字但 CtrlSpace 切换候选词时或在 QML 的 TextInput 里无法调出中文输入法。多数原因是 Qt 缺少fcitx输入法插件。如果你用的是 fcitx5至少要装sudo apt install fcitx5-frontend-qt5 fcitx5-module-xorg如果你用的是 ibus则可能需要安装 ibus-qt5 相关包sudo apt install ibus-qt5装完注销重新登录。还有一个小技巧在 Qt 程序里临时设置环境变量QT_IM_MODULEfcitx ./your_app看完有没有输入法如果有效再把QT_IM_MODULEfcitx写进~/.bashrc里的 export。但注意如果切换桌面环境这个变量反而可能害你无法输入所以最好按需设置。5.2 要是你默认启用的是 Wayland而 Qt 程序显示不正常如果 Qt 程序在 Ubuntu 22.04 上出现界面模糊、缩放异常或无法输入等问题很可能是 Wayland 会话导致的。你可以强制走 X11 方式运行./your_app -platform xcb或者设置环境变量export QT_QPA_PLATFORMxcb ./your_app反过来如果你是在嵌入式开发板上需要 Wayland 窗口环境那就得保证 Qt 配置里有-qt-wayland。5.3 在 Ubuntu 上做交叉编译到树莓派需要提前知道的热搜词里有“树莓派4交叉编译qt”这里简单提两句因为很多嵌入式项目终点就是这个。交叉编译不是在本机装个 ARM 版 Qt 就行你需要在 Ubuntu 主机安装交叉编译工具链比如aarch64-linux-gnu-gcc。下载或从树莓派里拷贝一套 sysroot树莓派系统根目录包含/lib、/usr/include等。用 Qt 源码交叉编译出一个 ARM 版的 Qt 库路径类似~/raspi/qt5。最后在创建编译套件时把编译器和 qmake 都指向交叉编译产物。交叉编译时最容易翻车的是 sysroot 里的库不匹配或者路径不对。我的建议是先在树莓派上把 Qt 依赖的库用apt装一遍再把整个根文件系统打包成 sysroot。具体操作之前写过专门的文章这里不展开但记住一个原则交叉编译的 qmake 千万不要和宿主机的 qmake 混用否则就会出现上一节说的 cannot mix incompatible Qt library。5.4 我的几条保命经验最后分享几条装过无数遍 Qt 后沉淀下来的习惯每次装 Qt 前先在虚拟机或独立目录里试一次确认没问题再动手到工作机避免污染正在用的开发环境。不要在LD_LIBRARY_PATH里塞太多自定义路径它会让动态库解析变得不可预测。能用 CMake 的 rpath 或 Qt Creator 中的构建目录设置来管理就不要去动全局环境变量。Qt Creator 里如果项目报错“project ERROR: Unknown module(s) in QT”先回头检查“Kits”里选择的 Qt 版本是否包含该模块。比如你要用Qt Charts但安装时没勾选那不管怎么编译都会报这个错误。在线安装器可以随时增删组件不需要卸载重复安装。运行安装器即可选择添加或移除模块比重新下载离线包省事。使用apt装完 Qt 后在/usr/lib/x86_64-linux-gnu/cmake/里能看到各种 Qt6 的 CMake 配置文件。如果 CMake 找不到 Qt检查这个目录是否存在。我个人在实际操作中的体会是Ubuntu 下装 Qt 环境最费时间的其实不是安装本身而是排错。这些报错大多指向同一个根源版本不一致、依赖缺失、路径混乱。把这三点控制好Qt 环境基本不会再折磨你。下次你再看到fatal: cannot mix incompatible Qt library这类错误可以先检查动态库路径而不是急着卸载重装。毕竟工具链这东西稳定是要求顺手是运气能自己排查才是真正的本事。
