简介本资源为在昭阳 N4720Z 设备、Kylin-Desktop-V10-GFB-Release-020-ARM64 系统上编译完成的 QT5.12.10 开发环境包面向需要在国产麒麟 ARM64 平台进行 Qt 应用开发的工程师与学习者可解决该架构下 Qt 环境搭建困难、官方预编译包缺失的问题。压缩包共约 2000 个文件以 h 头文件为主涵盖 qlocale、qopengl、qopenglextensions、qurltlds 等模块的接口声明是 Qt 库编译产物中供二次开发引用的核心部分整体约 84.62MB。资源已通过实际编译测试确认可用其他设备与系统需自行验证。使用者可将其解压至 /opt 目录在 Qt Creator 的 Kits 中手动添加 qmake 路径并指定 Qt 5.12.10 版本即可完成套件配置省去从源码交叉编译的繁琐过程。目前已有 1070 人学习下载适合从事麒麟系统 Qt 开发、需要快速获得可用 ARM64 编译环境的读者参考使用。1. 麒麟 V10 ARM64 上把 QT5.12.10 编译通过一次真实环境里的全链路复盘在国产化替代的现场Kylin-Desktop-V10-GFB-Release-020-ARM64 这个版本号几乎是一道分水岭。它跑在飞腾、鲲鹏这类 ARM64 架构的机器上系统自带的 Qt 版本往往停在 5.12.x 的某个早期小版本而业务侧偏偏要求 5.12.10——差一个小版本QML 引擎的行为、私有头文件的符号、甚至 qmake 生成的 Makefile 规则都可能对不上。于是「在麒麟 V10 ARM64 上从源码编译 QT5.12.10」就成了很多交付团队绕不开的一关。这篇笔记不讲空泛的国产化意义只讲我在这套系统上把 Qt 5.12.10 从解压到跑通 demo 的完整路径依赖怎么装、configure 参数怎么定、编译到一半报错怎么查、装完之后环境变量怎么配。适合正在做 ARM64 桌面端交付、需要自己掌控 Qt 版本的一线开发和构建工程师。2. 编译前的环境确认与依赖补齐别让缺库拖到 make 阶段才爆2.1 先确认你面对的是不是真正的 ARM64 桌面环境很多人拿到机器第一件事就是解压 Qt 源码开始 configure结果在 make 阶段被一个cannot find -lGL或者X11/extensions/Xrandr.h: No such file卡住。血泪经验是先把环境底细摸清楚再动手。麒麟 V10 的 GFB 版本在 ARM64 上默认是 Wayland 和 X11 混合的桌面栈Qt 5.12.10 默认走 X11所以 X11 的开发头文件必须齐。# 确认架构必须是 aarch64 而不是 x86_64 uname -m # 输出应为 aarch64 # 确认系统版本GFB Release 020 对应的是 SP 系列 cat /etc/kylin-release # 典型输出Kylin Linux Advanced Server release V10 (GFB) # 确认 gcc 版本Qt 5.12.10 对 gcc 7/8/9 都友好gcc 10 以上要留意 gcc --versionuname -m返回aarch64说明你确实在 ARM64 上这是后面所有交叉编译讨论的前提——如果你是在 x86 机器上想编 ARM64 版本那属于交叉编译路径完全不同需要先准备aarch64-linux-gnu-工具链本文不展开。/etc/kylin-release用来确认系统小版本因为不同 GFB 小版本的软件源里 Qt 依赖包名字会有细微差别。gcc 版本决定了后面 configure 时要不要加-no-strict-aliasing之类的兼容开关。2.2 用一条 apt 命令把 X11、OpenGL、字体、多媒体依赖一次装齐麒麟 V10 底层是 RPM 系还是 DEB 系取决于你拿到的具体镜像。GFB 版本多数是 DEB 系用 apt如果是 RPM 系就换成 yum/dnf包名基本对应。下面这条命令是我在 DEB 系麒麟上验证过的依赖集合覆盖了 QtBase、QtDeclarative、QtMultimedia 编译时最常缺的几类。sudo apt update sudo apt install -y \ build-essential perl python3 git \ libx11-dev libxext-dev libxrender-dev libxcb1-dev \ libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev \ libxcb-icccm4-dev libxcb-sync-dev libxcb-xfixes0-dev \ libxcb-shape0-dev libxcb-randr0-dev libxcb-render-util0-dev \ libxkbcommon-dev libxkbcommon-x11-dev \ libgl1-mesa-dev libglu1-mesa-dev \ libfontconfig1-dev libfreetype6-dev \ libssl-dev libasound2-dev libpulse-dev \ libdbus-1-dev libudev-dev libinput-dev \ libmtdev-dev libts-dev libjpeg-dev libpng-dev这条命令的逻辑是分组的build-essential perl python3 git是编译基础设施Qt 的构建系统依赖 perl 和 python3 做脚本处理libxcb-*那一长串是 X11 的 C 绑定库Qt 的 xcb 平台插件强依赖缺任何一个都会在 configure 阶段报xcb相关 feature 被禁用libgl1-mesa-dev和libglu1-mesa-dev提供 OpenGL 头文件ARM64 上 Mesa 的软件渲染是默认路径字体和 freetype 决定 QFontDatabase 能不能正常枚举中文字体libssl-dev是 QtNetwork 的 SSL 后端交付里只要涉及 HTTPS 就必须有libasound2-dev和libpulse-dev是 QtMultimedia 的音频后端。参数上唯一要注意的是libinput-dev和libmtdev-dev这两个是触摸屏和输入设备支持如果你的设备是纯键鼠可以省但省了之后 Qt 的 evdev 插件会缺功能。装完之后建议做一次快速验证确认关键头文件在位# 检查 X11 和 OpenGL 头文件是否存在 ls /usr/include/X11/Xlib.h ls /usr/include/GL/gl.h ls /usr/include/xcb/xcb.h # 三个都存在才继续缺哪个补哪个对应的 -dev 包提示麒麟 V10 的软件源里 Qt 相关依赖包名和标准 Ubuntu 有差异如果 apt 报找不到某个包先用apt search搜关键词比如apt search xcb-keysyms找到实际包名再装不要硬套网上的 Ubuntu 包名清单。3. configure 参数怎么定ARM64 上最容易翻车的一步3.1 源码解压与目录规划Qt 5.12.10 的源码包解压后是一个qt-everywhere-src-5.12.10目录里面包含 qtbase、qtdeclarative、qtmultimedia 等所有子模块。我一般不会在源码目录里直接 configure而是建一个独立的 build 目录这样编译失败要重来时直接删 build 目录就行源码保持干净。# 解压源码 tar -xf qt-everywhere-src-5.12.10.tar.xz cd qt-everywhere-src-5.12.10 # 建独立构建目录 mkdir build cd build # 记录源码根目录后面 configure 要用绝对路径 SRC_ROOT$(pwd)/.. echo $SRC_ROOT独立 build 目录的好处是Qt 的 configure 会在构建目录生成 config.summary 和 Makefile源码目录里只保留原始文件。如果编译到一半发现某个 feature 配错了删掉 build 重来比在源码目录里make distclean干净得多。SRC_ROOT这个变量后面 configure 时用-prefix和源码路径引用会用到。3.2 configure 命令逐参数拆解下面这条 configure 命令是我在麒麟 V10 ARM64 上跑通的版本参数不算最少但覆盖了桌面交付的常见需求。先给命令再逐段解释。../configure -prefix /opt/Qt5.12.10 \ -opensource -confirm-license \ -release -shared \ -platform linux-g \ -xplatform linux-aarch64-gnu-g \ -nomake examples -nomake tests \ -no-compile-examples \ -skip qtwebengine \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype \ -openssl-linked \ -dbus-linked \ -system-freetype -fontconfig \ -opengl desktop \ -no-use-gold-linker \ -recheck-all-prefix /opt/Qt5.12.10指定安装路径我习惯装在/opt下和系统自带的 Qt 隔离后面用环境变量切换。-opensource -confirm-license是开源版授权确认不加会交互式提问。-release -shared表示编译发布版动态库交付场景基本都用这个组合debug 版体积大且性能差。-platform linux-g和-xplatform linux-aarch64-gnu-g这两个参数是 ARM64 原生编译的关键。-platform指定构建机平台-xplatform指定目标平台。在 ARM64 机器上原生编译时两者其实都是本机但 Qt 的 mkspecs 里linux-aarch64-gnu-g这个 spec 会带上 ARM64 特有的编译选项。如果你的源码里没有这个 spec需要从linux-g复制一份改名并把QMAKE_CFLAGS里的架构相关选项确认一遍。-nomake examples -nomake tests -no-compile-examples三个一起用跳过示例和测试的编译能省掉将近三分之一的编译时间。-skip qtwebengine是因为 QtWebEngine 在 ARM64 上编译极其吃资源而且依赖 Chromium 的构建链交付里如果不用内嵌浏览器就直接跳过这是省时间的关键。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype表示用 Qt 自带的这些库而不是系统库。ARM64 上系统库版本参差不齐用 Qt 自带的能避免链接时的版本冲突。-openssl-linked -dbus-linked表示链接系统 OpenSSL 和 D-Bus这两个是运行时依赖必须用系统的否则和桌面环境的 D-Bus 通信会出问题。-system-freetype -fontconfig和上面的-qt-freetype看似矛盾实际是freetype 用 Qt 自带的编译但字体配置走系统的 fontconfig这样中文字体枚举才正常。-opengl desktop在 ARM64 上指定桌面 OpenGL如果你的板子只有 OpenGL ES要改成-opengl es2。-no-use-gold-linker是因为 ARM64 上 gold linker 支持不稳定用默认的 ld 更稳。-recheck-all强制重新检测所有 feature避免缓存导致的误判。3.3 configure 输出怎么读config.summary 里的关键行configure 跑完会输出一份 config.summary这份摘要比任何日志都重要。重点看这几行摘要项期望值异常时的处理Build typerelease如果是 debug检查 -release 是否被覆盖Target platformlinux-aarch64-gnu-g不对说明 xplatform spec 没找到X11 supportyesno 说明 libx11-dev 没装全xcbyesno 说明某个 libxcb-*-dev 缺失OpenGLdesktop和 -opengl 参数一致fontconfigyesno 说明 libfontconfig1-dev 缺失OpenSSLlinkedno 说明 libssl-dev 缺失或版本不匹配D-Buslinkedno 说明 libdbus-1-dev 缺失如果 X11 或 xcb 显示 no不要抱侥幸心理继续 make后面 QtGui 和 QtWidgets 会直接编译失败。正确做法是回到依赖安装那一步把缺的-dev包补上然后删掉 build 目录重新 configure。我见过有人为了省时间强行 make结果编译到 80% 报 xcb 符号未定义重来的时间成本更高。注意configure 阶段如果报ERROR: Feature xcb was enabled, but the pre-condition features.thread libs.xcb failed说明 xcb 库存在但线程检测没过通常是libxcb1-dev装了但libxcb-*-dev系列不全按 2.2 节的清单逐个核对。4. 编译与安装make 阶段的资源控制和报错定位4.1 用 -j 参数控制并行度ARM64 上别贪多configure 成功后就是 make。ARM64 机器的核心数差异很大飞腾 2000 系列可能只有 4 核鲲鹏 920 能到 64 核。并行度设太高会导致内存耗尽被 OOM killer 杀掉设太低又浪费时间。# 查看核心数和内存 nproc free -h # 根据内存决定并行度每核大约需要 2GB 内存 # 4 核 8GB 内存的机器用 -j4 make -j4 21 | tee build.log # 16 核 32GB 内存的机器可以用 -j16 # make -j16 21 | tee build.log21 | tee build.log这个组合是把标准错误重定向到标准输出再同时打印到屏幕和写入日志文件。编译 Qt 动辄一两个小时中途报错滚屏很快没有日志根本没法回溯。-j的数值经验公式是min(nproc, 内存GB / 2)。比如 8GB 内存的 4 核机器-j4是上限32GB 内存的 16 核机器-j16没问题。如果 make 过程中看到virtual memory exhausted或者进程被 kill就是并行度太高降到-j2重来。4.2 编译报错的三种典型模式和定位方法make 阶段的报错基本逃不出三类。第一类是头文件缺失报错形如fatal error: X11/extensions/Xrandr.h: No such file or directory这是依赖没装全回到 2.2 节补包。第二类是符号未定义报错形如undefined reference to XRenderFindVisualFormat这是链接阶段缺库通常是某个-dev包装了但对应的运行库没装用apt-file search找符号所属的包。第三类是编译器内部错误报错形如internal compiler error: Segmentation fault这是 ARM64 上 gcc 的已知问题换 gcc 版本或者降低优化等级能绕过。# 从头文件缺失报错里提取缺失的文件名 grep fatal error build.log | head -5 # 从符号未定义报错里提取缺失的符号 grep undefined reference build.log | head -5 # 定位符号属于哪个包需要先 apt install apt-file apt-file search XRenderFindVisualFormatgrep fatal error能快速列出所有缺失的头文件一次性补全比一个个试快。grep undefined reference列出缺失符号再用apt-file search反查包名。如果报错是internal compiler error先看是哪个文件触发的然后单独进那个子目录用make -j1重编确认是不是并行导致的资源竞争。ARM64 上 gcc 9 编译 Qt 5.12.10 的 qtdeclarative 模块时偶尔会在 qv4 引擎的某个文件上触发 ICE换 gcc 8 或者给那个文件单独加-O1能解决。4.3 安装到 /opt 并配置环境变量make 跑完没有报错就可以安装了。安装过程很快主要是把编译产物复制到-prefix指定的目录。sudo make install # 确认安装目录结构 ls /opt/Qt5.12.10/bin/qmake ls /opt/Qt5.12.10/lib/libQt5Core.so.5.12.10安装完成后/opt/Qt5.12.10/bin/qmake应该存在且可执行。接下来配置环境变量让系统优先用这个 Qt 而不是自带的。# 写入当前用户的 bashrc cat ~/.bashrc EOF export QT_ROOT/opt/Qt5.12.10 export PATH$QT_ROOT/bin:$PATH export LD_LIBRARY_PATH$QT_ROOT/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QT_ROOT/plugins export QML2_IMPORT_PATH$QT_ROOT/qml EOF source ~/.bashrc # 验证 qmake 版本 qmake -v # 应输出QMake version 3.1 Using Qt version 5.12.10 in /opt/Qt5.12.10/libLD_LIBRARY_PATH是最关键的一行不加的话运行时加载的还是系统自带的旧版 Qt 库会出现「编译时是 5.12.10运行时是 5.12.3」的玄学问题。QT_PLUGIN_PATH和QML2_IMPORT_PATH分别指向平台插件和 QML 模块桌面程序启动时报This application failed to start because no Qt platform plugin could be initialized就是这两个没配。验证时qmake -v输出的路径必须是/opt/Qt5.12.10/lib如果还是系统路径说明 PATH 顺序不对检查~/.bashrc里$QT_ROOT/bin是否在系统路径之前。5. 避坑与排查ARM64 编译 Qt 最常见的五个翻车现场5.1 现象configure 报 xcb 检测失败但 libxcb 明明装了原因麒麟 V10 的 libxcb 开发包拆得很细libxcb1-dev只提供核心库xcb-keysyms、xcb-icccm、xcb-image这些扩展是独立包。configure 检测的是完整功能集缺任何一个扩展都会把 xcb 整体判为不可用。解决按 2.2 节的清单逐个核对用dpkg -l | grep xcb列出已装的 xcb 相关包对照清单补缺。补完后必须删掉 build 目录重新 configure因为 configure 的检测结果有缓存。5.2 现象make 到 qtdeclarative 模块时报 internal compiler error原因ARM64 上 gcc 的某些版本在编译 qv4 引擎的 JIT 相关代码时寄存器分配会触发编译器 bug。这不是你代码的问题是工具链的问题。解决先确认 gcc 版本如果是 gcc 10 以上降到 gcc 8 或 9。如果不想换 gcc找到报错的文件在对应的 Makefile 里给那个文件单独加-O1降低优化等级。具体做法是进到build/qtdeclarative/src/qml/目录用make -j1单独编译看是哪个文件触发然后手动改该目录 Makefile 里那个文件的 CXXFLAGS。5.3 现象编译通过但运行 demo 时报找不到 Qt platform plugin xcb原因QT_PLUGIN_PATH没配或者配了但指向的目录里没有platforms/libqxcb.so。Qt 5.12.10 编译时如果 xcb feature 是 yes插件会生成在plugins/platforms/下但运行时需要环境变量告诉它去哪找。解决确认/opt/Qt5.12.10/plugins/platforms/libqxcb.so存在。如果不存在说明 configure 时 xcb 没启用回到 5.1 处理。如果存在检查QT_PLUGIN_PATH是否指向/opt/Qt5.12.10/plugins。可以用export QT_DEBUG_PLUGINS1再运行程序会打印插件加载的详细过程能看到它找了哪些路径、为什么没加载成功。5.4 现象中文字体显示为方块或乱码原因fontconfig 没启用或者系统里没有中文字体。Qt 5.12.10 的字体枚举依赖 fontconfig如果 configure 时-fontconfig没加QFontDatabase 就找不到系统字体。解决先确认 configure summary 里 fontconfig 是 yes。然后检查系统字体目录fc-list :langzh有没有输出。如果没有中文字体装一个sudo apt install fonts-wqy-zenhei或者把中文字体复制到/usr/share/fonts/下再fc-cache -fv。Qt 程序里用QFont(WenQuanYi Zen Hei)显式指定字体名比依赖默认字体更可靠。5.5 现象程序链接时提示 Qt5Core.so.5 版本不匹配原因系统里存在多个 Qt 版本LD_LIBRARY_PATH的顺序导致运行时加载了系统自带的旧版库。麒麟 V10 自带 Qt 5.12.3 或类似版本和 5.12.10 的 soname 相同但符号有差异。解决用ldd your_app | grep Qt5Core看实际加载的是哪个路径的库。如果是/usr/lib/aarch64-linux-gnu/下的说明LD_LIBRARY_PATH没生效或者顺序不对。确保~/.bashrc里export LD_LIBRARY_PATH$QT_ROOT/lib:$LD_LIBRARY_PATH在系统路径之前。更彻底的做法是在编译程序时用-Wl,-rpath,/opt/Qt5.12.10/lib把 rpath 写进可执行文件这样运行时优先从指定路径加载不依赖环境变量。6. 验证编译成果与一个让交付更稳的 rpath 技巧编译装完之后怎么确认这套 Qt 是真的能用而不是「qmake -v 对了但一跑就崩」我一般会写一个最小 demo同时用到 QtWidgets、QtNetwork 和 QML把三个最容易出问题的模块都覆盖到。// demo.cpp最小验证程序覆盖 Widgets、Network、QML 三个模块 #include QApplication #include QLabel #include QNetworkAccessManager #include QQmlApplicationEngine #include QDebug int main(int argc, char *argv[]) { QApplication app(argc, argv); // 验证 Widgets 和字体 QLabel label(麒麟 V10 ARM64 Qt 5.12.10 验证); label.show(); // 验证 Network 模块能初始化 QNetworkAccessManager manager; qDebug() Network manager created: manager; // 验证 QML 引擎能加载 QQmlApplicationEngine engine; qDebug() QML engine created: engine; return app.exec(); }编译命令用我们刚装的 qmake/opt/Qt5.12.10/bin/qmake -project /opt/Qt5.12.10/bin/qmake make -j4 ./demo这个 demo 的价值在于QLabel显示中文能验证 fontconfig 和字体链路QNetworkAccessManager构造能验证 QtNetwork 和 OpenSSL 链接正常QQmlApplicationEngine构造能验证 QML 模块和插件路径正确。三个都过了基本可以确认这套 Qt 在桌面交付场景下是完整的。最后一个技巧是关于 rpath 的。交付给客户的程序不能指望客户机器上配了LD_LIBRARY_PATH所以编译业务程序时要把 Qt 库路径写进可执行文件的 rpath。在 qmake 的.pro文件里加一行# 把 Qt 库路径写进 rpath运行时优先从该路径加载 QMAKE_LFLAGS -Wl,-rpath,/opt/Qt5.12.10/lib这样编译出来的程序用readelf -d your_app | grep RPATH能看到/opt/Qt5.12.10/lib被写进去了。客户机器上只要这个路径存在程序就能找到正确的 Qt 库不会去加载系统自带的旧版本。如果客户机器上 Qt 装在别的路径改这个 rpath 重新编译就行比让客户改环境变量靠谱得多。我自己在麒麟 V10 ARM64 上编 Qt 5.12.10 最大的教训是configure 阶段的 config.summary 一定要逐行看完再 make任何一项显示 no 都别抱侥幸。有一次 xcb 显示 no 我没管make 跑了四十分钟在 QtGui 模块炸了重来一遍的时间够我把依赖清单核对三遍。现在我的习惯是 configure 完先grep -E X11|xcb|OpenGL|fontconfig|OpenSSL config.summary确认全 yes 再开 make。希望帮到你。本文还有配套的精品资源点击获取