企业官网建设流程全解析

1. 先搞清楚你的麒麟是什么版本：架构和内核决定了安装方式

1.1 确认 CPU 架构和系统版本

在拿到一台预装银河麒麟V10的机器时，先别急着下载Qt安装包。虽然界面长得差不多，但V10这个版本号背后至少有两条主要分支：基于Linux 4.4内核的桌面版、基于Linux 5.4或更新内核的SP1/SP2版本，以及面向不同CPU架构的版本。安装方式完全不一样。

打开终端，执行下面两条命令：

cat /etc/os-release uname -m

/etc/os-release里能看到系统名称、版本号，比如Kylin V10 SP1还是Kylin V10 SP2。uname -m输出的是CPU架构，常见的有：

• x86_64：兆芯、海光、Intel、AMD等芯片
• aarch64：鲲鹏、飞腾等ARM架构芯片
• mips64el：龙芯
• sw_64：申威

这几个架构直接决定了你下载哪个版本的Qt安装包。网上很多教程默认是x86_64，拿去照抄到飞腾机器上，大概率第一步就跑不起来。另外还要留意系统是桌面版还是服务器版，服务器版通常没有图形界面，安装Qt Creator意义不大，更多是装Qt运行时库和交叉编译工具链。

1.2 Qt 5.12 的官方安装包为什么不是万能的

Qt官方提供三种安装途径：在线安装器、离线安装包、源码编译。但这三种对银河麒麟都谈不上友好。

在线安装器需要登录Qt账号，而且下载速度不稳定，在国产化环境的内网受限场景下基本不可用。离线安装包虽然不需要联网，但官方只提供有限的架构版本，x86_64的Linux离线包很好找，aarch64的离线包也有一部分，但mips64el和sw_64就完全没戏。源码编译在龙芯、申威这种架构上是唯一选择，但5.12这个版本的源码在旧平台上编译，坑非常多，光是配置-platform linux-generic-g++和调整mkspec就要折腾半天。

所以，动手前先做一个判断：

• 如果机器是x86_64，优先下载官方离线包，省心。
• 如果是aarch64，可以尝试官方在线安装器选择aarch64组件，或者找厂商适配包。
• 如果是mips64el或sw_64，老老实实走源码编译路线，或者改用系统仓库里带的老版本Qt。

我这次用的是一台x86_64的银河麒麟V10桌面版，所以主流程以官方离线包为准，后面也会把apt安装和源码编译的路线一并讲清楚。

2. 安装前的依赖环境：这一步能省下你90%的排查时间

2.1 更新系统仓库与基础编译工具

银河麒麟V10的软件仓库继承了Debian系的结构，包管理工具是apt。虽然系统自带的qt版本可能不是5.12，但我们需要在安装Qt之前先把基础编译环境搭好，否则后面即使装上了，也没法正常编译程序。

先执行：

sudo apt update sudo apt upgrade -y

然后安装编译最基础的包：

sudo apt install -y build-essential gcc g++ make perl wget

这里有个容易被忽略的点：Qt 5.12编译程序时会用到g++，但麒麟默认可能只装了gcc，或者两者版本不一致。稳妥的做法是装完build-essential后手动确认一下：

gcc --version g++ --version

如果g++没有安装，编译时会有类似g++: command not found的错误，而且报错时机是在qmake生成Makefile之后才出现，很容易让人以为是Qt安装的问题。

2.2 补全 Qt 依赖库：libxcb、GL、input

Qt 5.12在Linux桌面环境的图形界面依赖大量运行库，比如xcb插件、OpenGL库、字体库等。这些依赖如果缺失，最常见的结果是Qt Creator能启动但白屏，或者启动直接报错：

Failed to load platform plugin "xcb"

这个错误几乎承包了Qt在Linux上90%的启动故障。要提前避免，装Qt前先把依赖补全：

sudo apt install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \ libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 \ libxcb-xfixes0 libxcb-xkb1 libxkbcommon-x11-0

接着是OpenGL相关的库：

sudo apt install -y libgl1-mesa-dev libegl1-mesa-dev libgles2-mesa-dev

还有字体和基础图形库：

sudo apt install -y libfontconfig1 libfreetype6 libxrender1 libx11-xcb1 libsm6 libice6

这些包在大多数Debian系源里都有，银河麒麟源里一般也包含。装上之后，Qt的xcb插件才能找到所有依赖的.so文件。如果不确定装全了没有，后面我会说用ldd排查的办法，这里先不用纠结。

2.3 国产机型特殊注意事项：飞腾/鲲鹏/兆芯

如果你用的不是x86_64机器，依赖包的名字会稍有差异，但总体思路一致。重点说一下aarch64机器上的一个常见坑。

飞腾和鲲鹏都是ARM架构，系统里默认的Qt库如果是从软件仓库装的，包名一样的。但有些机器预装的是用厂商交叉编译链编译的Qt，这时去装官方离线包，即使架构匹配，也可能因为libstdc++.so.6版本不匹配而报错。解决思路是优先使用系统本身的Qt版本，或者把编译链切换成Ubuntu官方工具链。

兆芯机器虽然是x86_64，但有些老旧机型集成的显卡驱动比较特殊，比如只支持VESA framebuffer，不支持完整的OpenGL。这种情况在启动Qt程序时可能会提示GLX相关错误，后面我会给一个临时环境变量方案，让Qt用软件渲染，能绕过去。

3. 安装 Qt 5.12 的完整流程：离线包和 apt 两条路怎么选

3.1 官方离线安装包方式

拿到Qt 5.12.x的Linux x86_64离线安装包后，比如常见的qt-opensource-linux-x64-5.12.10.run，先给它执行权限：

chmod +x qt-opensource-linux-x64-5.12.10.run

然后直接运行：

sudo ./qt-opensource-linux-x64-5.12.10.run

这里我建议加sudo，因为安装目录默认是/opt，普通用户没有写权限。如果你打算装到用户目录，可以不加sudo，安装路径改成/home/用户名/Qt。

图形化安装界面和Windows上差不多，但有几个点容易踩坑。

第一，登录环节。Qt开源版安装时需要验证邮箱或者账号，虽然不是强制填写全部资料，但很多人卡在这里。如果网络不佳，建议网络配置好后再操作，或者直接断网运行，某些版本会跳过登录校验。

第二，组件选择。默认勾选的组件不一定包含桌面版的Qt库，尤其是Qt 5.12.10下面的Desktop gcc 64-bit这个组件，必须手动勾选，否则装完你会发现/opt下根本没有qmake和Qt库文件。

第三，安装路径尽量保持简单。不要带空格和中文路径，编译工具链和一些插件对路径中文支持并不好。

安装完成后，在/opt/Qt5.12.10目录下会看到几个子目录，重点是5.12.10/gcc_64，里面就是Linux x64的Qt库和qmake工具。

3.2 用静默模式安装 Qt 5.12

如果机器没有桌面环境，或者图形安装界面卡住起不来，可以改用静默模式。Qt官方安装器支持命令行参数，虽然不同版本参数略有差异，但基本套路是：

./qt-opensource-linux-x64-5.12.10.run --script qt-installer.qs --platform minimal

其中qt-installer.qs是一个JavaScript脚本文件，用来自动应答安装过程中的各种选项。脚本核心内容大致是这样的：

function Controller() { installer.autoRejectMessageBoxes(); installer.installer.setOnFinishedCallback(function() { gui.clickButton(buttons.NextButton); }); } Controller.prototype.WelcomePageCallback = function() { gui.clickButton(buttons.NextButton); }; Controller.prototype.CredentialsPageCallback = function() { gui.clickButton(buttons.NextButton); }; Controller.prototype.ComponentSelectionPageCallback = function() { var widget = gui.currentPageWidget(); var components = widget.deselectAll(); widget.selectComponent("qt.5131.gcc_64"); gui.clickButton(buttons.NextButton); };

不同版本组件名不一样，这里的qt.5131.gcc_64只是示例。要查对应版本的组件ID，可以把Components.xml文件从安装包里解压出来看。不过说实话，如果只是想在普通桌面上用Qt，图形化安装更直观，静默模式更多是用在批量部署VNC服务器或者无屏终端时。

3.3 apt 安装 Qt 的方式与版本差异

银河麒麟的软件仓库里其实有Qt相关包，但版本一般不是5.12，大概率是5.11或者5.15，不同版本系统不一样。如果你的项目不锁定Qt版本，用apt直接装其实最省事：

sudo apt install -y qt5-default qttools5-dev-tools qtbase5-dev

这样安装会同时装好qmake、Qt5核心库和Qt Creator跨平台IDE（如果qtcreator包存在的话）。检查安装结果：

qmake --version

如果显示版本是5.12开头，恭喜你，这是最省事的路径。如果显示版本不对，比如是5.11或者Qt4，说明源里的包版本被旧版覆盖了，这时要么调整源，要么卸载后改用官方离线包。

这里提醒一点：qt5-default这个包在较新的Ubuntu/Debian源里可能已经被移除，改由qtbase5-dev直接提供qmake。如果安装时提示找不到qt5-default，就只装qtbase5-dev和qttools5-dev-tools。

3.4 环境变量配置

不管用哪种方式装完Qt，环境变量这块都绕不开。官方离线包的默认安装路径是/opt/Qt5.12.10/5.12.10/gcc_64，把这个路径加到PATH里，让终端能找到qmake。

打开~/.bashrc，在末尾加上：

export QTDIR=/opt/Qt5.12.10/5.12.10/gcc_64 export PATH=$QTDIR/bin:$PATH export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH=$QTDIR/plugins export QT_QPA_PLATFORM_PLUGIN_PATH=$QTDIR/plugins/platforms

然后执行：

source ~/.bashrc

这里有几个变量要解释一下。QTDIR是Qt的安装根目录，很多工具链脚本和插件会引用它；LD_LIBRARY_PATH让程序运行时能找到Qt的.so动态库；QT_PLUGIN_PATH和QT_QPA_PLATFORM_PLUGIN_PATH则是让Qt运行时能找到插件目录，尤其是xcb平台插件，少了这个变量，即使qmake能用，程序启动时也会报找不到平台插件。

如果你是用apt装的Qt，路径通常已经被自动配置好，不需要手动设置这些变量，直接调用qmake即可。

4. Qt Creator 启动失败与界面异常的排查手记

4.1 "Failed to load platform plugin xcb" 的常见成因

这是我在麒麟系统上碰到过最多的问题，没有之一。现象是安装好Qt Creator，双击图标或命令行启动，终端里输出：

qt.qpa.plugin: Could not find the Qt platform plugin "xcb" in "" This application failed to start because no Qt platform plugin could be initialized. Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.

很多人看到这个提示第一反应是去重新安装xcb插件，但其实大多数情况是插件依赖的底层系统库不全，而不是插件本身缺失。

用ldd检查xcb插件依赖的库，能快速定位：

ldd /opt/Qt5.12.10/5.12.10/gcc_64/plugins/platforms/libqxcb.so

这条命令会列出libqxcb.so依赖的所有共享库。如果输出里出现某个.so显示not found，那就是缺依赖。我在一台麒麟V10 SP1上遇到过缺libxcb-xinerama.so.0，用apt装上libxcb-xinerama0后问题马上解决。

4.2 用 ldd 快速定位缺失的 .so

ldd是好东西，但要注意它只能检查直接的动态链接依赖，如果某个依赖的.so本身又有缺失依赖，那一层不一定能直接看到。所以当ldd输出里所有项目都没有not found，但还是报xcb加载失败，可以试试用LD_DEBUG环境变量启动Qt Creator：

LD_DEBUG=libs /opt/Qt5.12.10/Tools/QtCreator/bin/qtcreator 2>&1 | grep -i "not found"

这样能输出每次动态库加载的详细过程，任何一层缺失都会被捕捉到。这个方法比ldd更底层，建议记下来。

4.3 显示服务器与 GL 渲染问题

在麒麟桌面环境里，如果Qt程序能启动，但窗口空白、闪烁严重，或者直接报Could not initialize GLX，这通常是OpenGL渲染链路出了问题。

国产桌面环境有些默认走的是X11协议，但后端渲染可能用的是软件渲染，比如Mesa的llvmpipe。这时可以用环境变量强制Qt使用软件OpenGL：

export QT_XCB_FORCE_SOFTWARE_OPENGL=1

这个变量告诉Qt即使检测不到硬件OpenGL，也允许用软件渲染模式。代价是3D性能会下降，但至少界面能正常运行。调试结束后，如果确认硬件GL没问题，可以把这个变量去掉。

还有另一个变量也经常用到：

export QT_QPA_PLATFORM=xcb

如果程序默认选了offscreen或者eglfs导致看不到窗口，强制指定xcb平台可以解决。

4.4 用命令行启动 Qt Creator 获得详细报错

不要双击图标启动Qt Creator，而是从终端启动：

/opt/Qt5.12.10/Tools/QtCreator/bin/qtcreator

这样当启动失败时，终端里会留下完整的错误信息。如果你双击图标启动，错误信息会被吞掉，或者弹一个干巴巴的对话框，根本没法定位。

在排查过程中，我还遇到过一种情况：命令行启动完全没有输出，进程卡住，界面不出来。用ps aux | grep qtcreator看到进程还在，但没有任何窗口。这种大多是Qt Creator在等待某个系统服务，比如dbus，或者权限不够。可以试试用普通用户启动，别带sudo；如果必须用root调试，加上-d参数查看调试日志。

5. 第一个 Qt 程序：编译过程与常见错误

5.1 编写一个最小窗口程序

环境准备好之后，写一个最简单的Qt程序来验证整个工具链是否可用。

创建一个目录hello_qt，里面放两个文件。

main.cpp：

#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Hello, Kylin Qt!"); label.resize(200, 100); label.show(); return app.exec(); }

hello_qt.pro：

QT += widgets SOURCES += main.cpp TARGET = hello_qt

这个工程文件告诉qmake项目需要widgets模块，源文件是main.cpp，生成的程序名是hello_qt。

5.2 qmake 和 make 构建

在项目目录下执行：

qmake make

qmake会读取hello_qt.pro生成Makefile，这一步如果报错，多半是qmake找不到Qt库路径，检查一下环境变量里的QTDIR和PATH是否正确。make执行时如果报缺少头文件，比如找不到QApplication，说明qtbase5-dev或者对应开发包没装好。

编译成功后会生成hello_qt可执行文件。但是直接运行大概率会失败，因为程序运行时的动态库路径没有配置。这也是新手最容易困惑的地方，编译成功了不代表能运行。

在运行前，设置动态库路径，或者直接在命令行执行：

export LD_LIBRARY_PATH=/opt/Qt5.12.10/5.12.10/gcc_64/lib:$LD_LIBRARY_PATH ./hello_qt

如果界面窗口正常弹出，说明Qt工具链已经完整可用，这一步就算过关了。

5.3 部署到目标机器：linuxdeployqt 还是手动拷贝

开发机上运行成功后，如果想把程序部署到其他没有安装Qt的麒麟机器上，需要解决动态库依赖问题。常见的做法是使用linuxdeployqt工具，但要注意版本兼容性。

linuxdeployqt在Ubuntu 18.04上编译的版本拿到麒麟V10上可能因glibc版本不一致而无法运行。我发现更稳妥的是手动拷贝：

• 把编译出来的可执行文件拷到目标机器
• 用ldd列出所有Qt相关动态库
• 手动拷贝缺失的库到程序同级目录的lib子目录
• 设置LD_LIBRARY_PATH指定为程序所在目录的lib

对于一个小程序，这套手动流程已经很够用。linuxdeployqt的优势是自动处理依赖和打包，但碰上glibc版本敏感的环境，反而更折腾。

5.4 中文乱码与字体问题

银河麒麟系统的中文字体默认是有的，但Qt程序在某些场景下会出现中文显示成方块或者乱码。原因多半不是Qt本身的问题，而是系统缺少对应的中文字体或者locale没设置好。

在终端里检查：

locale

如果LANG不是zh_CN.UTF-8，设置一下：

export LANG=zh_CN.UTF-8

如果字体显示不正常，安装中文字体包：

sudo apt install -y fonts-noto-cjk fonts-wqy-zenhei

安装完字体后，Qt程序不需要重启系统，但可能要重启一下程序才能刷新字体列表。在编写程序时，也可以直接用代码指定字体：

QFont font("Noto Sans CJK SC"); app.setFont(font);

6. 装机后记：一些长期使用才发现的细节

6.1 快捷方式与图标

安装完Qt Creator后，如果桌面上没有图标，可以自己创建一个.desktop文件。在/usr/share/applications/下建一个qtcreator.desktop，内容大致：

[Desktop Entry] Name=Qt Creator Comment=Qt IDE Exec=/opt/Qt5.12.10/Tools/QtCreator/bin/qtcreator Icon=/opt/Qt5.12.10/Tools/QtCreator/share/qtcreator/resources/logo.png Terminal=false Type=Application Categories=Development;

注意Exec要写实际安装路径，Icon可以选择一个存在的图标文件。如果图标路径不对，快捷方式会显示为空白，不影响使用但不太美观。

6.2 版本升级 vs 保留自定义 Qt

银河麒麟V10系统更新比较频繁，从V10 SP1升级到SP2，每次升级后Qt的库文件有可能被系统包覆盖，或者被apt的依赖检查标记为冲突。

我的经验是：如果你用的是官方离线包，安装在/opt下，和系统包的/usr/lib基本隔离，升级影响不大。但如果用的是apt安装的Qt，系统升级时有可能会升级Qt版本，这时候要注意你的项目代码是否还兼容。

建议在项目里写好QMAKE路径，避免系统升级后qmake版本切换导致Makefile重建出错。

6.3 命令行工具链的补充

除了Qt Creator，建议把gdb和valgrind也装上，调试内存问题时非常有用：

sudo apt install -y gdb valgrind

麒麟系统上valgrind在aarch64架构下的支持比较完善，但mips64上可能需要自己编译。不过这些问题只要在开始安装Qt前想到，后面会省很多事。

回头总结这次安装过程，最深的体会是：银河麒麟V10虽然基于Linux，但和通用Ubuntu/Debian相比，软件源里的包版本普遍偏老，编译工具链也不完全一致。很多人安装Qt失败，并不是Qt本身的问题，而是依赖环境没有梳理清楚。只要按照"确认架构 -> 补齐依赖 -> 选择安装方式 -> 配置环境变量 -> 验证编译链路"这个顺序走，整个流程是可以稳定复现的。

最后再分享一个小技巧：如果在一台干净的麒麟系统上需要给团队批量部署Qt环境，可以把依赖包列表导出成一个脚本，用apt离线安装的方式统一推送，比每台机器手动点安装器要高效得多。