Ubuntu Qt 安装慢提速：换源、组件勾选与 aqtinstall 实践

新装完一台 Ubuntu，第一件事是配 Qt 环境，结果安装器进度条卡在 "Retrieving information from remote server" 那一行，去泡了杯咖啡回来还在转，再等半小时还是不动。这个场景我遇到过不止一次，也见过同事干脆放着跑一晚。Ubuntu 下 QT 安装慢并不是机器不行，绝大多数时候是下载链路、组件勾选和缓存策略三件事没安排明白。这篇就把我这几年前后装了几十次 Qt 的经验摊开讲清楚：慢在哪、怎么加快、哪些环节其实可以完全绕开，以及装完之后怎么验证没白装。不管你是刚接触 Qt 的学生，还是要在虚拟机里搭一套桌面开发环境的老手，下面这套流程都可以直接照抄。

1. 先定位耗时到底花在哪，别急着点"下一步"

很多人一上来就问"有没有更快的源"，但如果不先分清自己走的是哪条安装路线，换源可能一点用都没有。Qt 在 Ubuntu 上的安装方式本质上只有四条路，它们的耗时构成完全不同，优化手段也完全不一样。

1.1 四条安装路线的耗时构成对照

先用一张表把路线摆清楚，你可以直接对号入座。

看这张表就能明白一件事：如果你只是想在 Ubuntu 上用 qmake 或 CMake 编译一个 Qt 程序，走 apt 路线，十分钟以内就能干完，根本不需要去碰几个 G 的在线安装器。很多人之所以觉得"Qt 安装特别慢"，是因为默认选了最重的那条路。

1.2 Online Installer 到底在等什么

官方在线安装器慢，不是一个原因造成的，拆开看至少有五层。

第一层是拉取仓库索引。安装器启动后会先向远端请求组件清单（XML 格式的仓库元数据），这个请求要来回好几次，网络稍有抖动就会重试，界面上表现就是长时间停在 "Retrieving information from remote server"。

第二层是组件逐个下载。在线安装器的下载是近似串行的，一个压缩包下完再下一个，而 Qt 的单个组件包动辄几百 MB。假设单连接速度是 500 KB/s，下 3 GB 就是将近两个小时，这时候你换再快的 CPU、加再多内存都没意义。

第三层是下载和解压交替进行。它不是一个纯粹的下载任务，而是"下一个、解一个、下一个、解一个"，解压本身吃磁盘 IO，在机械盘或者虚拟磁盘上会明显拖后腿。

第四层是账号登录与校验。新版安装器强制登录账号才能继续，登录本身也要走网络请求。

第五层是磁盘写入路径。安装器会先把包放到临时目录再展开到目标目录，如果你的/tmp和安装目标是两个不同的分区，等于同样的数据写了两次。

把这五层拆开，对应的手段就清晰了：绕开索引请求、把串行下载变成多连接下载、把"下载"和"安装"解耦、换掉慢的写入路径。下面几节逐条落地。

1.3 Offline Installer 和 aqtinstall 为什么值得优先考虑

离线安装包的核心价值是把下载从安装过程里彻底剥离。你可以在任意时间、任意网络条件下把那个.run文件拉下来，校验完整性，然后再离线执行安装。安装过程本身不联网，也就不会出现"装到 60% 突然卡住重来"的情况。

需要说清楚的是，Qt 官方对开源用户提供的离线安装包，5.14.2 是一个比较关键的版本，之后的 5.15.2 虽然短暂放出过离线包，但后来下架了，这也是为什么现在搜索"qt 离线安装包下载 5.14"的人依然很多。如果你手上的项目没有强绑定 5.15 之后的特性，5.14.2 的离线包是一个非常务实的选择。

而 aqtinstall 是一个基于 Python 的命令行安装工具，它直接对接 Qt 官方的仓库结构，把包列表、下载、解压拆成可控的步骤。它最大的优势是可以精确指定要哪些归档（archive），比如你明确知道自己不用 Qt WebEngine，就可以完全不下载它，光这一项就能省掉将近一个 G。

2. 换源和 apt 参数调整，这一步收益最直接

如果你的需求落在"编译运行 Qt 程序"这个范围内，apt 路线是性价比最高的，而它提速的关键全在源和参数上。

2.1 Ubuntu 软件源替换：先确认你用的是哪种格式

Ubuntu 22.04 及以前，软件源是/etc/apt/sources.list；从 23.10 开始逐步切换到/etc/apt/sources.list.d/ubuntu.sources这种 deb822 格式。改之前先看一眼你的系统属于哪种。

# 判断格式 ls /etc/apt/sources.list.d/ubuntu.sources 2>/dev/null && echo "新格式" || echo "旧格式"

旧格式的替换方式：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list sudo sed -i 's|http://security.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list sudo apt update

新格式的替换方式（字段名是URIs:，不是deb http://...）：

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/ubuntu.sources sudo sed -i 's|http://security.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/ubuntu.sources sudo apt update

注意：改源之前一定先备份。sed是一次性全局替换，改错了想回滚，没有备份就只能重装系统源配置。

选镜像站的时候有个细节很多人忽略：不要把archive和security换成两个不同的站点。有些镜像站的security同步是有延迟的，混用之后会出现"某些安全更新拉不到"的怪问题。统一指向同一个站点最省事。

2.2 让 apt 少下载、多连接、不怕断

换完源，apt update的速度往往还是不够理想，因为它在下载一堆Translation索引文件——这些是软件描述的多语言翻译包，对安装本身毫无用处。关掉它们：

echo 'Acquire::Languages "none";' | sudo tee /etc/apt/apt.conf.d/99no-translations

这条配置我几乎每台新机器都会加，apt update的下载量能明显下降。

如果你的网络单连接速度一般，可以额外引入多连接下载。apt-fast是个常见选择，它本质上是把 apt 的下载环节替换成多连接的下载器：

sudo apt install -y aria2 apt-fast sudo sed -i 's/^_MAXCONNECTIONS=.*/_MAXCONNECTIONS=16/' /etc/apt-fast.conf sudo sed -i 's/^_DOWNLOADER=.*/_DOWNLOADER=aria2c/' /etc/apt-fast.conf

之后用apt-fast install代替apt install即可。实话说，对于几百 MB 的 Qt 开发包，apt-fast的收益是"能感觉到但没有质变"；它的真正优势在于一次性装几十个包、总量上 G 的场景。

还有一个容易被忽略的参数是重试次数。网络不稳的时候 apt 会因为一次失败就中断整个流程，加上重试能省掉重跑：

sudo apt -o Acquire::Retries=5 update sudo apt -o Acquire::Retries=5 install -y qtbase5-dev

2.3 apt 路线的最小安装集，别把文档包也背回家

这一步是很多人耗时的元凶。Ubuntu 上装qt5-doc、qt5-doc-html这类包，体积比开发库本身还大，而且是纯粹的网页文档。如果你不是离线查文档，直接跳过。

我常用的最小集是这样的：

# Qt5 + Qt Creator 最小开发环境 sudo apt install -y --no-install-recommends \ build-essential \ qtbase5-dev qtbase5-dev-tools \ qtchooser qt5-qmake \ qtcreator \ libqt5serialport5-dev

--no-install-recommends这个参数很关键，它会阻止 apt 把"推荐但非必需"的包也装上，文档包通常就是通过 recommended 依赖被带进来的。第一次用可能需要适应一下，但装完之后你会在磁盘占用上看得很直观。

几个必须单独装的模块，装之前先想清楚项目里有没有用到：

• libqt5serialport5-dev—— 串口通信，缺失时报Unknown module(s) in QT: serialport
• libqt5charts5-dev+qml-module-qtcharts—— Qt Charts 图表
• libqt5sql5-mysql/libqt5sql5-psql—— 对应数据库驱动
• qttools5-dev-tools—— 需要lupdate、lrelease做国际化时

再补一句版本相关的事。Ubuntu 22.04 之后已经没有qt5-default这个包了，网上很多老教程还在写sudo apt install qt5-default，跑起来会直接报"无法定位软件包"。这不是源的问题，是包在新版本里被拆掉了，用qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools这个组合替代就可以。

3. 组件勾选这一步，决定了你后面要不要重装一次

如果你确实需要用官方安装器拿一个特定版本的 Qt，那么组件勾选就是整篇里最值钱的一节。因为漏勾一个模块，代价不是"几分钟"，而是"重新跑一遍安装器验证并补下载"，而这个过程往往比第一次装还慢。

3.1 安装器组件树的四层结构

打开组件选择页面，那棵树看着乱，其实就四层：

• 第一层：Qt 版本。5.15.2、6.5.3 这种。你选了几个大版本，就有几套完整的库，体积翻倍。
• 第二层：编译器 / 目标平台。Desktop gcc 64-bit是我们在 Ubuntu 上要的那个。如果你不需要交叉编译，Android、iOS、WebAssembly 这些一律不勾。
• 第三层：模块（Modules）。Charts、Data Visualization、Virtual Keyboard、WebEngine 等等。
• 第四层：工具与源码。Qt Creator、Qt Designer、Sources、Debug Symbols。

新手最容易犯的错不是勾少了，而是勾多了。我见过有人把 5.15 和 6.2 两个大版本、再加 Android 和 WebAssembly 全勾上，安装体积直接冲到 10 GB 以上，装到一半磁盘不足失败。

3.2 一份可以直接照抄的桌面开发清单

假设你要做的是一个 Ubuntu 上的桌面程序，编译套件用系统自带的 GCC，目标就是 x86_64，那勾这些就够了：

Sources 这一项尤其要说。它下载的是 Qt 全部模块的源码包，体积非常大，而绝大多数人用不到——真要去翻 Qt 源码，直接在线看代码库更省事。Debug Symbols 同理，只在你要深入调试 Qt 内部行为时才需要。

3.3Unknown module(s) in QT: serialport为什么总在事后出现

这个报错几乎成了 Qt 新手的一道必修课。它的成因很简单：你的.pro文件里写了

QT += serialport

但当前使用的 Qt 环境里没有 QtSerialPort 这个模块。

问题在于，这个错误不是安装时出现的，而是你兴致冲冲新建工程、点编译时才出现的。于是你跑回去重新打开安装器，勾上模块，再走一遍"验证所有已安装组件、补下载、重新展开"的流程——这一步比第一次安装慢得多，因为安装器会逐个校验已有文件。

避免它的方法很朴素：在装的时候就按项目需求把模块勾全。如果你现在还不确定将来会不会用到串口，那就记住这个补救办法——apt 路线的环境直接补包：

sudo apt install -y libqt5serialport5-dev

安装器路线的环境则必须重新运行安装器的维护模式（Maintenance Tool），在"添加或移除组件"里补勾。

顺手把几个高频模块和它们在 apt 侧的对应关系列一下，装之前对照检查一遍，能省掉大量返工：

4. 把下载这件事单独拎出来做，速度差距最明显

前面反复提到"下载和安装解耦"，这一节说具体怎么做。

4.1 axel / aria2c / wget -c 的参数怎么选

如果你走的是离线安装包路线，第一步就是把.run文件拉下来。这里别再让浏览器单线程下载了，用命令行多连接工具，速度差别是肉眼可见的。

# axel：参数简单直接，-n 是连接数，-a 是显示进度条 axel -n 16 -a https://download.qt.io/archive/qt/5.14/5.14.2/qt-opensource-linux-x64-5.14.2.run

# aria2c：功能更强，-x 是单服务器最大连接数，-s 是分片数，-k 是分片大小 aria2c -x 16 -s 16 -k 1M https://download.qt.io/archive/qt/5.14/5.14.2/qt-opensource-linux-x64-5.14.2.run

# wget：最稳的兜底，-c 支持断点续传 wget -c https://download.qt.io/archive/qt/5.14/5.14.2/qt-opensource-linux-x64-5.14.2.run

关于连接数，我的经验是不要超过 16。开到 32 甚至 64 往往不升反降，因为服务器端和中间链路会对单 IP 的连接数做限制，连接被掐掉后重试的时间成本反而更高。从-n 8起步，逐步加到 16，找到一个稳定值就行。

另外提醒一个细节：axel对 HTTPS + 重定向的兼容性不如wget。如果你用的地址会跳转，先用wget -c更省心。

4.2 校验这一步别跳，否则可能白装一遍

大文件下载中断、被截断是常事。安装包如果不完整，表现往往是"安装器能启动，但装到某个组件时莫名报错"，甚至装完运行时崩溃。与其事后排查，不如装前校验一次：

# 先看官方提供的校验文件里对应的值 # 然后本地算一遍比对 sha256sum qt-opensource-linux-x64-5.14.2.run

对于 aqtinstall，它内置了校验逻辑，下载完会自动比对，这也是我用它做批量环境准备的原因之一——不用自己写校验脚本。

4.3 虚拟机里的隐形拖累：共享目录和虚拟磁盘

这一节专门写给在 VMware 里跑 Ubuntu 的人，因为这类环境下的"安装慢"往往和网络完全无关。

第一个坑：把安装包放在共享目录（/mnt/hgfs/...）里执行。共享目录是宿主机文件系统通过驱动挂载进来的，随机读写性能比原生虚拟磁盘差一大截。安装器在展开几万个文件的过程中，会在共享目录里做大量小文件写入，速度能慢到让人怀疑人生。正确做法是把安装包cp到虚拟机的家目录或/opt下再执行。

# 挪到本地磁盘再执行 cp /mnt/hgfs/share/qt-opensource-linux-x64-5.14.2.run ~/ cd ~ && chmod +x qt-opensource-linux-x64-5.14.2.run && ./qt-opensource-linux-x64-5.14.2.run

第二个坑：虚拟磁盘快照太多。每多一个快照，虚拟磁盘的写入路径就更长。装 Qt 这种大量小文件写入的操作，在累积了多个快照的磁盘上会明显变慢。装之前清理一下不用的快照，收益很直接。

第三个坑：磁盘空间预留不足。虚拟磁盘如果是按需增长模式，安装过程中会边写边扩，扩不动就会卡住。装之前先确认：

df -h ~ df -h /tmp

Qt 的完整安装建议预留 20 GB 以上，最小安装也要 10 GB。另外/tmp也看一眼，很多系统把它挂成 tmpfs（占内存），空间可能只有几 G，而安装器的临时文件默认就往那儿放。空间不够的话，用环境变量把它挪走：

mkdir -p ~/qt-tmp TMPDIR=~/qt-tmp ./qt-opensource-linux-x64-5.14.2.run

这个TMPDIR的用法我强烈建议记住，它不只对 Qt 安装有效，几乎所有大型安装程序都吃这个环境变量。

5. 卡住不动的现场，按这个顺序排查

即使前面都做对了，偶尔还是会遇到"不动"的情况。下面这套排查链路是我实际用过的顺序，从最可能的原因开始。

5.1 卡在 "Retrieving information from remote server" 或卡在登录

这个现象说明问题出在元数据请求阶段，跟你的磁盘、CPU 都没关系。

先做最基本的判断：换个时间或换个位置再试，网络高峰期的差异非常大。如果换了还是卡，那就是这条路走不通，直接换策略——把在线安装换成离线包或者 aqtinstall。在这一点上，不要在"怎么让在线安装器连上"上耗时间，投入产出比极低。

至于登录环节，官方安装器要求账号登录才能继续，这是它的既定流程，没什么可绕的。如果你的环境不方便走登录流程，aqtinstall 是更合适的选择，它基于命令行拉取仓库，不需要图形界面和账号交互。

5.2 卡在 99%、卡在"正在安装组件"

进度到 99% 卡住，通常是在展开文件的最后阶段，原因集中在两处：临时空间不足，或者目标分区的写入变慢。

排查顺序：

1. 开另一个终端看磁盘和 IO：df -h、iostat -x 2（没装的话sudo apt install sysstat）
2. 看安装器的临时目录还有多少空间：du -sh /tmp、df -h /tmp
3. 看是否有大量文件正在被写入：du -sh ~/Qt
4. 如果iostat显示%util长期接近 100% 而写入量很小，说明磁盘已经饱和，只能等，或者换一块盘

还有一种情况是权限问题导致的静默失败。安装器在写某个文件时没有权限，它不一定会立刻弹错，而是卡在那里反复尝试。如果你的安装目录在/opt下，需要提前把权限给到位：

sudo mkdir -p /opt/Qt sudo chown -R $USER:$USER /opt/Qt

我的习惯是干脆把 Qt 装在用户家目录下（~/Qt），完全绕开权限问题，重装系统时也方便保留。代价是家目录会变大，需要留意一下分区大小。

5.3 sudo 和普通用户混用的后果

这一条是很多人踩过但没意识到原因的坑：第一次用sudo跑安装器，第二次用普通用户跑，或者反过来。

后果有两层。第一层是文件属主混乱，之后 Qt Creator 读写配置可能报权限错误。第二层是缓存不复用——不同用户身份对应不同的配置和缓存目录，安装器不会复用上一次已经下载好的组件，等于从零再下一遍。

所以定一个规则并且坚持：要么全程普通用户 + 家目录，要么全程 sudo +/opt。我推荐前者。

顺便提一句环境变量的坑。用安装器装完 Qt 之后，qmake默认不一定在PATH里，直接敲命令会报"未找到命令"。解决办法有两条，选一条即可：

# 方案一：临时加到当前终端 export PATH=$HOME/Qt/5.15.2/gcc_64/bin:$PATH qmake -v # 方案二：写进 shell 配置，长期生效 echo 'export PATH=$HOME/Qt/5.15.2/gcc_64/bin:$PATH' >> ~/.bashrc source ~/.bashrc

如果你同时装了 apt 版和安装器版的 Qt，qmake -v显示的版本可能和你以为的不一样，因为两者都在PATH里。用qtchooser -list-versions查看当前系统识别到几个版本，需要切换时用qtchooser -set-default指定。这个细节在同时维护多个项目时很重要，我就因为没注意这个，在一个老项目上编了半天才发现用的是错的 Qt 版本。

5.4 aqtinstall 常见报错的处理

用 aqtinstall 的人容易撞上几个错，提前知道能省时间。

第一，Python 版本太老。aqtinstall 要求 Python 3.7 以上，Ubuntu 18.04 自带的 Python 可能不满足，先确认：

python3 --version

第二，pip 安装本身很慢。指定 PyPI 镜像：

pip3 install aqtinstall -i https://pypi.tuna.tsinghua.edu.cn/simple

第三，模块名写错。先用list-qt把可选的模块列出来，别靠猜：

aqt list-qt linux desktop --modules 5.15.2 gcc_64

第四，版本和架构组合不存在。同样先用命令确认：

aqt list-qt linux desktop --arch 5.15.2

确认完再执行安装：

aqt install-qt linux desktop 5.15.2 gcc_64 \ -O /home/$USER/Qt \ -m qtserialport qtcharts \ --base https://mirrors.tuna.tsinghua.edu.cn/qt

这里的--base指向一个仓库镜像，是把下载速度提上来的关键一项。-m后面是你要的额外模块，只写需要的，不写就是基础归档。

如果你想把体积压到极限，还有一个--archives参数，可以进一步限制只下载指定归档：

aqt install-qt linux desktop 5.15.2 gcc_64 \ -O /home/$USER/Qt \ --archives qtbase qtdeclarative qtcharts

注意：--archives裁剪得越狠，体积越小，但漏掉依赖时需要在代码编译阶段才发现。建议第一次先不加这个参数，等确认工程能跑通，再把这套命令固化到脚本里做瘦身。

6. 我现在固定用的一套流程

讲完原理和坑，把我现在给新机器配 Qt 环境的固定动作整理出来，你可以按需取用。

6.1 从零到能编译，我做这几步

第一步，先明确需求。只是编译 Qt 程序，还是要用 Qt Creator 做界面开发？前者走 apt，后者走安装器或 aqtinstall。这一步决定了后面所有操作。

第二步，换源并关掉翻译索引，两条命令：

sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list echo 'Acquire::Languages "none";' | sudo tee /etc/apt/apt.conf.d/99no-translations sudo apt update

第三步，装基础开发环境。build-essential一定要装，它包含 gcc、g++、make，缺了它后面编译任何 Qt 程序都会失败：

sudo apt install -y --no-install-recommends build-essential cmake git

顺带说一句 CMake 版本。Qt 5.15 对 CMake 要求不高，3.1 以上就行；但如果你的项目是 Qt 6 的，CMake 需要 3.16 以上，Ubuntu 18.04 自带的 3.10 是不够的，这时候要么升级系统，要么单独装新版 CMake。先确认一下版本再动手：

cmake --version

第四步，按路线安装 Qt 本体。apt 路线用前面那组包；需要特定版本就用 aqtinstall，命令也已经在上一节给全了。

第五步，验证。这一步千万别省，我见过好几次装完了但环境没配好、白折腾半天的。

6.2 装完之后的验证动作

先确认qmake能找到、版本对：

qmake -v which qmake

which qmake的输出能告诉你用的是哪一套 Qt，这一步能提前发现"装了新的但 PATH 还指着旧的"这种情况。

然后建一个最小工程，确认头文件和链接库都能用。写一个最简单的main.cpp：

#include <QApplication> #include <QImage> #include <QPainter> int main(int argc, char *argv[]) { QApplication app(argc, argv); QImage img(400, 200, QImage::Format_ARGB32); img.fill(Qt::white); QPainter painter(&img); painter.setRenderHint(QPainter::Antialiasing, true); painter.setPen(Qt::darkBlue); painter.drawLine(20, 100, 380, 100); painter.drawText(20, 40, QStringLiteral("Qt 环境验证通过")); painter.end(); img.save(QStringLiteral("verify.png")); return 0; }

配套一个verify.pro：

QT += core gui CONFIG += console c++11 TARGET = verify TEMPLATE = app SOURCES += main.cpp

然后编译运行：

qmake verify.pro make -j$(nproc) ./verify

这里用QPainter而不是只写一个qDebug()，是有意为之。QPainter会实际调用到 GUI 渲染相关的库，能顺带确认图形栈没有问题。如果你后面要做的正好是图形绘制相关的工作，这一步也是检查渲染是否正常的最小手段——相对QGraphicsView那一套场景图机制，直接拿QPainter画到QImage上是最轻量的验证方式，几百毫秒就能出结果。

最后确认一下你需要的模块确实在：

# 看 Qt 安装目录下有没有对应的库文件 ls $HOME/Qt/5.15.2/gcc_64/lib | grep -i serialport ls $HOME/Qt/5.15.2/gcc_64/lib | grep -i charts

输出了libQt5SerialPort.so之类的文件，说明模块装到位了。这个检查比"编译时报错再回头找"要省事得多。

6.3 后面需要加模块怎么办

这件事早晚会遇到，提前想清楚能少走弯路。

apt 路线的环境最简单，缺什么补什么，sudo apt install libqt5xxx-dev一条命令搞定，通常几秒钟。

安装器路线的环境，需要找到安装目录下的MaintenanceTool并运行：

$HOME/Qt/MaintenanceTool

进去之后选"添加或移除组件"。要有心理准备：这一步会先校验所有已安装文件，校验本身就要花几分钟，然后才下载新增组件。所以前面反复强调"一次勾全"。

aqtinstall 路线的环境，直接再跑一次安装命令，把新模块加到-m后面：

aqt install-qt linux desktop 5.15.2 gcc_64 -O /home/$USER/Qt -m qtserialport qtcharts qtvirtualkeyboard

它会识别已存在的文件，只补下载缺失的部分，速度比前两种都快。这也是我后来逐渐偏向 aqtinstall 的原因——它的增量行为是可预期的，不像图形安装器那样每次都做一遍全量校验。

最后分享一个我自己用下来最省时间的组合：在家目录下用 aqtinstall 装基础 Qt，模块用-m精确追加，apt 只负责build-essential和 CMake 这类系统级工具。这套组合让我在一台全新的 Ubuntu 虚拟机上，从系统装好到第一个 Qt 工程编译通过，控制在四十分钟以内，其中大部分时间花在下载上，而且中间断了可以随时续，不用从头再来。真正需要避免的，是反复重启在线安装器然后等它自己好起来——那才是时间黑洞。