企业官网建设流程全解析

这篇文章可能比较长，但每一节都是实际踩坑后沉淀下来的东西。很多人在 Ubuntu 上装 Qt，卡住的不是安装包本身，而是装完之后冒出来的各种环境问题：qmake 版本不对、串口模块找不到、中文输入法打不出字、Qt Creator 里 Kit 是空的。这篇就围绕这些内容，从版本选择、下载源、依赖安装，到环境变量、串口模块修复、周边配置，完整走一遍。

1. 动手前把版本和需求理清楚

1.1 先搞清楚你要的是 Qt 库，还是 Qt Creator 这个 IDE

这是新手最容易混的一点。大家嘴里说的“装 Qt 环境”，其实包含两样东西：一是 Qt 开发库本身（包括 qmake、头文件、编译好的库文件），二是 Qt Creator 这个图形化 IDE。两者是独立的，你可以只用 qmake 配合 Vim 和终端来写 Qt 程序，也可以把 Qt Creator 单独装好，然后在里面配置不同版本的 Qt 库。官方安装器默认会把这两个一起装好，但如果你走 APT 安装，就需要分别装 qtbase5-dev（库）和 qtcreator（IDE）。我见过有人只装了 qtcreator，然后新建项目时报“No valid kits found”，就是因为系统里没有对应的 Qt 库。

所以在动手之前，先问自己三个问题：要在什么 Ubuntu 版本上装？要写的程序跑在什么平台（纯 Linux 桌面、嵌入式 ARM 板、还是 Windows 交叉编译）？项目需要用到哪些 Qt 模块（Widgets、QML、SerialPort、Network）？这三个问题的答案直接决定你装哪个版本、选哪些组件。

1.2 Ubuntu 版本和 Qt 版本的匹配关系

Qt 官方对 Ubuntu 版本没有严格的强制绑定，但不同 Ubuntu 自带的 GCC、OpenGL 库、xcb 相关依赖版本不同，会影响 Qt 跑起来的表现。我的经验是：Ubuntu 20.04 装 Qt 5.15.2 是最稳的组合，Ubuntu 22.04 装同样版本也能跑，但需要额外补一个 xcb-cursor 库，否则程序启动会直接报缺库。

如果你做的是工业上位机、串口调试助手、Modbus 采集这类项目，我强烈建议选 Qt 5.15.2。不是 Qt 6 不好，而是大量第三方库、设备厂商的 SDK 还停留在 5.x，而且串口、Modbus 相关的示例代码网上最多的是 5.x 的写法。4K 分辨率下 Qt 5.15 的缩放也比早期版本好了很多，日常开发完全够用。

1.3 为什么我推荐 5.15.2，以及从哪里拿离线包

Qt 5.15.2 是 5.x 系列里最后一个对所有人开放的完整离线安装包版本。从 5.15.3 开始，官方安装器要求商用账号（虽然可以编译源码，但对绝大多数人来说没必要折腾）。5.15.2 作为 5.x 里最后的全开放版本，稳定性和资料丰富度都到了顶峰，这也解释了为什么网上搜索“qt 5.15.2 下载安装”的热度一直居高不下。

下载地址直接走国内镜像就好，官方站点的下载速度实在感人。清华、中科大、阿里云、腾讯都有 Qt 的镜像，路径结构基本一样：

# 清华镜像 Qt 5.15.2 离线安装包 https://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/5.15/5.15.2/qt-opensource-linux-x64-5.15.2.run

这个文件大约 1GB 左右，建议用浏览器直接下或者 wget 都行。下载完成后，先给执行权限，再运行：

chmod +x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run

2. 安装 Qt 环境的核心流程

2.1 安装系统依赖库（别跳过）

这是最容易踩坑的一步。很多人直接运行安装包，装完 Qt 之后新建项目一编译，程序启动时弹出一句：

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

这就是典型的系统缺少 xcb 相关库。Qt 在 Linux 下通过 xcb 插件和 X Window 通信，Ubuntu 默认不会把所有 xcb 相关的开发库都装好。所以运行安装包之前，先把依赖补齐：

sudo apt update sudo apt install build-essential libgl1-mesa-dev libfontconfig1 \ libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 \ libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ libxcb-shape0 libxcb-xinerama0 libxcb-xkb1 \ libxcb-cursor0

这里提一下 libxcb-cursor0 这个包。如果你在 Ubuntu 22.04 上装完 Qt 5.15.2，启动程序报错提示找不到 libxcb-cursor.so.0，就是因为缺少这个库。Ubuntu 20.04 没这个问题，22.04 开始 xcb 相关依赖拆分更细了。这是我在 22.04 上一个一个试出来的。

还有一个容易忽略的问题：如果你用的 Ubuntu 是最小化安装（Minimal Install），系统可能没有安装桌面相关的字体渲染库，Qt 程序界面会出现方块字。这种情况直接装一下字体库就好：

sudo apt install fontconfig libfreetype6

2.2 运行离线安装包并选择组件

运行安装包后，图形化向导会让你登录 Qt 账号。这里要注意：安装 5.15.2 时它默认不强制登录，如果界面要求登录，断开网络再试一次或直接选 Skip。登录步骤是用来下载额外组件的，对于离线包完全没有必要。

组件选择页是关键。很多人一上来全选，装完发现磁盘占用十几GB，而且编译时也用不到。我建议按需选择：

• 如果你做桌面应用：选 Qt 5.15.2 下的 Desktop gcc 64-bit
• 如果你可能用到串口、Modbus：展开 Qt 5.15.2，勾选 Qt Serial Port、Qt Serial Bus
• Qt Creator 组件：默认勾选即可，里面包含了 Qt Creator IDE 和调试工具
• Sources 组件：建议勾上，后面二次编译排查问题的时候用得上

组件一共约 3~4GB 左右，视选择不同有变化。装完后默认路径在 ~/Qt/5.15.2/gcc_64，记住这个路径，后面配置环境变量和 Qt Creator Kit 会用到。

2.3 在 Ubuntu 上使用 APT 安装 Qt 的另一种选择

官方安装包适合想用最新版或者特定版本的人。但对于很多服务器场景，或者你只是想在 Ubuntu 上编译别人已经写好的 Qt 项目，APT 安装其实更快、更省事，而且和系统包管理整合得更好：

sudo apt install qtbase5-dev qt5-qmake qtchooser qtcreator sudo apt install libqt5serialport5-dev libqt5serialport5

这种装法会把 Qt 库放在系统目录 /usr/lib/x86_64-linux-gnu/qt5 下，头文件在 /usr/include/x86_64-linux-gnu/qt5，qmake 命令也直接注册到了系统里。优点是升级、卸载都很干净，缺点是可选的模块比官方安装器少，比如一些 Qt Charts、Qt Data Visualization 要单独 apt 安装。

两种方式可以共存吗？可以，但不建议新手上来就同时搞两套，因为 qmake 路径、库路径会打架。我自己的习惯是：开发机上用官方安装包（灵活、组件全），编译服务器上用 APT（干净、自动化方便）。

3. 环境变量、qmake 和 Qt Creator 的版本关系

3.1 环境变量配置的正确姿势

装完官方安装包后，如果你直接在终端输入 qmake，大概率会提示命令未找到。这是因为 Qt 安装目录下的 bin 路径还没有加入 PATH。网上很多教程让你把这一行加到 ~/.bashrc：

export PATH=$PATH:~/Qt/5.15.2/gcc_64/bin

这本身没错，但要注意两点：一是 PATH 的追加顺序，写在前面；二是这行只对终端会话生效，如果从图形界面启动 Qt Creator，它不一定加载到你当前用户的 bash 配置。

更稳妥的做法有两种。如果你需要全局生效，编辑 /etc/environment，把路径加进去后重新登录；如果你不想影响系统全局，就在 ~/.bashrc 里追加之后执行 source ~/.bashrc：

echo 'export PATH=$HOME/Qt/5.15.2/gcc_64/bin:$PATH' >> ~/.bashrc source ~/.bashrc

然后验证：

qmake --version g++ --version

qmake 的输出应该显示 Qt 版本和安装路径。这里我补充一个判断小技巧：如果 qmake 的路径显示是 /usr/bin/qmake（而不是你安装目录下的那个），说明系统里有 Qt 的 APT 包或者之前装过别的 Qt，PATH 里 /usr/bin 优先级更高。

3.2 Qt Creator 和 Qt 库的对应关系

进入 Qt Creator 后，过菜单 Tools -> Options -> Kits -> Qt Versions，你会看到它把系统里能检测到的所有 Qt 版本都列出来了。很多人这时候困惑“qtcreator 对应 qt 版本”到底怎么选，其实它们之间没有严格的一一绑定。Qt Creator 是个 IDE，可以管理多个 Qt 库版本；某个 Qt 库也能被多个版本的 Creator 打开。

真正影响编译的是 Kit（套件）里的配置。一个 Kit 由三部分决定：编译器（GCC）、调试器（GDB）、Qt 库版本（qmake 路径）。只要这三者匹配，Qt Creator 版本稍微新一点旧一点都无所谓。

打开 Tools -> Options -> Kits，在 Qt Versions 页点 Add，选择你安装目录下的 qmake。比如官方安装包就是 ~/Qt/5.15.2/gcc_64/bin/qmake；APT 装的就是 /usr/bin/qmake。加完之后回到 Kits 页面，把默认的 Desktop 套件里的 Qt Version 选成你刚加的那个，编译器选 GCC。

3.3 同时存在多个 Qt 版本时的切换

如果你的系统里既有 APT 装的 Qt 5，又有官方安装包装的 Qt 5.15.2，终端下默认 qmake 指向谁，取决于 PATH 和 qtchooser 的配置。Ubuntu 的 APT 包自带了一个 qtchooser 工具：

# 查看当前默认的 Qt 版本 qmake --version # 列出系统里所有可用的 Qt 版本 qtchooser -list-versions

qtchooser 的配置文件存放在 /usr/lib/x86_64-linux-gnu/qtchooser 或 /etc/xdg/qtchooser 下。如果你想让终端下某个应用使用特定版本，可以通过环境变量强制指定：

export QT_SELECT=5.15.2

但实际开发中我更推荐一个土办法：打开 Qt Creator，在 Kit 里直接指定每个项目用哪个 qmake，不需要在系统层面纠结默认指向。终端编译时也一样，直接用完整路径调用 qmake：

~/Qt/5.15.2/gcc_64/bin/qmake your_project.pro make -j$(nproc)

避免用裸的 qmake 命令去编译，因为你不确定它指向的是哪个版本。这种显式指定比折腾环境变量要省心得多。

4. 串口模块缺失的解决思路

4.1 报错背景和产生原因

很多人在 Ubuntu 上做串口上位机时会卡在一个报错上：

Project ERROR: Unknown module(s) in QT: serialport

这个报错不管你是用官方安装包还是 APT 装的 Qt，都可能遇到。原因其实不复杂：官方离线安装包里，Qt Serial Port 这个模块默认不是必选组件，你在安装向导里如果没手动勾选，装完自然找不到；APT 方式装 qtbase5-dev 时，默认只装了基础模块，串口属于附加模块库，需要单独装。

另一个隐蔽的原因是多版本 Qt 共存导致的头文件和库路径错位。比如 qmake 是官方安装包的 5.15.2，但编译器搜索头文件的路径里没有 QtSerialPort 这个目录，或者链接时找不到 libQt5SerialPort.so。它会直接导致你用 qmake 构建时报“Unknown module”，但你在安装目录里明明看到了 Qt Serial Port 的文件夹。

4.2 解决步骤与验证

最干净的解决办法是按模块补齐。如果你是 APT 安装的 Qt：

sudo apt install libqt5serialport5-dev libqt5serialport5

如果你用的是官方安装包，先确认安装目录里有没有 QtSerialPort：

ls ~/Qt/5.15.2/gcc_64/include/QtSerialPort ls ~/Qt/5.15.2/gcc_64/lib/libQt5SerialPort*

如果不存在，回到安装向导里重新运行维护工具（MaintenanceTool，在 ~/Qt 目录下），Add or remove components，勾选 Qt Serial Port 后更新。如果文件存在但 qmake 依然报 Unknown module，多半是路径配置问题，我遇到过一次是因为同时装了 APT 版和官方版，qmake 用了 APT 的，但模块文件是官方版的。此时把 qmake 路径改成官方安装目录下的那个，或者在项目文件里直接指定：

QT += core serialport

改完之后先 qmake 再 make：

~/Qt/5.15.2/gcc_64/bin/qmake serial_demo.pro make -j$(nproc)

编译通过后，验证运行环境里能不能找到动态库：

ldd ./serial_demo | grep serialport

看到 libQt5SerialPort.so.5 就说明库链接正常了。

4.3 一段最小可用验证代码

为了确认串口模块真的能用，我一般会在测试项目里写一个最小的串口枚举程序，跑通了再继续写业务逻辑。代码很简单：

#include <QCoreApplication> #include <QSerialPortInfo> #include <QDebug> int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); const auto infos = QSerialPortInfo::availablePorts(); qDebug() << "Available serial ports:" << infos.size(); for (const QSerialPortInfo &info : infos) { qDebug() << "Port:" << info.portName() << "Description:" << info.description() << "Vendor ID:" << info.vendorIdentifier(); } return 0; }

如果你插了一个 USB 转串口设备，跑起来能看到设备列表，就说明 serialport 模块整个链路（头文件、库、运行环境）已经通了。注意 Ubuntu 下如果看不到 USB 转串口设备，先检查系统有没有权限读 /dev/ttyUSB0 或 /dev/ttyACM0，通常要把当前用户加入 dialout 组：

sudo usermod -aG dialout $USER

加完重新登录，串口才能真正打开。

5. 常见问题速查与周边环境配置

5.1 中文输入法装好之后 Qt Creator 里打不出中文

这个问题搜索“ubuntu中文输入法怎么设置”的人特别多。装好搜狗输入法或 fcitx 输入法框架后，系统自带的文本编辑器能打入中文，但 Qt Creator 里按 Ctrl+Space 没有反应或候选框不出现，原因是 Qt 程序启动时没有加载输入法模块。

解决方法是设置输入法模块的系统环境变量，我推荐写到 /etc/environment，这样不管从桌面启动还是终端启动都生效：

GTK_IM_MODULE=fcitx QT_IM_MODULE=fcitx XMODIFIERS=@im=fcitx

如果你用的是 ibus 输入法，把 fcitx 换成 ibus 即可。改完重启系统或者重新登录，Qt Creator 里就能正常调出中文候选了。这里有个细节：如果你只是 export 到 ~/.bashrc，从终端敲命令行启动 Qt Creator 才会生效，但在桌面应用菜单里点图标启动，依然不行，这是很多人的困惑点。

还有一种方式是在 Qt Creator 的快捷方式文件里设置环境，但操作起来比较麻烦。直接在系统层面设置输入法模块是通用做法，我在 Ubuntu 20.04 和 22.04 上都验证过可行。

5.2 SSH 突然连不上 Ubuntu

开发过程中经常会有“ubuntu ssh无法连接”的搜索。大多数情况不是密码错了，而是 OpenSSH Server 根本没安装，或者防火墙拦截了 22 端口。排查顺序：

# 1. 检查 sshd 是否在运行 systemctl status ssh # 2. 检查 22 端口是否监听 ss -tlnp | grep 22 # 3. 如果没有，先安装 sudo apt install openssh-server sudo systemctl enable --now ssh # 4. 防火墙放行 SSH sudo ufw allow OpenSSH sudo ufw enable

Ubuntu 桌面版默认不带 SSH 服务端，这是最常见的原因。装好之后注意，如果之前改过 SSH 端口，客户端连接时也要指定 -p 端口。另外记得确认一下客户端的 RSA 公钥是否已经 copy 到服务器的 ~/.ssh/authorized_keys 里，这些都排除了基本就能连上了。

5.3 在虚拟机上安装 Ubuntu 后画面卡顿、拖拽不便

很多读者是在 VMware 虚拟机里装完 Ubuntu，然后开始折腾 Qt，画面卡、分辨率低、复制粘贴失灵这些体验问题一开始就劝退了好多人。我的建议是装 open-vm-tools-desktop，而不是按照老教程去 VMware 菜单里 Install VMware Tools：

sudo apt install open-vm-tools-desktop

装好后重启虚拟机，分辨率会自适应，剪贴板共享、文件拖拽都能用了。给虚拟机的资源分配上，至少 2 核 CPU、4GB 内存，编译 Qt 项目才不至于卡得怀疑人生。如果你还打算在虚拟机里跑 Qt Creator 并打开较大项目，建议磁盘用 SSD，内存给到 6~8GB 更舒服。

5.4 Ubuntu 下安装 Docker 与 Qt 环境的配合

嵌入式开发或者 CI 编译里经常要装 Docker。在 Ubuntu 上安装 Docker 的关键步骤就三步：

sudo apt update sudo apt install ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

然后增加 Docker 软件源，安装就行。常规 apt 仓库里的 docker.io 版本偏旧，不推荐。装完如果拉取镜像慢，可以配置 registry-mirrors，这个在 /etc/docker/daemon.json 里指定镜像加速地址即可。

如果你是在 Docker 容器里编译 Qt 项目，注意装好所有基础依赖，推荐镜像直接拉 ubuntu:20.04，然后按前面 APT 的方式装 qtbase5-dev 和对应模块，就能当一个干净的编译环境用了。

5.5 CMake 版本过旧导致的构建问题

Ubuntu 20.04 默认的 CMake 是 3.16.3，Ubuntu 22.04 是 3.22.1。Qt 5.15 的项目用 CMake 3.16 基本没问题，但如果拉下来的第三方库要求 CMake 3.21+，这时候建议单独装新版，不要动系统自带的：

sudo apt install python3-pip pip install cmake --upgrade

装完后 which cmake 会指向 python 的 bin 目录，Qt Creator 里在 Tools -> Options -> Kits -> CMake 添加这个新版本路径就行。实测新版 CMake 对 Qt 6 支持和 Qt 5 的兼容性都更好。

6. 装好之后的下一步建议

很多人在装好环境后会立刻去搜“qt读写json”“qt获取文件信息”“qt绘图效率比较”“用qt左右平滑滑动的卡片列表”这些词。我的建议是，先别急着堆功能。先把第一个最简单的 QWidget 项目跑通，完成一次 新建项目 -> 写代码 -> qmake -> make -> 运行 的闭环，确认 IDE 和终端两条编译链路都通，再开始做功能。

Qt 的绘图效率问题（特别是 QPainter 实时刷新和曲线绘制卡顿）是后面几乎一定会遇到的坎。如果做数据采集显示，优先把数据获取和界面刷新分离，曲线控件 update() 和 replot() 的区别要搞清楚，数据量大了放子线程里做预处理再通过信号槽抛给界面。这些都是环境搭好之后才会暴露的问题，提前了解能少走很多弯路。

我个人的经验是：Ubuntu 上 Qt 环境的搭建，真正的难点不在于安装包本身，而在于依赖的完整性、模块的按需补齐和版本路径的清晰管理。把这篇文章里的依赖安装、模块校验、环境变量设置这几步做扎实，后面开发会顺畅很多。遇到问题时，先 qmake --version 确认版本路径，再 ldd 确认运行库，基本能定位九成问题。