企业官网建设流程全解析

银河麒麟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 SP1，CPU是飞腾D2000（8核），架构显示aarch64，16G内存。这串信息很关键，它决定了后面所有软件包的选型。

飞腾处理器走的是ARMv8指令集，属于64位ARM平台，所以绝大多数针对x86_64编译的二进制文件在这里都没法跑。这个概念好比英制螺丝刀跟公制螺丝，看着都是螺丝刀，拧上就滑丝。银河麒麟V10 SP1底层是Debian系，包管理是apt，很多经验可以借鉴Ubuntu/Debian的玩法，但也别全信，因为麒麟的软件源里的包版本和上游不一定同步。

触摸屏、显卡、网卡这些硬件的驱动适配，在不同批次的飞腾板上差异很大。如果安装过程中遇到跟驱动相关的奇怪问题，先确认一下硬件型号和驱动状态，再排查软件原因。

1.2 装Qt到底有哪几条路

我在动手之前把路径摸了一遍，大致有三条：

• 路径A：银河麒麟软件源直接apt安装。优点是命令短、装得快，缺点是源里的Qt版本不一定正好是5.12.8，可能是5.11或5.15，而且有些是定制裁剪过的。如果对版本号没有强迫症，日常开发用这个最省心。
• 路径B：Qt官网提供的离线安装包（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-dev：OpenGL开发库，Qt的opengl模块、以及很多图形渲染路径都要用。
• libfontconfig1-dev和libfreetype6-dev：字体配置和字型渲染，Qt文本绘制依赖它们，不装的话界面文字会异常。
• libx11-dev：X11协议开发头文件，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-0，Qt程序一启动就报键盘相关错误，苦查了半天。

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：这是我在飞腾平台上的核心选择。因为很多飞腾主板配的显卡是景嘉微或者其他国产GPU，OpenGL驱动往往不完整，与其后面被各种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.sh：

sudo 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_PLATFORM=xcb

说明一下这几个变量的作用：

• QTDIR：Qt的根目录，很多工具和脚本会引用它。
• PATH：让qmake、moc、rcc等工具可以直接在命令行使用。
• LD_LIBRARY_PATH：程序运行时动态库的搜寻路径。Qt程序启动时会去这里找libQt5Core.so等文件，不配的话会报cannot open shared object file。
• QT_PLATFORM_PLUGIN_PATH：指示平台插件目录。xcb插件就在这个目录下。
• QT_QPA_PLATFORM=xcb：指定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，依次配置：

1. 打开工具 -> 选项 -> 编译器。
2. 在GCC那一栏，添加C编译器/usr/bin/gcc，C++编译器/usr/bin/g++，通常系统会自动检测到。
3. 切到Qt Versions，点击添加，选择/opt/Qt5.12.8/bin/qmake。如果显示版本为“Qt 5.12.8 (qt5.12.8)”，就说明识别成功。
4. 切到Kits，新建一个Kit，把上面添加的Compilers和Qt Version选进去，CMake保持自动即可。
5. 创建一个新的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_MODULE=fcitx export GTK_IM_MODULE=fcitx export XMODIFIERS=@im=fcitx

这三条可以追加到/etc/profile.d/qt.sh里，全局生效。设置完记得fcitx restart，或者注销重新登录，输入法就能在Qt程序里唤出来了。

3.5 坑五：编译太慢、内存不足被OOM

Qt源码编译是一项大工程，全量包的qt-everywhere在飞腾平台上编译一次动辄一小时以上。如果configure时没裁剪模块、make时又用了-j$(nproc)，8核机器全核编译时内存峰值可能冲到十几G，OOM后就无提示地杀掉编译器。

我的建议是：

• 只想做界面开发，就只编qtbase-opensource-src-5.12.8.tar.xz，体积小很多。
• 如果编全量包，在configure里加-skip qtwebengine -skip qt3d -skip qtgamepad，把用不到的重型模块全跳掉。
• make并发行数根据内存来定：4G内存用-j2，8G用-j4，16G以上再考虑-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. 常见问题速查（我的实战笔记）

这个表格里的问题，都是我实际踩过、验证过的。遇到类似现象直接对号入座，基本都能快速定位。

最后再分享一个小技巧：在国产平台上做开发，遇到报错先别急着去网上搜索大段的问题描述，先用file和ldd两个命令把二进制文件的架构和依赖摸清楚，再用ldd检查缺失库，往往答案就在那里等着你。这个环境搭好之后，后面不管是做界面工具还是移植业务系统，都会顺很多。希望这篇记录能帮你少走弯路，早日把QT5.12.8在这个组合上跑起来。