简介：本资源面向在国产化平台进行桌面或嵌入式应用开发的工程师，提供在 Kylin-Server-10-SP2-Release-Build09-20210524 的 arm64 架构上编译完成的 Qt 5.12.8 头文件集合，可解决麒麟系统下 Qt 开发环境搭建与头文件缺失、版本不匹配等常见问题。压缩包为 gz 格式，共约 2000 个文件，全部为 .h 头文件，整体约 65.91MB，涵盖 QLocale、QOpenGL 系列函数、Valgrind 调试支持、QUrl 顶级域名等模块的声明，便于在交叉编译或本地构建时直接引用。目前已有 251 人学习下载，适合需要快速补齐 Qt 头文件依赖、对照源码排查编译错误的开发者参考使用。
1. 麒麟系统上把 Qt 5.12.8 从源码啃下来：为什么值得折腾
在 Kylin-Server-10-SP2-Release-Build09-20210524-arm64 这套国产化服务器环境里，系统自带的 Qt 版本往往停在 5.6 或 5.9 附近，而不少工业上位机、组态软件、串口调试工具偏偏要求 5.12.8 这个 LTS 版本。直接apt install qt5-default拿到的要么版本对不上，要么缺qtmqtt、qscintilla这类扩展模块，最后只能走源码编译这条路。arm64 平台和 x86 最大的区别在于：官方预编译包基本不覆盖麒麟的库路径和 GCC 版本，交叉编译又容易在qmake阶段就翻车，所以本地原生编译反而是最稳的选择。这篇笔记面向的是手里已经有一台麒麟 arm64 服务器、需要把 Qt 5.12.8 完整跑起来的嵌入式或桌面应用开发者，从依赖准备一路讲到模块裁剪和验证，中间踩过的坑都会标出来。
2. 编译前的依赖清单与工具链核对
2.1 先确认系统里到底有什么
麒麟 SP2 基于较新的 glibc，但默认安装的编译工具往往不完整。第一步不是急着下源码，而是把家底摸清楚。执行下面几条命令，把 GCC、G++、make、Python 的版本记下来，后面配置阶段会反复用到。
# 查看系统版本与架构，确认是 aarch64 而非 x86_64 cat /etc/kylin-release uname -m # 核对编译器版本，Qt 5.12.8 建议 GCC 7.3 及以上 gcc --version g++ --version make --version # 查看 Python 位置，Qt 的 configure 脚本依赖 python2 或 python3 which python3 python3 --version逻辑说明：uname -m返回aarch64才说明是真正的 arm64 环境，如果返回x86_64说明你连错机器了。GCC 版本低于 7.3 时，Qt 的 C++11 特性支持会出问题，典型表现是编译qbytearray相关文件时报std::atomic找不到。Python 这块要注意，Qt 5.12.8 的configure脚本对 Python 3 的支持是半吊子，如果系统里只有 Python 3.10 以上，建议额外装一个python3.8或直接用-no-feature-python跳过。
2.2 一次性补齐开发库
麒麟的软件源里包名和 CentOS、Ubuntu 都有差异，下面这份清单是我在 SP2 上实测能装齐的。缺任何一个都可能在configure或make中途报错，与其编译到一半再补，不如一次装完。
# 基础编译工具 sudo yum install -y gcc gcc-c++ make cmake perl python3-devel # X11 与 OpenGL 相关，Qt Widgets 和 Qt Quick 都依赖 sudo yum install -y libX11-devel libXext-devel libXrender-devel \ libXtst-devel libXi-devel mesa-libGL-devel mesa-libGLU-devel # 字体与图形库 sudo yum install -y fontconfig-devel freetype-devel libpng-devel \ libjpeg-turbo-devel libtiff-devel # 音频与多媒体，编译 QtMultimedia 时需要 sudo yum install -y alsa-lib-devel pulseaudio-libs-devel # 数据库驱动，QtSql 模块依赖 sudo yum install -y sqlite-devel postgresql-devel mysql-devel # 网络与安全 sudo yum install -y openssl-devel libcurl-devel参数说明：mesa-libGL-devel提供 OpenGL 头文件，缺了会在编译qtbase/src/gui/opengl时报GL/gl.h: No such file。libXtst-devel是 XTest 扩展，Qt 的自动化测试模块需要它。sqlite-devel建议必装，因为 Qt 自带的 SQLite 插件在麒麟上默认走系统库，不装的话QSqlDatabase会提示驱动未加载。如果这台机器不接显示器、只做后台服务，可以省掉 X11 那一组，但configure时要加-no-xcb，否则一样会去找 X11 头文件。
提示：麒麟 SP2 的 yum 源里
mysql-devel可能叫mariadb-devel，装之前先yum search一下，别硬套包名。
3. 源码获取、configure 参数与模块裁剪
3.1 源码包怎么拿、放哪
Qt 5.12.8 的源码有两种拿法：一是从官方归档站下single包，二是用git拉5.12.8分支再初始化子模块。arm64 上我推荐用 single 包，省去子模块同步的麻烦。下载后解压到一个路径不含中文和空格的目录，比如/opt/qt-src。
# 创建源码目录并进入 sudo mkdir -p /opt/qt-src cd /opt/qt-src # 假设源码包已放到当前目录，解压 tar -xf qt-everywhere-src-5.12.8.tar.xz # 进入解压后的目录 cd qt-everywhere-src-5.12.8逻辑说明：qt-everywhere-src是包含所有模块的完整包，解压后大约 5GB 左右。不要放在/root下，因为编译过程中会产生大量中间文件，/root分区通常较小容易撑爆。解压后先别急着 configure，用ls看一眼目录结构，确认qtbase、qtdeclarative、qtmultimedia这些子目录都在。
3.2 configure 参数逐条拆解
configure 是整个编译过程中最容易翻车的一步。参数写多了编译不过，写少了功能缺失。下面这份是我在麒麟 arm64 上验证过的配置，兼顾了桌面应用和串口通信需求。
# 在源码根目录执行 ./configure -prefix /opt/Qt5.12.8 \ -opensource -confirm-license \ -release -shared \ -platform linux-g++ \ -nomake examples -nomake tests \ -no-openssl \ -qt-zlib -qt-libpng -qt-libjpeg \ -qt-sqlite \ -skip qtwebengine \ -skip qtwebview \ -skip qtlocation \ -skip qtsensors \ -skip qtgamepad \ -skip qtserialbus \ -skip qtwayland \ -v参数说明：-prefix指定安装路径，建议单独放一个目录方便后续打包。-opensource -confirm-license是开源版必须的，少了会交互式询问。-release -shared生成动态库，如果要做静态部署改成-static，但静态编译在 arm64 上对 OpenSSL 依赖处理很麻烦，不建议新手碰。-nomake examples -nomake tests能省掉至少 30% 的编译时间，examples 里有些模块的示例代码在 arm64 上本身就有编译错误。-no-openssl是因为麒麟自带的 OpenSSL 版本和 Qt 5.12.8 的兼容层有冲突，如果确实需要 HTTPS，建议单独编译 OpenSSL 1.1.1 再用-openssl-linked指定路径。-qt-zlib -qt-libpng -qt-libjpeg表示用 Qt 自带的第三方库，避免和系统库版本打架。-skip那几个模块要么体积巨大（qtwebengine 在 arm64 上编译要几个小时），要么在服务器场景根本用不上。
注意：
-skip qtwebengine是必须的，这个模块在 arm64 上需要 Chromium 的交叉编译支持，麒麟环境基本编不过去，硬编只会浪费时间。
3.3 模块裁剪的取舍逻辑
不是所有项目都需要完整 Qt。如果你的应用只用到 Widgets 和 Network，可以把qtdeclarative、qtquickcontrols也 skip 掉，编译时间能从两小时压到四十分钟。但要注意，qtmqtt和qscintilla这两个热搜里常出现的模块并不在qt-everywhere包里，它们是独立项目，需要单独编译。qtmqtt依赖qtbase的QtNetwork，所以qtbase必须完整编译。qscintilla则依赖QtWidgets和QtPrintSupport，裁剪时别把qtbase里的打印支持关了。
# 如果只需要核心模块，可以用更精简的配置 ./configure -prefix /opt/Qt5.12.8-mini \ -opensource -confirm-license \ -release -shared \ -nomake examples -nomake tests \ -no-openssl \ -qt-zlib -qt-libpng -qt-libjpeg \ -skip qtdeclarative \ -skip qtmultimedia \ -skip qtwebengine \ -skip qtlocation \ -skip qtsensors \ -skip qtgamepad \ -skip qtserialbus \ -skip qtwayland \ -skip qtquickcontrols \ -skip qtquickcontrols2 \ -v逻辑说明：这份配置只保留qtbase、qtsvg、qttools等基础模块，适合纯 Widgets 应用。-skip qtdeclarative会连带跳过 QML 相关的一切，如果后续想加 QML 界面就得重新编译。建议第一次编译时保留qtdeclarative，哪怕不用，后面想加也方便。
4. 编译、安装与 qtmqtt/qscintilla 扩展模块
4.1 make 阶段的并行度与内存控制
configure 通过后，make的并行度设置直接影响编译速度和成功率。arm64 服务器通常核数不多，盲目-j拉满会导致内存溢出，典型报错是g++: internal compiler error: Killed。
# 查看 CPU 核数和内存 nproc free -h # 根据内存决定并行度，一般每核 2GB 内存 # 假设 8 核 16GB 内存，用 -j8 make -j8 2>&1 | tee build.log # 如果中途报错，单独重试出错模块，不要从头再来 make -j4 2>&1 | tee build_retry.log逻辑说明：tee build.log把编译输出同时写到文件和终端，方便出错后回溯。如果make -j8跑到一半被 Killed，降到-j4再跑，make 会自动跳过已编译成功的文件。internal compiler error不一定是代码问题，九成是内存不够。编译qtdeclarative时单个进程峰值能到 2GB 以上，16GB 内存的机器建议-j6保守一点。
4.2 安装与环境变量配置
编译完成后执行make install，然后配置环境变量让系统能找到新装的 Qt。
# 安装到 configure 时指定的 prefix sudo make install # 配置环境变量，写入 /etc/profile.d/qt5.sh sudo tee /etc/profile.d/qt5.sh << 'EOF' export QTDIR=/opt/Qt5.12.8 export PATH=$QTDIR/bin:$PATH export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH=$QTDIR/plugins export QML2_IMPORT_PATH=$QTDIR/qml EOF # 使环境变量生效 source /etc/profile.d/qt5.sh # 验证 qmake 版本 qmake -v参数说明：QTDIR是 Qt 的根目录，很多第三方项目的.pro文件会引用这个变量。LD_LIBRARY_PATH让运行时能找到libQt5Core.so.5等动态库。QT_PLUGIN_PATH是插件路径，缺了会导致QSqlDatabase找不到驱动、QJpegPlugin加载失败。QML2_IMPORT_PATH是 QML 模块路径，不用 QML 可以不加。qmake -v输出里应该显示Using Qt version 5.12.8，如果显示的是系统旧版本，说明 PATH 顺序不对。
4.3 单独编译 qtmqtt 与 qscintilla
qtmqtt和qscintilla不在主包里，需要单独拉源码编译。这两个模块在工业上位机和代码编辑器场景里出现频率很高，热搜里也常有人问。
# 编译 qtmqtt cd /opt/qt-src git clone -b 5.12.8 https://code.qt.io/qt/qtmqtt.git cd qtmqtt /opt/Qt5.12.8/bin/qmake make -j4 sudo make install # 编译 qscintilla cd /opt/qt-src # 假设已下载 QScintilla 源码包并解压 cd QScintilla-2.11.6/Qt4Qt5 /opt/Qt5.12.8/bin/qmake qscintilla.pro make -j4 sudo make install逻辑说明：qtmqtt的qmake必须用新编译的 Qt 5.12.8 里的，不能用系统自带的，否则会链接到旧版本库。qscintilla的.pro文件在Qt4Qt5目录下，虽然名字叫 Qt4Qt5，但兼容 Qt5。编译完成后，qtmqtt的头文件会装到/opt/Qt5.12.8/include/QtMqtt，库文件在/opt/Qt5.12.8/lib。qscintilla装完后需要在项目的.pro里加LIBS += -lqscintilla2_qt5才能链接。
提示：
qscintilla编译时如果报undefined reference to QPrinter，说明qtbase的QtPrintSupport没编进去，回头检查 configure 时有没有误加-no-printsupport。
5. 避坑排查：麒麟 arm64 编译 Qt 的五个血泪教训
5.1 报错GL/gl.h: No such file or directory
现象：configure 阶段或编译qtbase/src/gui时提示找不到GL/gl.h。 原因：系统没装mesa-libGL-devel，或者装了但头文件路径不在默认搜索路径里。 解决：sudo yum install mesa-libGL-devel，如果已装，用find / -name "gl.h" -path "*GL*"确认路径，然后在 configure 时加-I/usr/include/GL。
5.2 报错g++: internal compiler error: Killed
现象：make 跑到某个模块突然中断，日志最后一行是Killed。 原因：并行编译时内存耗尽，被系统 OOM Killer 杀掉。 解决：降低-j数值，8GB 内存用-j2，16GB 用-j4，32GB 以上再考虑-j8。也可以临时加 swap 分区顶一下。
5.3 qmake 生成的 Makefile 里链接了错误的库路径
现象：编译第三方项目时提示cannot find -lQt5Core，但/opt/Qt5.12.8/lib下明明有。 原因：环境变量LD_LIBRARY_PATH没生效，或者qmake用的是系统旧版本。 解决：which qmake确认指向/opt/Qt5.12.8/bin/qmake，在.pro文件里显式加QMAKE_LIBDIR += /opt/Qt5.12.8/lib。
5.4 运行程序时报QSqlDatabase: QSQLITE driver not loaded
现象：程序启动后数据库连接失败，提示 SQLite 驱动未加载。 原因：QT_PLUGIN_PATH没设置，或者sqldrivers插件目录不在搜索路径。 解决：export QT_PLUGIN_PATH=/opt/Qt5.12.8/plugins，用ls /opt/Qt5.12.8/plugins/sqldrivers确认libqsqlite.so存在。如果不存在，说明 configure 时-qt-sqlite没生效，检查sqlite-devel是否安装。
5.5 编译 qtmqtt 时报QtMqtt/QMqttClient: No such file
现象：项目里#include <QtMqtt/QMqttClient>编译失败。 原因：qtmqtt没装到 Qt 的 include 目录，或者.pro里没加QT += mqtt。 解决：确认qtmqtt执行了make install，然后在.pro里加QT += mqtt，重新qmake再make。
6. 验证编译成果与一个提速技巧
编译装完之后，别急着上项目，先用一个最小示例验证 Qt 5.12.8 在麒麟 arm64 上确实能跑通。下面这个测试程序同时覆盖 Widgets、Network 和 SQLite，能一次性把核心模块都验一遍。
// test_qt.cpp #include <QApplication> #include <QLabel> #include <QNetworkAccessManager> #include <QSqlDatabase> #include <QDebug> int main(int argc, char *argv[]) { QApplication app(argc, argv); // 验证 Widgets QLabel label("Qt 5.12.8 on Kylin arm64 OK"); label.show(); // 验证 Network QNetworkAccessManager manager; qDebug() << "Network manager created:" << &manager; // 验证 SQLite 驱动 QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE"); db.setDatabaseName(":memory:"); if (db.open()) { qDebug() << "SQLite driver loaded OK"; } else { qDebug() << "SQLite driver failed:" << db.lastError().text(); } return app.exec(); }编译命令：
/opt/Qt5.12.8/bin/qmake -project # 在生成的 .pro 文件里加 QT += widgets network sql /opt/Qt5.12.8/bin/qmake make ./test_qt逻辑说明：qmake -project自动生成.pro文件，然后手动补上QT += widgets network sql。运行后如果弹出窗口、终端输出SQLite driver loaded OK，说明 Widgets、Network、SQL 三个模块都正常。如果窗口没弹出来但终端没报错，检查DISPLAY环境变量是否设置，无头服务器上跑 GUI 需要 X11 转发或虚拟显示。
最后分享一个提速技巧：如果后续需要反复编译调试，把qtbase单独拎出来编译，其他模块用make -C qtbase的方式增量编译。qtbase是整个 Qt 的核心，改configure参数后只需要重编qtbase，其他模块的 Makefile 会引用qtbase的库，不用全部重来。我在麒麟 SP2 上第一次全量编译花了将近三小时，后来用增量方式改配置，每次只要二十分钟。这个习惯帮我省下了大量等待时间，希望帮到你。
本文还有配套的精品资源，点击获取
