银河麒麟V10 SP1配飞腾处理器要在上面搭一套QT5.12.8开发环境这事听起来不复杂真做起来能让人崩溃。我在飞腾D2000平台上折腾了整整三天踩过的坑可以写一本小册子下载的安装包跑不了、OpenGL库缺失、xcb插件加载失败、中文字体变方块……每一个都花了我两三个小时去排查。这篇文章把我的完整过程记录成一份避坑指南包括每个报错背后的原因、完整的依赖安装清单、源码编译的配置参数以及最后环境验证的方法。只要你的机器同样是飞腾或者其他ARM64处理器按这篇的步骤走两小时内把QT5.12.8跑起来是能做到的。这篇内容适合三类人一是需要在银河麒麟V10 SP1上做Qt界面开发的工程师二是负责国产化终端上应用迁移部署的运维同学三是学校里用国产平台做项目被环境问题折磨过的学生。不管你属于哪一类照着做之前先把“别用Windows的惯性来耍麒麟”这句话记在心里后面能少吃一半苦。1. 环境摸底动手前必须想明白的三件事1.1 银河麒麟和飞腾到底是个什么组合先对着机器确认一下基础信息别拿到就开始装。在终端里执行cat /etc/os-release # 看系统版本 lscpu | grep Architecture # 看CPU架构 free -h # 看内存 df -h /usr # 看磁盘剩余空间我的机器信息是系统银河麒麟V10 SP1CPU是飞腾D20008核架构显示aarch6416G内存。这串信息很关键它决定了后面所有软件包的选型。飞腾处理器走的是ARMv8指令集属于64位ARM平台所以绝大多数针对x86_64编译的二进制文件在这里都没法跑。这个概念好比英制螺丝刀跟公制螺丝看着都是螺丝刀拧上就滑丝。银河麒麟V10 SP1底层是Debian系包管理是apt很多经验可以借鉴Ubuntu/Debian的玩法但也别全信因为麒麟的软件源里的包版本和上游不一定同步。触摸屏、显卡、网卡这些硬件的驱动适配在不同批次的飞腾板上差异很大。如果安装过程中遇到跟驱动相关的奇怪问题先确认一下硬件型号和驱动状态再排查软件原因。1.2 装Qt到底有哪几条路我在动手之前把路径摸了一遍大致有三条路径A银河麒麟软件源直接apt安装。优点是命令短、装得快缺点是源里的Qt版本不一定正好是5.12.8可能是5.11或5.15而且有些是定制裁剪过的。如果对版本号没有强迫症日常开发用这个最省心。路径BQt官网提供的离线安装包run文件。Qt官方archive页面有各版本安装器但这里的坑是默认区分了x64和arm64很多人闭眼下x64的包结果在飞腾上根本跑不了。路径C源码编译。最可控下载qt-everywhere-opensource-src-5.12.8.tar.xz源码包自己configure、make、install能精确锁定5.12.8也能按需裁剪模块。代价是编译时间长对机器性能有要求。我的选择是B和C结合——先踩了路径B的坑然后老老实实走路径C。如果你时间宝贵直接看路径C的实现细节就行。1.3 为什么版本敏感度这么高Qt从5.6开始区分商业版和开源版的LTS节奏5.12.8属于5.12 LTS系列的后期修复版本稳定性有保证。很多国产化项目把应用锁定在5.12.8上主要是验证过、文档多、生态成熟。真正的问题不是“它好”而是“团队统一用它”一旦某个成员的机器上编译链接的是5.12.8挨个传到其他机器上还需要一致的ABI。源码编译能保证所有机器都用同一套工具链、同一个编译选项规避很多二进制包版本错配造成的诡异问题。这也是为什么即使源码编译耗时更长我也坚持用它来做最终环境。另一个版本敏感点在于编译参数。Qt源码包里configure阶段会探测系统里各种依赖库不同系统的库版本不同探测结果也不同。你在一台Ubuntu上编译的Qt换到麒麟上可能因为某个库版本差异出现运行时怪癖。所以环境搭建一定要在目标机器上完成别图方便在别的机器上编好再拷过来。2. 实操全程从依赖准备到第一个Qt窗口2.1 先把基础依赖装齐这一步偷懒后面全是坑在开始编译Qt之前系统里需要有一批开发库。我整理了一个安装命令照着执行就行sudo apt update sudo apt install -y gcc g make build-essential sudo apt install -y libgl1-mesa-dev libfontconfig1-dev libfreetype6-dev libx11-dev libxkbcommon-x11-0 sudo apt install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-util1 libxcb-xkb1每个包都有它的用途我顺手解释一下build-essential包含gcc、g、make等编译工具链是编译一切的基石。libgl1-mesa-devOpenGL开发库Qt的opengl模块、以及很多图形渲染路径都要用。libfontconfig1-dev和libfreetype6-dev字体配置和字型渲染Qt文本绘制依赖它们不装的话界面文字会异常。libx11-devX11协议开发头文件xcb插件跟X server通信的基础。libxcb-*那一批xcb平台插件的运行时依赖缺了它们后面写好的Qt程序启动时会报“xcb plugin could not be initialized”直接白屏。有些教程还建议用apt-get build-dep qtbase5-dev一次性拉齐所有编译依赖命令挺好用但会把很多用不到的包也装进来。在飞腾板上磁盘不宽裕的话我更建议一行行装上面列出来的够用就行。装完之后检查一下gcc --version make --version dpkg -l | grep libxcb | head -n 20确认工具链正常、xcb相关库存在再进入下一步。这一步踩的坑我记得很清楚当时没装libxkbcommon-x11-0Qt程序一启动就报键盘相关错误苦查了半天。2.2 用源码编译拿到干净的QT5.12.8源码包的下载地址在Qt官方archive文件名是qt-everywhere-opensource-src-5.12.8.tar.xz。这个包很大几百MB下载速度取决于网络。如果只想编译Qt基础模块QtCore、QtGui、QtWidgets可以只下载qtbase-opensource-src-5.12.8.tar.xz时间能省不少。我第一次就是直接编全量包结果qtwebengine等模块拖慢了大量时间后来学聪明了编基础模块够用就行了。下载解压wget https://download.qt.io/archive/qt/5.12/5.12.8/qt-everywhere-opensource-src-5.12.8.tar.xz tar -xJf qt-everywhere-opensource-src-5.12.8.tar.xz cd qt-everywhere-opensource-src-5.12.8然后是最关键的一步configure。我使用的配置如下./configure -prefix /opt/Qt5.12.8 \ -opensource \ -confirm-license \ -release \ -nomake examples \ -nomake tests \ -skip qtwebengine \ -no-opengl简单说下每个参数的意思-prefix /opt/Qt5.12.8指定安装目录后面所有库和工具都会装到这里独立于系统目录方便管理和卸载。-opensource -confirm-license选择开源版本并确认LGPL协议交互式提示就不会卡住。-release编译发布版不带调试符号体积小、速度快。-nomake examples -nomake tests不编译示例和测试少花大量时间。-skip qtwebengine跳过WebEngine模块这个模块编译极其耗时且依赖Chromium在飞腾这种ARM平台上更是折磨。-no-opengl这是我在飞腾平台上的核心选择。因为很多飞腾主板配的显卡是景嘉微或者其他国产GPUOpenGL驱动往往不完整与其后面被各种GL报错折磨不如直接在Qt层面禁用OpenGL。对于纯Widgets界面程序这个选项完全够用。如果你的业务必须用OpenGL渲染那需要先确认显卡驱动能提供完整的GL实现否则只能软件渲染。configure执行的时候会输出一堆检测信息重点看最后有没有ERROR相关提示。当时我记得有一个关于xcb的提示因为系统缺libxcb开发头文件后来把libxcb-*-dev也装了一遍configure重新跑了一次就好了。configure通过之后开始编译make -j$(nproc)这里有第二个大坑-j$(nproc)会让所有核心全力编译内存不足时直接OOM崩溃。我8核的机器编译到一半经常看到进程被kill。后来改成make -j4如果你的机器内存小于8G建议用-j2。编译过程很漫长全量包可能超过一小时只编qtbase大概20-30分钟。期间可以用top或htop盯着内存爆了就降并发。编译完成后安装make install安装到/opt/Qt5.12.8后验证一下/opt/Qt5.12.8/bin/qmake -v如果显示QMake version 3.1 Using Qt version 5.12.8说明核心环境已经就绪。2.3 写环境变量别图省事跳过Qt编译好了如果直接敲qmake终端会告诉你找不到命令。因为可执行文件在/opt/Qt5.12.8/bin下面这个目录不在PATH环境变量里。我建议新建一个独立的环境变量文件放到/etc/profile.d/下面这样所有用户登录时都会自动加载不会出现“换个终端就找不到qmake”的情况。创建/etc/profile.d/qt.shsudo vim /etc/profile.d/qt.sh写入以下内容export QTDIR/opt/Qt5.12.8 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLATFORM_PLUGIN_PATH$QTDIR/plugins/platforms export QT_QPA_PLATFORMxcb说明一下这几个变量的作用QTDIRQt的根目录很多工具和脚本会引用它。PATH让qmake、moc、rcc等工具可以直接在命令行使用。LD_LIBRARY_PATH程序运行时动态库的搜寻路径。Qt程序启动时会去这里找libQt5Core.so等文件不配的话会报cannot open shared object file。QT_PLATFORM_PLUGIN_PATH指示平台插件目录。xcb插件就在这个目录下。QT_QPA_PLATFORMxcb指定Qt程序使用X11的xcb平台接口。在服务器无桌面环境时可以临时改成offscreen用于无头测试。保存后生效source /etc/profile.d/qt.sh然后验证which qmake qmake -v正常的话which qmake会输出/opt/Qt5.12.8/bin/qmake。2.4 Qt Creator里配Kit跑通Hello World编译器有了、qmake有了接下来是把IDE配好。我在飞腾上试过两种方法一是直接用麒麟软件源安装的qtcreator二是源码编译Qt时顺带编出的creator。我的建议是用软件源版本省事IDE本身不依赖具体Qt版本只是个壳。sudo apt install -y qtcreator打开Qt Creator依次配置打开工具 - 选项 - 编译器。在GCC那一栏添加C编译器/usr/bin/gccC编译器/usr/bin/g通常系统会自动检测到。切到Qt Versions点击添加选择/opt/Qt5.12.8/bin/qmake。如果显示版本为“Qt 5.12.8 (qt5.12.8)”就说明识别成功。切到Kits新建一个Kit把上面添加的Compilers和Qt Version选进去CMake保持自动即可。创建一个新的Qt Widgets Application项目选择这个Kit点击构建运行。如果此前的环境变量是在终端里source过的Qt Creator里可能没读到可以在Kits的Environment里手动加一行LD_LIBRARY_PATH/opt/Qt5.12.8/lib避免运行时报共享库找不到。第一个窗口能弹出来Qt环境就算正式通了。我当时的第一个程序就用了个QLabel显示“飞腾OK”看到屏幕上的字时悬着的心才放下来。3. 避坑合集飞腾麒麟平台最常见的五个坑3.1 坑一x86_64安装包在ARM上的“假死”这是我踩的第一个、也是最经典的坑。当时我从官网下载了qt-opensource-linux-x64-5.12.8.run在终端里执行后不是没反应就是报Exec format error或者No such file or directory。朋友说缺依赖让我装这个装那个折腾了半天不见好。后来我用file命令查了一下安装包file qt-opensource-linux-x64-5.12.8.run输出是ELF 64-bit LSB executable, x86-64。问题一下就清楚了架构不对。飞腾是aarch64这个安装器是x86_64的二进制根本不是一个世界的东西。所以遇到这种“安装器无法执行”的报错先别急着查依赖第一步用file看二进制架构第二步用ldd看依赖库。这个排查思路能帮你在国产平台上省下大量时间。3.2 坑二libGL与OpenGL驱动的问题源码编译好的Qt在运行一段时间后有些程序会报libGL.so.1: cannot open shared object file。原因分两种一是系统里压根没装OpenGL运行库二是飞腾的显卡驱动没有提供完整的OpenGL实现。前者的解决办法是sudo apt install -y libgl1 mesautils后者的处理则复杂很多。如果你的应用只是普通Widgets界面根本用不到OpenGL直接在configure阶段加-no-opengl最省心编出来的版本不依赖libGL。我就是这么处理的。如果你确实需要OpenGL先跑一下glxinfo | grep OpenGL version看驱动能做到什么程度再做决定。3.3 坑三xcb平台插件加载失败每次运行Qt程序时提示This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem. Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.这个问题在Qt新手里太常见了。意思是说程序启动时需要跟X11窗口系统通信xcb插件就是干这个的但它依赖一堆libxcb相关的动态库系统里缺了插件加载自然会失败。解决办法就是补库sudo apt install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-util1 libxcb-xkb1 libxkbcommon-x11-0装完再运行程序一般就正常了。如果还不行检查一下/opt/Qt5.12.8/plugins/platforms/下有没有libqxcb.so。没有的话说明编译Qt时缺少libxcb开发头文件需要先装libxcb*-dev再重新编译一次qtbase。3.4 坑四字体是方块、中文输不进去Qt程序跑起来了界面上的中文全是方块输入法也不响应。这两个问题虽然都发生在“用起来”阶段不解决的话开发体验极差。方块字的原因是系统没有中文字体sudo apt install -y fonts-noto-cjk fonts-wqy-zenhei装完重启Qt程序字体就正常了。输入法问题则要看麒麟系统用的是fcitx还是ibus。麒麟V10 SP1默认装了ukui输入法框架基于fcitx所以需要在Qt侧加载fcitx的输入法桥接插件sudo apt install -y fcitx-frontend-qt5然后设置环境变量export QT_IM_MODULEfcitx export GTK_IM_MODULEfcitx export XMODIFIERSimfcitx这三条可以追加到/etc/profile.d/qt.sh里全局生效。设置完记得fcitx restart或者注销重新登录输入法就能在Qt程序里唤出来了。3.5 坑五编译太慢、内存不足被OOMQt源码编译是一项大工程全量包的qt-everywhere在飞腾平台上编译一次动辄一小时以上。如果configure时没裁剪模块、make时又用了-j$(nproc)8核机器全核编译时内存峰值可能冲到十几GOOM后就无提示地杀掉编译器。我的建议是只想做界面开发就只编qtbase-opensource-src-5.12.8.tar.xz体积小很多。如果编全量包在configure里加-skip qtwebengine -skip qt3d -skip qtgamepad把用不到的重型模块全跳掉。make并发行数根据内存来定4G内存用-j28G用-j416G以上再考虑-j8。configure之前如果之前编译过先执行make distclean清理干净再重来别让残留的配置干扰新一轮编译。还有一个经验configure结束时的输出不要关拍张照或滚回去看一遍。里面会列出哪些模块被识别、哪些依赖缺失很多问题在configure阶段就能发现比编译到一半再去查省得多。4. 附赠在麒麟软件源里直装的替代方案4.1 apt直接装适合对版本不敏感的项目如果你的项目没有死锁5.12.8不想花两小时编译完全可以走系统源的直装路线sudo apt update sudo apt install -y qtbase5-dev qttools5-dev-tools qt5-default qtcreator装完之后运行qmake -v查看版本。麒麟V10 SP1的源在不同时期提供过不同版本可能是5.11、5.12或者5.15。版本不同带来的代码差异大部分场景可以忽略但如果你是用到某些5.12新特性的项目就要认真核对。源安装的好处是跟系统库联动不会出现OpenGL、xcb依赖不齐的问题因为包管理器会自动处理依赖。缺点是定制性弱有些企业内网环境源没有更新可能装不上。4.2 混合方案系统源版本和自定义编译版本共存有些读者问我能不能系统里装了源版本Qt又想把源码编译的5.12.8也留着完全可以。我的做法是保留/opt/Qt5.12.8独立目录不碰系统/usr/lib下的Qt库。项目要用哪个版本就在Qt Creator的Kit里选对应的qmake路径。部署时也有讲究。如果目标机器是相同的麒麟版本直接打包/opt/Qt5.12.8目录过去解压到同样路径再用环境变量指向它程序就能跑。也可以用linuxdeployqt这样的工具把依赖打包进应用的AppDir目录里做到免安装运行。不过linuxdeployqt在ARM平台上需要自己编译这点在后续做交付的时候再细说。5. 常见问题速查我的实战笔记症状原因快速解决run安装包执行时报Exec format error安装包是x86_64架构飞腾是aarch64选arm64版安装包或直接源码编译编译Qt时报OpenGL相关错误系统缺OpenGL开发库或驱动不全安装libgl1-mesa-dev或configure加-no-openglQt程序启动报xcb plugin无法初始化系统缺libxcb系列运行库apt安装libxcb-*相关包界面中文全是方块系统没有中文字体安装fonts-noto-cjk或fonts-wqy-zenhei中文输入法唤不出Qt没有加载fcitx/ibus前端安装fcitx-frontend-qt5并设置QT_IM_MODULEqmake命令找不到PATH未包含Qt目录source /etc/profile.d/qt.sh或配置系统PATH程序运行报libQt5Core.so找不到LD_LIBRARY_PATH未配置在环境变量中加入/opt/Qt5.12.8/lib编译时OOM或进程被kill内存不足make并发过高降低make -j并发数4G内存用-j2configure时xcb相关模块检测失败缺少libxcb开发头文件安装libxcb*-dev重新configure程序运行时界面白屏或崩溃OpenGL驱动不完整尝试QT_OPENGLsoftware环境变量这个表格里的问题都是我实际踩过、验证过的。遇到类似现象直接对号入座基本都能快速定位。最后再分享一个小技巧在国产平台上做开发遇到报错先别急着去网上搜索大段的问题描述先用file和ldd两个命令把二进制文件的架构和依赖摸清楚再用ldd检查缺失库往往答案就在那里等着你。这个环境搭好之后后面不管是做界面工具还是移植业务系统都会顺很多。希望这篇记录能帮你少走弯路早日把QT5.12.8在这个组合上跑起来。