保姆级避坑指南：Ubuntu 20.04 LTS源码编译Qt 5.15.2全流程

1. 为什么选择源码编译Qt 5.15.2？

在Ubuntu 20.04 LTS上安装Qt通常有两种方式：通过apt安装预编译版本，或者从源码编译安装。源码编译虽然步骤繁琐，但能带来三个关键优势：版本可控（官方仓库的Qt版本往往较旧）、功能定制（可以按需启用/禁用模块）、深度优化（针对当前硬件环境编译性能更好）。我在多个嵌入式项目中发现，源码编译的Qt程序运行效率比仓库版本平均提升15%-20%。

不过源码编译最大的痛点就是依赖问题。网上很多教程只列出基础依赖，实际编译时总会遇到各种报错。我花了三天时间反复测试，整理出这份完整依赖清单+避坑指南。跟着做，90%的常见错误都能避免。

2. 环境准备与源码下载

2.1 系统基础配置

首先确认系统版本：

lsb_release -a

输出应包含"Ubuntu 20.04 LTS"。虽然Qt 5.15.2官方最低要求是18.04，但实测20.04的软件包兼容性更好。

建议先更新系统：

sudo apt update && sudo apt upgrade -y

2.2 下载Qt源码

官方源码包有两个下载渠道：

1. 商业版（需要账号登录）
2. 开源版（推荐）

获取开源版源码：

wget https://download.qt.io/archive/qt/5.15/5.15.2/single/qt-everywhere-src-5.15.2.tar.xz

下载完成后验证完整性：

sha256sum qt-everywhere-src-5.15.2.tar.xz

正确哈希值应为：3db4c729b4d80a9d8fda8dd77128406353baff4755ca619177eda4cddae71269

注意：国内用户如果下载慢，可以使用清华镜像源替换URL中的download.qt.io为mirrors.tuna.tsinghua.edu.cn/qt

3. 安装编译依赖（完整版）

3.1 基础编译工具链

必须安装的编译器工具：

sudo apt install -y build-essential gcc g++ make cmake

3.2 Qt核心依赖库

这是最容易出问题的部分，我整理了完整依赖清单：

sudo apt install -y \ libxcb* \ libx11-xcb-dev \ libxkbcommon-x11-dev \ libxrender-dev \ libgl1-mesa-dev \ libglu1-mesa-dev \ libegl1-mesa-dev \ freeglut3-dev \ libfontconfig1-dev \ libfreetype6-dev \ libx11-dev \ libxext-dev \ libxfixes-dev

3.3 可选功能依赖

如果需要WebEngine、多媒体等模块，还需额外安装：

sudo apt install -y \ libssl-dev \ libdbus-1-dev \ libicu-dev \ libpulse-dev \ libasound2-dev \ libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev

实测发现：缺少libxkbcommon-dev会导致XCB插件编译失败，而网上90%的教程都没提到这个依赖

4. 配置与编译实战

4.1 解压源码并初始化

解压源码包（建议在home目录操作）：

tar -xvf qt-everywhere-src-5.15.2.tar.xz cd qt-everywhere-src-5.15.2

4.2 关键配置参数

推荐使用以下配置命令：

./configure \ -prefix /opt/Qt5.15.2 \ -opensource \ -confirm-license \ -xcb \ -nomake examples \ -nomake tests \ -skip qtdoc

参数说明：

• -prefix：指定安装路径（避免污染系统目录）
• -xcb：强制使用XCB后端（解决Ubuntu下常见显示问题）
• -nomake：跳过示例和测试（节省编译时间）

4.3 常见配置错误处理

如果配置失败，按以下步骤排查：

1. 查看config.log最后20行错误信息
2. 安装缺失的依赖（通常是libxxx-dev格式的包）
3. 清除缓存后重试：

rm -rf config.cache ./configure ...

5. 编译与安装

5.1 多线程编译

使用make的-j参数加速编译（根据CPU核心数调整）：

make -j$(nproc)

我的Ryzen 7 5800H（8核16线程）完整编译耗时约1小时20分钟。

重要：如果编译中途报错，不要直接重新make。先执行make clean再重新开始

5.2 安装到系统

编译完成后执行：

sudo make install

这会将所有文件安装到之前-prefix指定的目录（本例为/opt/Qt5.15.2）

6. 环境配置与测试

6.1 设置默认Qt版本

安装qtchooser工具：

sudo apt install qtchooser

创建配置文件：

qtchooser -install qt5.15.2 /opt/Qt5.15.2/bin/qmake echo "export QT_SELECT=qt5.15.2" >> ~/.bashrc source ~/.bashrc

验证安装：

qmake -v

应显示"QMake version 3.1"和"Using Qt version 5.15.2"

6.2 永久环境变量配置

编辑/etc/profile文件：

sudo nano /etc/profile

在末尾添加：

export QTDIR=/opt/Qt5.15.2 export PATH=$QTDIR/bin:$PATH export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH

7. 字体问题终极解决方案

7.1 字体缺失现象

编译测试程序时常见两种问题：

1. 窗口显示空白（无文字）
2. 控制台警告"QFontDatabase: Cannot find font directory"

7.2 永久修复方案

创建字体链接（比复制字体更优雅）：

sudo ln -s /usr/share/fonts /opt/Qt5.15.2/lib/fonts

如果仍不生效，可以手动指定字体路径：

QApplication::setFont(QFont("Arial")); QApplication::addLibraryPath("/usr/share/fonts");

8. 开发实战：创建第一个Qt程序

8.1 标准项目结构

建议按以下结构组织代码：

myproject/ ├── src/ │ └── main.cpp ├── include/ ├── resources/ └── myproject.pro

8.2 示例CMake配置

现代Qt项目推荐使用CMake：

cmake_minimum_required(VERSION 3.5) project(MyProject LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) find_package(Qt5 COMPONENTS Core Widgets REQUIRED) add_executable(myapp src/main.cpp) target_link_libraries(myapp Qt5::Core Qt5::Widgets)

8.3 编译运行

创建build目录进行编译：

mkdir build && cd build cmake .. make -j$(nproc) ./myapp

9. 高级技巧与性能优化

9.1 选择性编译模块

通过configure参数可以禁用不需要的模块：

-skip qt3d -skip qtwebengine -skip qtmultimedia

完整模块列表可通过./configure --help查看

9.2 编译器优化选项

在configure前设置：

export CXXFLAGS="-O3 -march=native" export CFLAGS="-O3 -march=native"

这能提升10%-15%的运行性能

9.3 调试版本配置

开发时建议使用：

./configure -debug -separate-debug-info

会生成带调试符号的二进制文件

10. 常见问题排查手册

10.1 XCB插件加载失败

错误现象：

Could not load the Qt platform plugin "xcb"

解决方案：

export QT_DEBUG_PLUGINS=1 ./myapp

根据输出检查缺少的库

10.2 OpenGL相关错误

如果出现GLX错误，尝试：

./configure -opengl desktop

10.3 多版本Qt共存

通过qtchooser管理多个版本：

qtchooser -list-versions qtchooser -set-default qt5.15.2

11. 维护与升级

11.1 安全清理

删除源码和编译中间文件：

cd ~ rm -rf qt-everywhere-src-5.15.2*

11.2 卸载Qt

直接删除安装目录：

sudo rm -rf /opt/Qt5.15.2

并清理环境变量中的相关配置

12. 实际项目经验分享

在嵌入式设备上部署Qt时，我推荐添加这些configure参数：

-release -optimize-size -no-pch -qt-zlib -qt-libpng -qt-libjpeg

能显著减少二进制体积。有个项目通过参数优化，最终镜像大小从87MB降到了52MB。

遇到最棘手的问题是触摸屏校准，后来发现需要特别编译tslib支持：

./configure -tslib -I /usr/include/tslib -L /usr/lib/arm-linux-gnueabihf

字体问题在ARM设备上更复杂，最终方案是将字体编译进资源文件：

<RCC> <qresource prefix="/fonts"> <file>fonts/NotoSansCJK-Regular.ttc</file> </qresource> </RCC>