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、inputQt 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 快速定位缺失的 .soldd是好东西但要注意它只能检查直接的动态链接依赖如果某个依赖的.so本身又有缺失依赖那一层不一定能直接看到。所以当ldd输出里所有项目都没有not found但还是报xcb加载失败可以试试用LD_DEBUG环境变量启动Qt CreatorLD_DEBUGlibs /opt/Qt5.12.10/Tools/QtCreator/bin/qtcreator 21 | grep -i not found这样能输出每次动态库加载的详细过程任何一层缺失都会被捕捉到。这个方法比ldd更底层建议记下来。4.3 显示服务器与 GL 渲染问题在麒麟桌面环境里如果Qt程序能启动但窗口空白、闪烁严重或者直接报Could not initialize GLX这通常是OpenGL渲染链路出了问题。国产桌面环境有些默认走的是X11协议但后端渲染可能用的是软件渲染比如Mesa的llvmpipe。这时可以用环境变量强制Qt使用软件OpenGLexport QT_XCB_FORCE_SOFTWARE_OPENGL1这个变量告诉Qt即使检测不到硬件OpenGL也允许用软件渲染模式。代价是3D性能会下降但至少界面能正常运行。调试结束后如果确认硬件GL没问题可以把这个变量去掉。还有另一个变量也经常用到export QT_QPA_PLATFORMxcb如果程序默认选了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.proQT widgets SOURCES main.cpp TARGET hello_qt这个工程文件告诉qmake项目需要widgets模块源文件是main.cpp生成的程序名是hello_qt。5.2 qmake 和 make 构建在项目目录下执行qmake makeqmake会读取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 LANGzh_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] NameQt Creator CommentQt IDE Exec/opt/Qt5.12.10/Tools/QtCreator/bin/qtcreator Icon/opt/Qt5.12.10/Tools/QtCreator/share/qtcreator/resources/logo.png Terminalfalse TypeApplication CategoriesDevelopment;注意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离线安装的方式统一推送比每台机器手动点安装器要高效得多。