在 Ubuntu 24.04 中编译 Qt 5.15.2 项目完全指南

1. 前言

在跨平台开发中，许多团队选择在 Windows 上编写代码，在 Linux 上编译和部署 Qt 项目。本文将详细介绍在 Ubuntu 24.04 环境下，从零开始搭建 Qt 5.15.2 编译环境的方法，并给出所有必需的依赖包、下载链接以及详细的步骤说明，帮助你将 Windows 上开发的 Qt 项目顺利迁移到 Linux 编译。

在阅读过程中，你可以根据需要在对应位置插入截图。文中已预留了图片插入位置，方便你记录操作过程。

2. 环境准备总览

在开始之前，我们需要准备好以下核心组件：

图片插入位置：此处可插入一张 Ubuntu 24.04 系统信息截图或 Qt 5.15.2 官方发布页面截图。

3. 系统基础依赖安装

首先更新系统包列表，并安装编译 Qt 所必需的基础开发工具和库。打开终端，依次执行以下命令：

sudoaptupdatesudoaptinstall-ybuild-essential perl python3gitsudoaptinstall-ylibfontconfig1-dev libfreetype6-dev libx11-dev\libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev\libxrender-dev libxcb1-dev libxcb-glx0-dev libxcb-keysyms1-dev\libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev\libxcb-sync0-dev libxcb-xfixes0-dev libxcb-shape0-dev\libxcb-randr0-dev libxcb-render-util0-dev libxcb-util0-dev\libxcb-xinerama0-dev libxcb-xkb-dev libxkbcommon-dev\libxkbcommon-x11-dev

图片插入位置：此处可插入终端执行sudo apt install命令时的截图。

接着安装 OpenGL、SSL 和多媒体相关依赖：

sudoaptinstall-ylibgl1-mesa-dev libglu1-mesa-devsudoaptinstall-ylibssl-dev libopenal-dev libpulse-dev\libasound2-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

图片插入位置：可插入依赖安装过程中终端输出的截图。

4. 下载 Qt 5.15.2 源码

所有 Qt 版本均通过官方下载页提供。请注意，Qt 5.15.2 属于 LTS 版本，需要持有 Qt 账号才能从官方仓库下载。如果你没有商业许可，也可以使用社区维护的镜像或第三方源。

4.1 官方下载（推荐）

1. 访问 Qt 官方下载页面：
   https://download.qt.io/archive/qt/5.15/5.15.2/
2. 选择single目录下的qt-everywhere-src-5.15.2.tar.xz源码包。
3. 直接使用 wget 下载：

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

图片插入位置：此处可插入 Qt 下载页面中 5.15.2 源码包高亮显示的截图。

4.2 备用下载

如果官方下载速度较慢，也可以使用国内镜像，例如：

• 清华大学开源镜像站：
  https://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/5.15/5.15.2/single/
• 中科大镜像站：
  https://mirrors.ustc.edu.cn/qtproject/archive/qt/5.15/5.15.2/single/

5. 解压并配置编译选项

下载完成后，解压源码包，并进入目录：

tar-xfqt-everywhere-src-5.15.2.tar.xzcdqt-everywhere-src-5.15.2

Qt 源码使用configure脚本进行配置。你可以根据项目需求定制编译选项。下面是一个常用的配置命令，它包含了大多数桌面应用所需的模块：

./configure-prefix/opt/Qt5.15.2\-release\-opensource\-confirm-license\-nomakeexamples\-nomaketests\-skipqtwebengine\-qt-zlib\-qt-libpng\-qt-libjpeg\-qt-freetype\-qt-harfbuzz\-qt-pcre\-xcb\-xcb-xlib\-bundled-xcb-xinput\-ssl\-opengldesktop

参数说明：

• -prefix /opt/Qt5.15.2：安装路径，你可以根据个人习惯修改。
• -skip qtwebengine：跳过体积庞大的 QtWebEngine，如果项目不需要可以跳过，大幅缩短编译时间。
• -opengl desktop：使用桌面 OpenGL，避免依赖 EGL 等额外库。

图片插入位置：此处可插入终端中运行 configure 命令时的输出截图。

6. 编译与安装

配置成功后，屏幕会显示 Qt 的配置摘要。确认无误后，开始编译。编译时间取决于机器性能，通常需要 30 分钟到数小时不等。

make-j$(nproc)

-j$(nproc)会使用所有可用 CPU 核心加速编译。编译完成后，安装到指定目录：

sudomakeinstall

图片插入位置：可插入编译过程中的进度截图，以及安装完成后的提示信息截图。

7. 配置环境变量

安装完成后，为了在终端直接使用qmake或qmake5命令，需要将 Qt 的 bin 目录加入PATH环境变量。编辑~/.bashrc文件，在末尾添加以下内容：

exportPATH=/opt/Qt5.15.2/bin:$PATHexportLD_LIBRARY_PATH=/opt/Qt5.15.2/lib:$LD_LIBRARY_PATHexportQT_PLUGIN_PATH=/opt/Qt5.15.2/plugins:$QT_PLUGIN_PATH

然后使配置生效：

source~/.bashrc

验证安装是否成功：

qmake-v

如果输出类似QMake version 3.1并显示 Qt 5.15.2 的字样，说明配置成功。

图片插入位置：此处可插入终端执行qmake -v的截图。

8. 编译你的 Qt 项目

现在，你已经拥有了完整的 Qt 5.15.2 编译环境。将 Windows 上开发的 Qt 项目源码拷贝到 Ubuntu 中，进入项目目录，使用以下命令编译：

如果你使用 qmake：

qmake your_project.promake

如果项目使用 CMake：

mkdirbuild&&cdbuild cmake..-DCMAKE_PREFIX_PATH=/opt/Qt5.15.2make

如果编译过程中报错缺少某些模块，请根据报错信息重新运行 Qt 的configure并添加相应模块，再重新编译 Qt 本身。

图片插入位置：此处可插入编译自己项目时的终端输出截图。

9. 常见问题与排错

9.1 找不到qmake命令

确保环境变量已正确设置，并重新打开终端或执行source ~/.bashrc。

9.2 缺少libxcb相关库

在 Ubuntu 24.04 中，默认的libxcb库可能版本较新，如果 Qt 5.15.2 配置时仍然提示找不到，可以尝试安装libxcb-util1等早期版本，或者使用-qt-xcb选项让 Qt 自带编译一份 xcb 支持。

9.3 编译qtwebengine失败

如果项目不需要 WebEngine，强烈建议在配置时使用-skip qtwebengine跳过。如果确实需要，可以提前安装libnss3-dev、libnspr4-dev等依赖，并参考 Qt 官方文档。

图片插入位置：可插入典型错误提示的截图，或排错成功的终端界面。

10. 总结

本文详细介绍了在 Ubuntu 24.04 中编译 Qt 5.15.2 项目的完整流程，包括系统依赖安装、源码下载、配置、编译、环境变量设置以及项目编译实操。通过以上步骤，你可以顺利地将 Windows 上开发的 Qt 项目迁移到 Linux 平台进行编译和部署。

如果你在操作过程中遇到任何问题，欢迎在评论区留言交流。

图片插入位置：文末可插入一张编译成功的项目运行截图，作为成果展示。