直接开工不多说废话。最近在国产化环境里折腾了一套银河麒麟V10桌面系统业务需求是跑一个基于QT的图形化工具。原以为QT这玩意儿跨平台安装很成熟结果在国产系统上踩坑踩到怀疑人生——光是一个QT5.12就翻来覆去折腾了三天。倒不是说多难而是网上资料零散很多还是抄来抄去的老旧方案拿来就用容易翻车。这篇博文把我整个安装过程、踩过的坑、排查思路全部还原出来包含从环境检查、依赖安装、源码编译、qmake配置到Qt Creator开发环境验证的完整闭环。目标读者是需要在银河麒麟V10上搭建QT开发环境的人不管你是想做国产化适配、还是给业务系统搞个Linux客户端这套流程都可以直接照搬。我会尽量把每一步为什么这么做、遇到问题怎么排查都讲清楚省得你再去当小白鼠。1. 安装前的环境盘点与方案选型1.1 先搞清楚你的银河麒麟V10是个什么版本银河麒麟V10这名字听着简单实际拆开很多讲究。我这边遇到的是桌面版内核版本5.4.18CPU是AMD64架构。但你要知道银河麒麟V10还有ARM版、X86版还分SP1、SP2更新批次不同版本之间依赖库版本差异挺大这直接决定了你后面装QT的方式。先跑几条命令把家底盘清楚# 查看系统版本信息 cat /etc/os-release # 查看内核版本 uname -a # 查看CPU架构 lscpu | grep Architecture我机器上输出的是Kylin V10 SP1内核5.4.18-142-genericX86_64架构。这个信息很关键因为你找安装教程、查依赖报错的时候先确认自己和别人是不是同一个环境。有人拿ARM64的教程套X86的机器依赖包名字都对不上那不是浪费时间嘛。另外要看清楚系统是否激活。没有激活的银河麒麟系统软件源默认是连不上的你apt update会直接报错或者卡住很久。检查激活状态可以用kysec-get-status # 或者直接在系统设置里看激活信息如果没激活先走激活流程这一步偷懒的话后面装依赖寸步难行。我这边系统是已经激活的状态软件源指向的是官方源但速度确实一般几百KB/s的样子要有心理准备。1.2 三种安装方案怎么选源码编译、离线包、发行版仓库QT在Linux上安装就那么几条路我根据自己的测试经验列个表格安装方案优点缺点推荐指数源码编译兼容性最稳可定制编译选项编译时间长full build 1-2小时以上依赖要求多★★★★★QT官方在线安装包安装方便组件选择灵活银河麒麟默认无桌面版QT环境在线安装器依赖GL库易报错★★☆☆☆发行版仓库apt安装命令简单qmake自动配置好版本偏旧通常5.11或5.12组件不全★★★☆☆离线二进制包不依赖网络安装快需要匹配架构和系统版本小白容易下错包★★★☆☆我最终选的是源码编译。原因很简单国产系统的GL库、X11库路径和Ubuntu这类标准发行版有差异在线安装器经常卡在平台插件检测那一步仓库里的QT版本又不够用。源码编译虽然慢但成功的确定性最高而且后续你想编静态库、调WebEngine等模块源码包最配合。如果你只是跑个现成QT程序不需要动QT本身那直接apt install qt5-default就行但如果要装完整开发环境源码编译更省心。后面的实操流程我按源码编译来写。2. 编译依赖安装半个小时的耐心活2.1 需要准备哪些编译工具和依赖库QT5.12编译对系统环境的要求不少缺一个库编译到中途就会报错回头看还挺折腾。提前把依赖装齐是最省时间的做法我这里直接把需要的包分成两类编译工具链和运行时依赖库。编译工具链必须有gcc、g、make这些是基础。银河麒麟V10默认可能带了gcc但g不一定先检查一遍gcc -v g -v make -v如果没装用apt补上。然后是一大堆运行时依赖主要给QT的各个模块用sudo apt update sudo apt install -y libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev sudo apt install -y libx11-dev libxext-dev libxrender-dev libxrandr-dev libxfixes-dev libxi-dev libxcb1-dev sudo apt install -y libxkbcommon-dev libxkbcommon-x11-dev libfontconfig1-dev libdbus-1-dev sudo apt install -y libsm-dev libice-dev libpulse-dev libasound2-dev sudo apt install -y libssl-dev libsqlite3-dev libjpeg-dev libpng-dev libtiff-dev我一开始没装libxkbcommon和libxcb相关包编译出来的QT运行时Qt Creator起不来报错“xcb plugin无法加载”后来补装重编才解决。这套依赖包里有些在银河麒麟源里名字略有出入找不到就apt search一下相近名字。2.2 在国产系统上安装依赖的注意事项这里重点说三个坑都是我这个环境实测踩出来的。第一个是GL库。银河麒麟V10桌面版为了适配国产显卡GL库做了软件渲染实现llvmpipe你编译QT时如果检测不到OpenGLconfigure会直接跳过很多模块。装libgl1-mesa-dev、libglu1-mesa-dev就是为了让configure阶段能认出来GL支持。如果你机器上有独立显卡景嘉微、兆芯等可能还需要显卡厂商额外的驱动包但只跑软件渲染的话mesa这套就能过。第二个是apt源速度。银河麒麟默认软件源慢是出了名的装依赖包还好总量不算大实在慢可以换镜像站。但这里注意麒麟系统的源配置文件在/etc/apt/sources.list换源之前先备份别把源结构改坏了。我换过一段时间国内高校镜像稳定性不错但有的镜像更新不及时会出现个别包404这时候切回官方源把缺的包装上再切回来就行。第三个是依赖完整性。很多人装到一半报错回头发现是缺了某个基础库。我的建议是用一条命令把所有包串起来装不要分多次减少中间遗漏。还有编译的时候建议挂一个终端专门记录输出sudo apt install -y 上面的依赖列表 21 | tee apt-install.log后面出问题还能翻日志查缺了哪个库。3. 下载QT5.12源码与configure配置实战3.1 源码包从哪里获取、怎么校验完整性QT5.12源码官方托管在download.qt.io国内直连速度时好时坏。我建议优先用清华、中科大的镜像站下载速度稳定很多。用的具体文件是qt-everywhere-src-5.12.12.tar.xz5.12系列的最后一个更新版直接选12小版本修复了不少bug。下载完成后务必校验SHA256防止文件损坏导致编译到一半报错。官方哈希值在源码包旁边的.md5和.sha1文件里我为了稳妥直接对比了官方记录的SHA1值echo 官网给你的SHA1值 qt-everywhere-src-5.12.12.tar.xz | sha1sum -c -匹配再解压。这一步不只是洁癖源码包损坏在编译时会出现各种诡异的g错误排查起来极度浪费时间。解压后源码目录大概3GB左右编译产物还要再占几GB提前看下磁盘空间df -h至少留出10GB空闲空间我机器上只剩5GB的时候编译到qtwebengine直接磁盘写满报错清了一堆缓存才继续。3.2 configure参数怎么选既要精简又要够用QT5.12的configure配置项非常多不用全懂但关键的几个得明白含义。我最终使用的configure命令如下cd qt-everywhere-src-5.12.12 ./configure -prefix /opt/Qt5.12.12 \ -release \ -opensource -confirm-license \ -xcb -xkbcommon \ -glib \ -dbus \ -fontconfig \ -system-libpng -system-libjpeg -system-zlib \ -no-openssl \ -nomake examples -nomake tests \ -skip qtwebengine -skip qtcharts -skip qtdatavis3d逐项解释一下我为什么这么选-prefix /opt/Qt5.12.12安装路径我统一放在/opt下方便后面配置环境变量和让其他用户使用。-release只编译release版不编debug版省一半时间。平时开发调试用release也够真需要debug再重编。-opensource -confirm-license开源版自动接受LGPL协议。-xcb -xkbcommon这两个是QT在X11下正常运行的关键鼠标键盘事件、窗口渲染都靠它们。第一次编的时候漏了xkbcommon结果所有基于XCB的平台插件跑起来都输入异常。-glib和-dbus让QT和系统底层事件循环、消息总线更好配合麒麟这种基于Debian的系统建议打开。-no-openssl我项目暂时不需要QT内置SSL模块系统自己带OpenSSL后续要可以单独编。这个选项能少编译一堆东西。-skip qtwebengineqtwebengine是编译时间大头Chromium内核光下载就烦不用浏览器类功能直接skip省出至少40分钟。注意如果你需要QT的WebEngine做混合开发这个不能跳。-nomake examples -nomake tests不编示例和测试能省好几GB空间和时间。configure跑完以后会生成一个summary里面列了QT各模块启停状态。务必扫一眼确认xcb、xkbcommon这些你需要的模块都是yes状态如果有模块意外被disable先解决依赖再继续不要带着问题硬编。3.3 踩坑实录configure阶段最常见的两个报错configure阶段常见的报错有两个。一个是“Basic XLib functionality test failed”。这个通常是缺X11开发库回去补装libx11-dev、libxext-dev就能解决。我当时遇到这个报错时第一反应是查编译器版本后来才发现纯粹是依赖包没装全。另一个是“Could not find qmake”之类——这个不是真的缺qmake而是configure后生成的临时qmake没跑起来多半是权限或者磁盘空间问题。我把源码目录放在用户目录下结果/home分区快满了临时文件写不进去。清理磁盘后重新configure就好了。configure报错时不要慌直接去看源码目录下的config.log搜error关键字基本能定位到具体是哪个测试程序编译失败。把这个信息粘贴到搜索引擎里比盲目重试效率高得多。4. 编译安装马拉松开始4.1 make编译的命令与耗时configure通过后就到了最磨人的编译阶段。QT5.12完整编译用make -j4大概要一个半到两个小时-j后面的数字根据CPU核数来。先看核数nproc我机器是4核直接用make -j4 21 | tee make.log建议先不加-j跑慢一点不存在的时间宝贵该并行就并行。但-j8这种超出核数的参数不推荐反而会因为上下文切换导致编译更慢还可能内存耗尽。4核机器老老实实-j4。编译过程中会有一大堆警告输出非常正常不用管。真正要看的是error关键字一旦出现编译错误make会自动停。我之前因为configure阶段没注意GL库编译到qtbase时直接报“cannot find -lGL”回头补装libgl1-mesa-dev后需要重新configure并清理之前的中间文件。编译期间可以偶尔看一下CPU温度和磁盘占用满负荷运行一小时对笔记本散热是个考验。台式机没问题笔记本建议垫高散热防止过热降频反而变慢。4.2 常见编译错误的处理思路编译QT最典型的三类错误我逐个说处理思路第一类是缺少系统库报错形如“fatal error: XXXX.h: No such file or directory”。这就回到第2章强调的依赖问题了。缺什么头文件就搜什么包apt search 名字先确认头文件属于哪个包然后安装对应的-dev包不需要重新configure直接从断点继续make就行。第二类是编译器内存不足报错通常是“internal compiler error: Killed”。这在中低配机器上很常见GCC编译大文件时内存峰值很高。解决办法是降低并行度比如-j4改成-j2或者临时增加swap。我当时加了4GB swap编译过程稳了不少。sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile第三类是qtwebengine模块下载Chromium源码卡住。这就是我为什么建议直接-skip qtwebengine的原因。真需要WebEngine的要么科学配置代理下载要么就用仓库里的老版本QT个人建议多数业务场景下用不到WebEngine直接跳过去最省心。4.3 安装到/opt并设置环境变量make完成后执行安装sudo make install安装时间不长几分钟就结束。完成后/opt/Qt5.12.12目录下就是完整的QT开发环境包含bin、lib、include、plugins等目录。这时候环境变量必须配好否则命令行敲qmake还是系统里没有的。修改用户级配置文件vim ~/.bashrc在末尾追加export QTDIR/opt/Qt5.12.12 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins保存后生效source ~/.bashrc然后验证qmake版本qmake -v能输出“QMake version 3.1 Using Qt version 5.12.12 in /opt/Qt5.12.12”就说明环境OK了。这里有个小细节如果系统里还有旧版qmake输出可能会指向老版本路径检查PATH顺序/opt/Qt5.12.12/bin要在前面。5. 图形界面开发环境与Qt Creator配置5.1 安装Qt Creator IDE编译完QT库还不够日常开发你需要一个好用的IDE。Qt Creator官网有Linux安装包但为了少折腾依赖我推荐用银河麒麟仓库里的版本sudo apt install qtcreator -y仓库里的Qt Creator版本可能不是最新的但对5.12的QT来说完全够用。装完以后从开始菜单或命令行启动qtcreator如果启动报错“libxcb-cursor0找不到”这是银河麒麟V10的系统库太老的典型问题。解决方法是装一个兼容库一般libxcb-cursor0在更新源里就有sudo apt install libxcb-cursor0装完再启动就能进界面了。5.2 Qt Creator里配置Kit编译器Qt Creator装好只是编辑器还需要告诉它用哪个qmake、哪个编译器才能编译项目。在菜单栏选“工具 - 选项 - Kits - Qt Versions”点击“添加”路径选/opt/Qt5.12.12/bin/qmake。然后切到“Compiler”页签确认gcc和g自动检测到了没有就手动添加。最后在“Kits”页签新建一套工具链把Qt Version指向刚添加的5.12.12编译器选系统gcc/gCMake可以用系统自带版本。配置完成后建一个空的Qt Widgets Application测试项目编译运行能弹窗口说明整套环境就通了。如果你只写命令行程序不需要QT界面那Qt Creator这一步可以跳过命令行里qmake make就够用。5.3 中文乱码和字体问题的快速修复银河麒麟V10上QT程序跑起来后中文显示容易出两个问题一个是界面中文乱码一个是文本编辑器打开后中文乱码。界面中文乱码多半是字体缺失或编码设置不对。在main函数里加上这行代码QApplication::setFont(QFont(Noto Sans CJK SC, 10));如果系统里没有Noto Sans CJK SC字体先装一下sudo apt install fonts-noto-cjk -y文本编辑器乱码这个问题要分两头看。如果你说的是Qt Creator里的代码文件打开后中文变成乱码那一般是文件编码不是UTF-8在Qt Creator右下角切换编码到UTF-8就能解决。如果你说的是银河麒麟系统自带的文本编辑器打开QT生成的源码文件乱码问题也类似用系统设置把默认编码改成UTF-8即可。我测试时还发现一个隐蔽原因源码文件是GBK编码的QT Creator默认UTF-8打开直接乱码。解决方法是把源码统一转成UTF-8再编译iconv -f GBK -t UTF-8 main.cpp main_utf8.cpp5.4 打包发布ldd检查和依赖库拷贝开发环境搭好程序能跑接下来就是怎么把编译好的可执行文件拷到别的机器上跑的事情。Linux下没有Windows那种“拷贝exe就能跑”的优势QT程序依赖一堆动态库直接拷到没装QT的机器会报“cannot find -lQt5Core.so.5”。推荐用linuxdeployqt把这个过程自动化配置文件写好后执行./linuxdeployqt ./myapp -appimage它会自动把依赖的so文件拷过来生成AppImage格式的单文件拷到哪都能跑。如果不想用这工具手动ldd看看依赖ldd ./myapp输出里带/opt/Qt5.12.12路径的库都需要拷到目标机器的同级目录然后配置LD_LIBRARY_PATH指向它们。国产化环境下Qt程序的打包一直是痛点我建议早点把linuxdeployqt的流程熟悉起来免得每次交付程序都在目标机器上再编一遍。6. 常见问题汇总与快速排查手册6.1 发行版仓库安装QT时的几个坑不是所有人都必须源码编译仓库apt直接装也好用但有几个坑必须说清楚。第一个坑是版本覆盖问题。银河麒麟V10仓库里的qt5-default可能关联的是5.11或者更低版本装出来后如果你的代码用到了5.12新特性编译直接报错。用apt-cache policy qtbase5-dev查一下仓库里到底是什么版本再决定要不要用。第二个坑是仓库包拆得太细。qtbase、qtmultimedia、qtsvg等每个模块一个包漏装一个你的代码编译就缺头文件。建议先装qt5-default把基础的一套拉进来缺什么单独补。第三个坑是qtcreator自带的qmake版本和仓库QT版本不匹配。装完qtcreator后它可能默认用自己内置的qmake而你代码编译用的是仓库的qmake两个版本不一致会导致插件加载问题。老老实实在Kit配置里手动指定qmake路径。6.2 运行时报错快速排查表报错信息原因解决方案qt.qpa.plugin: Could not load the Qt platform plugin xcb缺libxcb相关库或平台插件路径不对确认QT_PLUGIN_PATH指向/opt/Qt5.12.12/plugins并安装libxcb-*系列cannot find -lGL缺OpenGL开发库sudo apt install libgl1-mesa-dev libglu1-mesa-devQStandardPaths: XDG_RUNTIME_DIR not set运行时目录权限问题export XDG_RUNTIME_DIR/tmp/runtime-$USER并chmod 700该目录程序中文字体显示为方块缺中文字体sudo apt install fonts-noto-cjkThis application failed to start because no Qt platform plugin could be initialized平台插件缺失或GL库问题检查libqxcb.so是否存在检查LD_LIBRARY_PATH是否有旧QT干扰这些是我目前总结的最常遇到的五类问题处理掉基本就能顺利跑起来。6.3 命令行安装软件的高频操作最后补充一些银河麒麟V10的软件管理命令算是通用知识不管装不装QT都用得上。# 安装本地deb包 sudo dpkg -i xxx.deb # 如果有依赖缺失自动修复 sudo apt -f install -y # 安装软件 sudo apt install -y 软件名 # 卸载软件 sudo apt remove --purge 软件名 # 查看某个软件是否安装 dpkg -l | grep 软件名 # 查看软件安装位置 which 软件名 # 查看软件版本 软件名 --version这些命令在银河麒麟V10各个桌面版本上都通用。很多刚转过来的朋友不习惯Linux的包管理体系其实记住“apt install就是装、apt remove就是卸、dpkg -i装本地包”这三个逻辑日常使用基本就顺了。遇到依赖问题先别慌apt -f install这种修复命令能解决大部分情况。7. 写在最后的实操体会装配QT5.12这次经历下来我最深的一个体会是在国产系统上装QT难点从来不是QT本身而是对系统生态的不熟悉。银河麒麟V10本质上是Debian系但仓库包的完整度、版本新鲜度、文档丰富度都和Ubuntu有差距遇到问题第一反应别去套用Ubuntu的教程先确认系统版本、架构、源是否可用再动手。另外一个建议就是编译前把依赖装齐configure完仔细看一遍summary把-j参数控制好这三件事做好了整个编译过程基本不会卡壳。很多人失败都是因为着急跳过依赖检查直接configure后边一个个报错补坑反而更慢。另外如果你只是需要用QT跑现成软件那真不用折腾源码编译下载对应的deb包装上就行。源码编译适合我这种要改QT源码、要定制模块、要静态编译的场景。动手前先想清楚需求能省一半力气。这套流程跑完之后我后续的工作就是在上面做业务系统的界面适配目前Qt Creator开发调试一切正常编译出的程序在麒麟V10和标准的Ubuntu 18.04上都能跑。有朋友最近也在折腾同款环境的话有问题欢迎留言我踩过的坑你大概率也会遇到咱们可以互相验证方案。