Ubuntu下Qt环境搭建全攻略：apt与官方安装器对比及常见问题排查

1. 整体思路与方案选型

先聊聊我在 Ubuntu 上折腾 Qt 环境的一些体会。不少新手一上来就直奔 Qt 官网下载安装包，结果发现要么缺依赖、要么许可证选错、要么装完了打开 Creator 就报错，折腾一晚上还在跟库文件较劲。其实在 Ubuntu 上装 Qt，路子不止一条，关键看你要干什么。

先说结论：如果你只是想用一个稳定的环境写 Qt Widgets 或 Quick 程序，并且不追求 Qt 官网的“原汁原味”，那我个人首推动手apt 直接安装官方源里的版本。原因很简单：Ubuntu 软件源里的 Qt 是经过发行版测试的，跟系统的 OpenGL 驱动、gcc、cmake 版本都磨合过，装完基本能跑，不用自己处理一堆底层依赖。而如果你需要某个特定版本的 Qt（比如装 Qt 5.15 或 Qt 6.5 的某个小版本），或者要调试 WebEngine、要装一些官方源里没有的模块，那就得走 Qt 官方在线安装器或离线安装包的路线。

这里把几种常见方案的优劣放在一起对比一下，你在动手前先对号入座：

我自己在 Ubuntu 22.04、24.04 上都实操过，结合网上大家反馈比较多的“新手翻车点”，这篇文章里我会把两条路的细节都掰开讲清楚，并且把运行 Qt Creator、配置 Kit（编译器套件）、编译运行首个程序的全过程也一起走一遍，这样你照着操作一次就能跑通。

注意：如果你想做的是嵌入式方向，比如给 RK3588 或树莓派做交叉编译，那安装 x86 平台上的原生 Qt 只是第一步，后面还需要交叉工具链和 sysroot，这些内容本文最后会提一嘴思路，但不展开细说，那是个大话题，一篇文章写不完。

2. Ubuntu 下安装 Qt 的两种主流方案

这里我按“能直接跑起来”为标准，把安装过程逐步写清楚。先讲 apt 方案，再讲官方安装器方案。你可以根据自己需求挑一条路走，不必两条都执行。

2.1 方案一：apt 安装，最快上手路线

Ubuntu 的 apt 源里一直有 Qt 的相关包，只是很多人不知道具体该装哪些。这里先明确一个基础概念：Qt 5 的包名基本以libqt5开头，Qt 6 的包名以qt6开头。如果只是装个开发框架本体，只装libqt5*的运行时是远远不够的，必须装-dev结尾的开发包，否则编译时头文件都找不到。

我建议用一条命令把这组核心开发包装好：

sudo apt update sudo apt install build-essential libgl1-mesa-dev libfontconfig1-dev \ libdbus-1-dev libfreetype6-dev libicu-dev libinput-dev libxkbcommon-dev \ libssl-dev libegl1-mesa-dev libx11-xcb-dev libxcb-cursor-dev \ qtbase5-dev qtbase5-dev-tools qtchooser qt5-qmake qtcreator

解释一下这里面几个包的作用：

• build-essential：包含 gcc、g++、make 等编译工具链。没有它，啥都编不了。
• qtbase5-dev：Qt5 的核心开发包，包含了 QtWidgets、QtGui、QtCore 等模块的头文件和链接库。
• qtbase5-dev-tools：给了一堆命令行工具，比如qmake、moc、uic，这些都是 Qt 编译流程的关键工具。
• qtcreator：集成开发环境本体，装完就能启动 IDE。
• qtchooser：用来切换多个 Qt 版本的命令行工具。如果你后面又装了 Qt 6，可以用它来切换默认 qmake 版本，很方便。
• 最后那一堆libxxx-dev是 Qt 图形界面在 Linux 上运行的基础依赖。尤其libegl1-mesa-dev和libgl1-mesa-dev，这俩是 OpenGL 相关的，很多 Qt 程序界面显示异常、黑屏、报could not find the qt platform plugin之类的问题，很大概率就是缺了它们。
• libxkbcommon-dev和libxcb-cursor-dev是为了解决在 Wayland 会话下的键盘和鼠标光标渲染问题，Ubuntu 22.04 以后默认 Wayland，这俩不装的话，新装好的 Qt 程序可能打不开或光标消失。

装完验证一下：

qmake --version

如果正常输出类似QMake version 3.1和Using Qt version 5.15.13这样的内容，说明核心环境已经就位。再启动一下 Qt Creator：

qtcreator

第一次启动如果界面正常出现，那就说明图形环境依赖也齐了。这一步如果报错，绝大多数是缺libxcb-cursor0或libegl1-mesa-dev，装一下再试。

这套方案的缺点是版本不会特别新。以 Ubuntu 22.04 为例，官方源里 Qt 5 是 5.15.13，Qt 6 则在 24.04 里提供 6.4.x。对于日常开发和学习完全够用，但如果你想用 Qt 6.5 LTS 或更新的版本，就得走官方安装器了。

2.2 方案二：Qt 官方安装器，版本自由

Qt 官方安装器分为在线安装器和离线安装包。在线安装器是个几百 KB 的.run文件，真正的东西需要联网下载。离线安装包则是整个安装包的快照，体积通常在 3~10GB 之间，适合内网或网络环境差的场景。

先到 Qt 官网下载在线安装器，注意选择 Linux 平台。我建议直接下载在线安装器，它能让你自由勾选 Qt 版本和模块，后续加装新版本也更方便。下载后执行：

chmod +x qt-unified-linux-x64-online.run ./qt-unified-linux-x64-online.run

运行后会弹出一个图形化的安装向导。我提醒几个容易忽略的点：

• 必须注册 Qt 账号并登录，否则无法继续。这一步很多人嫌烦，但绕不过去。
• 安装路径建议使用默认的~/Qt，因为 Qt Creator 后续会在这个目录下自动搜索已安装的 Qt 版本，如果你自改到/opt或别处，后面需要手动配置路径，对新手来说多一层出错风险。
• 在选择组件时，默认只勾选了Qt本体和Qt Creator。如果你需要用 QML 开发界面，记得展开Qt下的Libraries，勾上Qt QML和Qt Quick相关模块。需要编译 Android 或 iOS 程序则需要额外勾选对应平台组件，这个一般用不到，不勾。

安装器的下载过程需要耐心。Qt 官方服务器在国内经常慢到怀疑人生，动辄几个小时。这里有个经验：如果下载太慢，可以先点暂停，再点继续，有时候会切换到一个更快的 CDN 节点，实测有效。

装完后命令行验证：

export PATH=~/Qt/对应版本目录/gcc_64/bin:$PATH qmake --version

这里注意，通过官方安装器装的 qmake 不会自动进入系统的 PATH，你需要手动把它加进去，或者每次启动 Qt Creator 时让它自己去注册表（配置文件中）识别。通常你直接启动 Qt Creator，它会自动扫描到~/Qt下的所有 Qt 版本并列出，不需要手动设置。

2.3 环境变量与多版本管理

装完 Qt 之后，不管你是 apt 装的还是官方安装器装的，我强烈建议你搞明白环境变量和 QMAKE 的关系，否则后面很容易出现“系统里明明有 Qt，但你编译时用的却是另一个版本”这种怪问题。

先说最简单的场景：你只装了 apt 源里的 Qt5。那么系统默认的qmake直接可用，不需要设置任何环境变量。这得益于 Ubuntu 把/usr/bin/qmake指向了qtchooser，而 qtchooser 又默认选择 Qt5 的 qmake。

再多装一个 Qt6 之后，情况就变了。此时qmake会变成 qtchooser 的一个入口，你需要告诉它用哪个版本，比如：

qmake -qt=qt5 qmake -qt=qt6

或者直接用绝对路径调用：

/usr/lib/qt6/bin/qmake ~/Qt/6.5.0/gcc_64/bin/qmake

为了省事，我建议在~/.bashrc里为常用 Qt 版本设置一个别名：

alias qmake6=~/Qt/6.5.0/gcc_64/bin/qmake alias qmake5=qmake -qt=qt5

这样在不同项目中切来切去就不会搞混了。关于 CMake 项目，则可以在构建时用CMAKE_PREFIX_PATH指定 Qt 路径，这个后面实操部分我会说。

3. Qt Creator 配置与编译环境搭建

很多人在这一步忽略了客厅一个加分项：Qt 的集成开发环境 Qt Creator。它是一个很好的 IDE，编译、调试、界面设计都在里面，你可以省掉很多来回折腾的功夫。但需要说明的是，Qt Creator 本身只是一个编辑器，真正编译靠的是底下配好的构建套件，也就是编译器、qmake 或 CMake、调试器的组合。搞清楚这套组合，才是环境配置的重头戏。

3.1 新建项目与选择构建套件（Kit）

安装完成后第一次启动 Qt Creator，界面上会有“Welcome”页面。如果你在安装 Qt 时没有特别改动路径，这里它会自动检测到 Qt 版本和编译器。你可以先到菜单“Tools -> Options -> Kits”里看看有没有自动生成的套件。如果没有，或者某些项目标有黄色感叹号，说明对应的组件不完整，需要手动补。

一个正常套件需要哪些要素：

• 编译器（Compiler）：一般选GCC，对应x86_64-linux-gnu-g++。
• 调试器（Debugger）：GDB。
• Qt 版本（Qt version）：qtbase 的 qmake 路径。
• CMake：如果项目基于 CMake 构建，则需要指定的 CMake 版本。

创建新项目时选Qt Widgets Application或Qt Quick Application模板。创建完成后，左下角会有构建套件下拉框，确认选中你刚才看得那个 Kit。很多人编译时点击运行发现“building”是灰的，原因就是没有选中任何 Kit，或者 Kit 不完整。

3.2 编译运行第一个 Qt 程序

我们写一个最简单的控制台 Qt 程序来验证整个链路。新建文件hello.cpp：

#include <QCoreApplication> #include <QDebug> int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); qDebug() << "Qt environment is ready!"; return a.exec(); }

在终端中编译：

qmake -project qmake make ./hello

如果看到Qt environment is ready!输出，说明你的 qmake、编译器、链接器全部工作正常。如果这里有问题，说明 Qt 环境有缺口，请先用这个最小程序做诊断，而不要直接去编译一个大型项目。

对于 CMake 项目，通常的编译格式为：

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/qt cmake --build build -j$(nproc)

要注意的是，CMAKE_PREFIX_PATH要指向包含lib/cmake/Qt5或lib/cmake/Qt6的目录，比如/usr/lib/x86_64-linux-gnu/cmake（apt 源）或~/Qt/6.5.0/gcc_64（官方安装器）。如果这个路径没有给对，CMake 会疯狂报Could not find a package configuration file provided by "Qt5Widgets"之类的错误。

4. 核心细节：Qt 库依赖与编译背后那些事

一个很有价值的经验：不要把 Qt 环境想成“一个 IDE 里点按钮就能出程序”的东西。Qt 本质上是一堆动态库（.so）和编译工具的组合，Linux 下编译 Qt 程序，本质上是链接器把libQt5Core.so.5、libQt5Gui.so.5这些库找出来并链接进你的可执行文件。所以你在排查问题时，最常用的工具不是搜索引擎，而是ldd。

4.1 动态库依赖排查：ldd 的用法

当你的程序编译通过，运行却报error while loading shared libraries: libQt5Widgets.so.5: cannot open shared object file时，很多人的第一反应是“Qt 坏了”。事实往往不是，只是运行时的库搜索路径不对。

这个命令可以看到你的可执行文件依赖哪些库，以及它们去哪里找：

ldd ./myapp

如果是 apt 装的 Qt，系统装什么包就把.so放在/usr/lib/x86_64-linux-gnu/下面，动态链接默认就能找到，因此一般不会出这个错。但官方安装器装出来的 Qt，可执行文件默认不会自动找到~/Qt/5.15.2/gcc_64/lib下的库，你需要在启动前设置：

export LD_LIBRARY_PATH=~/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH

注意：LD_LIBRARY_PATH只是临时环境变量，重启终端后就没了。如果你嫌麻烦，可以在启动脚本里加上这一行，或者干脆在/etc/ld.so.conf.d/下新建一个配置文件写入 Qt 库路径，然后运行sudo ldconfig。我个人建议个人开发时直接用环境变量，改库路径这种事不要轻易对系统动刀，万一系统里还跑着别的 Qt 程序，你改了全局的ldconfig可能把它们连带弄崩。

4.2 看清 Qt 的程序运行时库

另一个常见报错是：

qt.qpa.plugin: Could not find the Qt platform plugin "linuxfb" in ""

这个报错和缺失linuxfb插件有关。平台插件是 Qt 图形程序启动时用于创建窗口的底层接口层（platform plugin），不同的运行环境需要不同的插件：xcb用于 X11，wayland用于 Wayland，linuxfb用于 Linux 帧缓冲设备——一般嵌入式场景才用，台式机上不一定装了。如果 Qt 提示找不到linuxfb，大概率是你程序代码里或环境变量里强制指定了该平台，但你这个发行版的 Qt 没有附带它。

排查办法很简单：

QT_QPA_PLATFORM=xcb ./myapp

如果这样能启动，说明只是平台插件指定错误，在代码里删掉-platform linuxfb的参数即可。如果你确实需要 linuxfb 插件，在 Ubuntu 上需要额外安装libqt5gui5的对应插件包或自己编译 Qt 时勾选 LinuxFB 支持。

4.3 多版本混用导致的“canonical”版本冲突

很多人在编译一个带 Qt 的项目时，会遇到类似这种报错：

fatal: cannot mix incompatible Qt library (version 0x50e0601) with this library

这种情况我在实际中遇到很多次，本质原因就一句话：编译环境中链接了 Qt 5，但运行时却加载了 Qt 6 的库，或者同一个进程里链接了两个不同小版本的 Qt 库。因为 Qt 库里有大量的内联函数和 ABI 敏感的符号，链接器和运行时不匹配就会直接崩溃。

举个例子：你在 CMake 里设置了CMAKE_PREFIX_PATH指向 Qt6，但系统的qmake是 Qt5 的，同时 Makefile 的部分目标还是用 qmake 生成的，这样编出来的程序某些模块链接 Qt6，某些模块链接 Qt5，启动就崩。解决办法很简单：项目内的所有构建配置保证指向同一个Qt 版本，用 CMake 项目就统一用CMAKE_PREFIX_PATH，用 qmake 项目就全程用同一个 qmake 路径，不要一会儿 CMake、一会儿 qmake。

4.4 编译时找不到库文件：cannot find -lxxx

日志里出现cannot find -lxx，这种错误很多新手看着吓人，其实就是一个链接器找不到静态库或动态库文件的问题。比如：

/usr/bin/ld: cannot find -lpublic

这表示链接器在搜索路径里没有找到名为libpublic.so或libpublic.a的库文件。这里的-lpublic只是“public”这个名字，不是某个固定存在的库。它的产生原因一般是两类：

一是你的.pro或CMakeLists.txt中用了LIBS += -lpublic，但对应的库根本没有安装。这时你需要先定位这个库属于哪个包，用apt search libpublic找到后apt install装一下。

二是库文件存在，但路径不标准。比如库在/opt/mylib/lib/下，链接器默认不去这里搜。qmake 项目要手动加：

LIBS += -L/opt/mylib/lib -lpublic

CMake 项目则用：

target_link_directories(myapp PRIVATE /opt/mylib/lib) target_link_libraries(myapp PRIVATE public)

经验谈：遇到cannot find -lxxx，先看这个名字和你代码里 include 的头文件的对应关系，然后到/usr/lib/x86_64-linux-gnu/下搜一下有没有libxxx.so或libxxx.a。如果搜不到，说明缺包或路径问题，不要急着改代码。

5. 常见问题排查与避坑指南

到了这一部分，我们把这些年在安装和第一周使用 Qt 过程中遇到的最经典问题集中写一写。这部分适用于你已经把环境装完、但运行出问题的阶段。按问题的频次从高到低排序。

5.1 Qt Creator 打不开或启动后白屏

很多 Ubuntu 用户都有这个经历：装好了 qtcreator，双击图标没反应，在终端运行时输出：

qt.qpa.xcb: could not connect to display qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.

这种情况十有八九是缺少 XCB 相关的库，而且具体缺哪个还不好说，因为 Qt Creator 需要一系列 xcb 库：libxcb-icccm4、libxcb-image0、libxcb-keysyms1、libxcb-render-util0、libxcb-shape0、libxcb-xinerama0。

最简单粗暴的修复方式是安装完整依赖：

sudo apt install libxcb-*0 libxcb-*dev

这里注意通配符会把一些无关的包也带上，但不会引入冲突。这种情况多出现在官方安装器安装的 Qt 上，因为官方安装器不强检查发行版依赖。如果你是通过 apt 装的 Qt，一般不会遇到这问题。

另外一个可能原因是 OpenGL 不可用。Qt Creator 完美支持硬件加速，但如果你的虚拟机或者显卡驱动有问题，它可能创建 OpenGL 上下文失败。可在启动时强制用软件渲染：

QT_OPENGL=software qtcreator

这条命令是我在虚拟机里跑 Qt Creator 最常用的保命药。如果你是 VMware 虚拟机里装 Ubuntu 来开发，务必记住这个。

5.2 程序编译通过，运行时找不到 platform plugin

这个报错前面提过：

qt.qpa.plugin: Could not find the Qt platform plugin "xcb" in ""

还有一种变体：

This application failed to start because no Qt platform plugin could be initialized.

通常原因是你的程序找不到 Qt 安装目录中的plugins/platforms/libqxcb.so。当你使用官方安装器安装 Qt，并写了一个独立程序，直接双击运行时很容易遇到。因为可执行文件通过LD_LIBRARY_PATH找到了libQt5Core.so，但libqxcb.so在执行某些操作时需要额外加载，而此时 Qt 内部判断 Qt 库的路径不是它预期的~/Qt/5.15.2/gcc_64。

解决思路：看你的可执行文件旁边的启动环境。最稳妥的方式是不要直接双击，而是用一个启动脚本：

#!/bin/bash export QTDIR=~/Qt/5.15.2/gcc_64 export QT_PLUGIN_PATH=$QTDIR/plugins export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH ./myapp

原理是用QT_PLUGIN_PATH显式告诉 Qt 到哪个目录找插件。如果程序内嵌了 Qt 的部署方式，也可以检查 Qt 安装目录下plugins/platforms/是否真的有libqxcb.so。没有的话，安装器部分组件可能没勾全，回到安装器里补上“Qt Platform”模块。

5.3 编译时找不到 Qt 头文件

日志里出现：

fatal error: QApplication: No such file or directory

这就是 QApplication 的声明完全没找到，也就是开发包没装好。apt 方案中，需要用qtbase5-dev提供头文件。如果你已经装过了还是找不到，可以检查头文件位置：

dpkg -L qtbase5-dev | grep "QApplication"

正常会输出一个/usr/include/x86_64-linux-gnu/qt5/QtWidgets/QApplication之类的路径。如果这个包存在但你的项目还是找不到头文件，那大概率是 qmake/CMake 的 include 路径配置出了问题。qmake 项目可以在.pro文件里手动添加：

QT += widgets INCLUDEPATH += /usr/include/x86_64-linux-gnu/qt5

CMake 项目则检查CMAKE_PREFIX_PATH指向是否有问题，也可以在CMakeLists.txt里加：

find_package(Qt5Widgets REQUIRED)

后者的内部逻辑会处理头文件路径，不需要手动指定。

5.4 卸载 Qt 时留的后遗症

有相当多的人因为各种原因决定卸载 Qt，结果卸载后又出现各种问题。我提两个常见场景。

如果你是 apt 方式装的，卸载命令：

sudo apt remove qtbase5-dev qtcreator sudo apt autoremove

建议连autoremove一起执行，把不再需要的依赖清理掉。但要注意：这样会把所有依赖 Qt 5 开发包的软件一起清理，如果你系统里还有别的基于 Qt 的软件（比如 VLC 的部分模块、WPS 等），它们可能会被一同移除，有误删风险。所以执行autoremove之前先看看它列出的要删的包，有疑惑就手动取消一些包。

如果你是用官方安装器装的 Qt，卸载时直接在安装目录下运行MaintenanceTool，这是一个带图形界面的维护工具，可以管理组件、增加模块、卸载全部 Qt。强推，不要自己手动rm -rf ~/Qt，因为那样会留下注册表信息（在~/.config/QtProject和~/.local/share/Qt），下次安装可能会报“已有 Qt 安装记录”之类的奇怪错误。

5.5 Ubuntu 输入法在 Qt 程序中无法输入中文

这个问题在中文环境下极其常见。你在系统里用搜狗或 fcitx 输入法打字没问题，但一进 Qt Creator 或者编译出来的 Qt 程序里，中文输入就失效，或者光标不跟随。原因是 Qt 程序没有加载输入法插件。

解决方法：确认你安装的 Qt 包含libfcitxplatforminputcontextplugin.so或libibusplatforminputcontextplugin.so。在 Qt5 中，这属于qtbase5-dev的一部分，但可能需要安装额外的输入法支持包：

sudo apt install libqt5sql5-sqlite qt5-qmltooling-plugins fcitx-frontend-qt5

对于 Ubuntu 22.04 之后系统的 IBus 拼音，可能要这样：

sudo apt install ibus-qt5

装完后退出 Qt Creator 重启，输入法一般就正常了。如果还是不行，在/etc/environment中增加两行：

QT_IM_MODULE=fcitx GTK_IM_MODULE=fcitx

然后注销重登。这个方法我用过很多次，基本能解决 90% 的 Qt 输入法问题。

6. 进阶思路：编译嵌入式和自编译 Qt

6.1 自编译 Qt 的流程与代价

如果你需要的 Qt 版本在 apt 源和官网安装器里都找不到，或者想做嵌入式裁剪，那就只能源码编译。自编译 Qt 的完整流程大致是：

wget https://download.qt.io/official_releases/qt/5.15/5.15.2/qt-everywhere-opensource-src-5.15.2.tar.xz tar xf qt-everywhere-opensource-src-5.15.2.tar.xz cd qt-everywhere-opensource-src-5.15.2 ./configure -prefix /opt/Qt-5.15.2 -opensource -confirm-license -release \ -nomake examples -nomake tests make -j$(nproc) sudo make install

看着简单，实际操作时configure会检查一大堆依赖：Perl、Python、OpenGL 头文件、xcb 库……缺一个都会终止。所以自编译前，最好把 Ubuntu 的依赖一次性装齐：

sudo apt install perl python3 libfontconfig1-dev libfreetype6-dev libx11-dev \ libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-dev \ libx11-xcb-dev libxcb-glx0-dev libxcb-util0-dev libxcb-image0-dev \ libxcb-keysyms1-dev libxcb-randr0-dev libxcb-shape0-dev \ libxcb-sync-dev libxcb-xfixes0-dev libxcb-xinerama0-dev \ libxcb-xkb-dev libxcb-icccm4-dev libxcb-cursor-dev \ libgl1-mesa-dev libglu1-mesa-dev libxkbcommon-dev libxkbcommon-x11-dev

我个人的经验是：如果你不是要做嵌入式交叉编译，不要轻易自编译 Qt。因为 Qt 本体编译一次在目前的机器上也要 30 分钟到 1 小时，而且你还得维护自编译版本的更新。嵌入式场景下自编译是无法回避的，因为你要做的设备可能是个 arm 板子，能用的资源、依赖都有限，需要定制。但桌面开发用自编译纯粹是和自己过不去。如果你选择了这条路，我的建议是把-prefix设置到一个不干扰系统其他软件的位置（比如/opt），不要覆盖系统自带的 Qt，免得把你现有能用的环境搞崩。

6.2 树莓派或 RK3588 等 ARM 平台的 Qt 交叉编译思路

最近不少人在搞 RK3588 和树莓派的 Qt 开发，因为这两类单板电脑作为工控设备或桌面级 SBC 非常好用。交叉编译 Qt 的思路和桌面自编译类似，但多了工具链和 sysroot 的概念。

交叉编译常规套路：

1. 在 x86 的 Ubuntu 上安装交叉工具链（比如aarch64-linux-gnu-g++）。
2. 准备目标机（板子）的文件系统 rootfs，把需要的头文件和库拷贝到某个目录，比如/opt/rootfs。
3. 用-prefix /opt/qt-arm配置 Qt，并指定-xplatform linux-aarch64-gnu-g++。
4. 编译安装，然后把整个/opt/qt-arm目录拷贝到板子上。

这么说可能对新手很抽象。我建议先不要碰交叉编译，先在板子上直接 Ubuntu 源里apt install一个原生 Qt，跑通第一个程序，再研究交叉编译。如果不先理解编译产物如何在设备上运行，交叉编译只是多给了一堆凌乱的命令而已。这个方向我在后续文章里可能会单开一篇细讲，这里先点到为止。

7. 关于 Qt 版本选择的个人建议

文章最后想聊一个在使用过程中最容易忽略的问题：选 Qt 版本。

很多教程默认推荐 Qt 5.15 或 Qt 6.x，但没有人告诉你：Ubuntu 系统版本和 Qt 版本是强相关的。如果你是 Ubuntu 20.04，系统里默认的 GCC 是 9.x，这个编译器虽然支持 C++17，但对 Qt 6 的某些 CMake 特性支持不是特别完美。你要是 Ubuntu 22.04，内置 GCC 11，跑 Qt 6.2+ 就非常顺滑。勉强在旧系统上跑新 Qt，最后会变成“为了编 Qt 先升 GCC，为了升 GCC 再改源”的死循环。

从我这个老用户的经验来说，我建议：

• Ubuntu 20.04：用 apt 装 Qt 5.15，稳妥。想用 Qt6 就装官方安装器，但别想着用旧编译器直接编 Qt6 源码。
• Ubuntu 22.04 / 24.04：可以用 apt 装 Qt 6.4 或官网 Qt 6.5 LTS，日常开发体验已经很成熟。
• 如果你要跨平台发布程序，Qt 5.15 LTS 依然是兼容性最好的版本。老系统上跑也好，依赖少，真没那么多毛病。

最后说一个小细节。很多人装完 Qt 后，直接看 Qt Creator 里的示例项目，发现一跑就报错，然后就觉得环境不行。其实大部分示例项目需要额外的模块（比如 Charts、Data Visualization），你可能没装对应模块。不要一上来就拿复杂示例开刀，先用最基础的 Widgets 项目跑通整个流程，再逐步引入新模块。很多问题不是你环境有问题，而是你用它的方式太猛了。

我自己在实际开发中最常用的检查动作是：新环境装完，先建一个QCoreApplication的最小程序编译运行，再建一个带界面的QWidget程序运行，两头都通了，环境才算真就绪。这个过程总共不到五分钟，但它能帮你省下后面调试项目时大量的排查时间。