企业官网建设流程全解析

很多刚开始用 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 环境，大体有三条路：

在线安装器会让你登录 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 路线 A：apt 安装，最省事但注意版本

如果你只想快速在一个干净的 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 6：

sudo apt install qt6-base-dev sudo apt install qt6-base-examples sudo apt install qt6-declarative-dev sudo apt install qtcreator

用 apt 装的 Qt，qmake命令会由qtchooser管理。有时候你装了 Qt5 又装了 Qt6，直接敲qmake可能提示让你选择版本，这时候可以用qtchooser -qt=5或qtchooser -qt=6来切换默认版本。很多人不知道这一点，在终端里敲qmake报“command not found”，然后以为安装失败，其实是 qtchooser 没有默认项。可以通过这条命令查看：

qtchooser -list-versions

2.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 GB，6.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 能找到 Qt：

cmake --find-package -Dname=Qt6 -DCOMPILER_ID=GNU

或者写个最简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_PLATFORM=linuxfb。你可以检查一下：

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 相关系统库版本不匹配。

解决方式分两步：

1. 确认插件的依赖是否完整：

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

2. 如果依赖完整还是报错，注意查看报错信息里的具体库名，比如libxcb-xinerama.so.0。这时用locate libxcb-xinerama看看到底在哪，是不是 32 位/64 位混淆了。

通常把上面这些装好，Qt 的桌面 GUI 就能正常弹出来了。这个坑真的太普遍，因为在线安装器里的 Qt 并不帮你把这些 xcb 依赖装好，它假设你的系统已经有了。

5. 收尾前，再补几个新手经常问的周边问题

5.1 Ubuntu 中文输入法在 Qt 程序里失效怎么办

不少人在 Ubuntu 上装完 Qt Creator 后，发现写代码时中文输入法能正常打字，但 Ctrl+Space 切换候选词时或在 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_MODULE=fcitx ./your_app

看完有没有输入法，如果有效，再把QT_IM_MODULE=fcitx写进~/.bashrc里的 export。但注意，如果切换桌面环境，这个变量反而可能害你无法输入，所以最好按需设置。

5.2 要是你默认启用的是 Wayland，而 Qt 程序显示不正常

如果 Qt 程序在 Ubuntu 22.04 上出现界面模糊、缩放异常或无法输入等问题，很可能是 Wayland 会话导致的。你可以强制走 X11 方式运行：

./your_app -platform xcb

或者设置环境变量：

export QT_QPA_PLATFORM=xcb ./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这类错误，可以先检查动态库路径，而不是急着卸载重装。毕竟，工具链这东西，稳定是要求，顺手是运气，能自己排查才是真正的本事。