做国产化开发这两年在银河麒麟V10系统上装软件被问到最多的就是QT5.12怎么装。单独看“安装”两个字感觉就是跑一条命令的事但真正操作起来软件源、架构匹配、依赖库、Qt Creator套件配置哪个环节都可能把人卡住。我自己给同事和项目现场的机器装过不少次也踩过不少坑这篇直接把我验证过的完整流程和问题清单整理出来给需要的人当个参照。不管你是做桌面应用、工控上位机还是信创项目里要跑起来一个Qt开发环境这篇都适合先收藏再动手。1. 动手之前先摸清麒麟V10的家底很多人拿到系统后第一件事就是敲apt install qt5-default结果终端刷出一片依赖错误然后就懵了。其实多半不是命令的问题而是没搞清楚眼前这台麒麟V10到底是什么底细。银河麒麟V10并不是单一版本桌面版和服务器版不一样x86_64和ARM的差异也很大安装策略完全不通用。开始安装前花五分钟确认环境后面能少折腾半天。1.1 系统版本和架构决定后续所有选择先把这三条命令执行一遍cat /etc/os-release uname -m hostnamectl第一条查看具体版本是V10的哪个SP版本基于Debian还是其它上游第二条确认CPU架构最常见是x86_64在飞腾、鲲鹏这类机器上输出是aarch64。这个信息直接决定你该找哪个Qt安装包以及软件源该怎么配。比如x86_64桌面版可以正常跑Qt官方提供的.run离线包但aarch64机器找不到合适安装包的情况很常见可能就要走在线源或者让厂商提供适配好的编译版本。如果是装在一台已经跑了好几年的机器上最好再确认一下当前系统的更新状态比如sudo apt update是否能正常执行。源有问题的话后面所有依赖都装不顺这时候先别急着装Qt。1.2 包管理器确认apt还是yum银河麒麟V10桌面版大部分是基于Debian的上游包管理工具是apt但确实有部分服务器版本用的是yum/dnf使用习惯完全是两套。判断很简单which apt which yum哪条命令有输出后面就用哪套体系。如果用apt先把软件源更新一下sudo apt update更新源这一步如果报“无法解析”或“404”说明/etc/apt/sources.list里的源地址和当前系统版本不匹配或者网络有问题。先解决源的问题再继续不然后面几乎每一步都会报错。包管理器确认之后再决定用哪种方式装Qt不要混着乱敲。1.3 在线、离线、源码编译三条路怎么选这里先把三条路线摊开对比一下方便你根据自己的场景直接选安装方式优点缺点适合场景在线apt安装命令少、依赖自动处理版本不一定正好5.12部分模块缺失快速验证环境、对版本要求不高官方离线.run版本固定、目录清晰、可批量复用需要提前准备安装包图形安装界面偏老内网环境、正式项目交付源码编译可定制、可适配特殊架构依赖多、耗时长、编译坑多ARM等特殊平台、需要定制Qt模块我个人更推荐离线.run的方式。原因很简单安装包一次下载拷贝到其它机器上随时能装版本完全可控。在线apt虽然方便但仓库里的Qt版本经常不是理想的5.12装出来的IDE和库版本不是一套的话后面排查更费劲。源码编译留给确实有特殊需求的场景新手不要轻易尝试。2. 离线安装包方式安装Qt 5.12推荐路径离线安装是最稳妥的正攻法下面按步骤说说具体怎么做顺便把每一步背后的原因讲清楚。2.1 获取匹配架构的Qt 5.12安装包Qt 5.12的离线安装包命名一般是qt-opensource-linux-x64-5.12.12.run这里建议认准5.12.12这是5.12系列里修复问题比较多、也是很多国产系统上验证最多的版本。获取途径优先走Qt官方下载页或者在线安装器公司内部如果有共享安装包也完全可以关键是别从不明来源随便下一个编译环境里混入不可信文件后期很难排查。拿到安装包先核对一下架构x86_64对应x64的包aarch64不要强行运行x64包会提示cannot execute binary fileARM平台如果拿不到官方离线包可以尝试用在线安装器选对应平台组件或者找麒麟软件适配库、芯片厂商提供的成品Qt镜像。下载完的.run文件建议放到/home/用户/Downloads或者/opt这样的路径确保所在分区不能是noexec挂载否则执行时会毫无理由地报权限错误。动手前可以用sha256sum校验一下文件哈希特别是从网盘或者转发的渠道拿到文件时这一步能挡住不少损坏的包。2.2 图形化安装过程中的关键选项文件就位后先给执行权限chmod x qt-opensource-linux-x64-5.12.12.run ./qt-opensource-linux-x64-5.12.12.run如果启动时提示缺少libXrender.so.1、libXinerama.so.1之类的库先回系统把X11运行库补齐sudo apt install libxrender1 libxinerama1 libxkbcommon-x11-0安装器的图形界面是Qt自带的老版本跑起来有点慢耐心等。组件选择这一步是很多人闭眼乱点的重灾区。我建议这么选Qt 5.12.12下的Desktop gcc 64-bit必选这是核心库Qt Creator必选IDE本体按项目需要勾选Qt Charts、Qt Data Visualization、Qt WebEngine等不需要的别勾每个模块都是磁盘空间和编译时间的开销工具链部分如果系统还没装gcc/g后面单独用apt补这里不用管。安装路径默认会在用户目录下我习惯指定成/opt/Qt5.12.12避免与系统目录混在一起也方便多用户共同使用。整个安装大概占用2到4GB磁盘空间装之前用df -h看一下剩余空间。2.3 安装完先别急着开发环境变量配置安装完成不是结束不配环境变量的话终端里敲qmake依然是找不到命令。打开~/.bashrc把下面内容追加到末尾export QTDIR/opt/Qt5.12.12/5.12.12/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH然后让配置生效source ~/.bashrc如果你的安装路径是/home/用户名/Qt5.12.12对应把QTDIR里的路径换掉。验证一下qmake -v看到类似QMake version 3.1和Using Qt version 5.12.12的输出就说明基础环境已经通了。需要注意如果之前用apt装过qt5-qmake系统里可能存在两个qmake这时用which qmake确认当前用的是哪个。如果PATH顺序不对后面Qt Creator里也容易串版本不如把apt那个先卸掉或者手动调整环境变量顺序。3. 在线apt方式安装Qt 5.12组件离线包不是唯一选择某些临时机器上不方便传文件或者只想快速搭一个能编译Qt的环境在线安装也够用。这条路的重点是先把软件源和依赖库处理好。3.1 配置软件源与安装依赖库如果安装源本身没配置好在线安装直接不用往下走了。修改/etc/apt/sources.list之前先备份这是保命习惯sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak.$(date %F)替换源地址时最好参考官方提供的麒麟V10对应版本源或者选择开源镜像站里匹配发行版源的地址。改完以后执行sudo apt update确保能正常拉到索引信息。接下来安装的是整个Qt构建链路的运行基础缺了任何一个都会被编译器反复教做人sudo apt install build-essential g gdb make cmake sudo apt install libgl1-mesa-dev libglu1-mesa-dev libegl1-mesa-dev sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-image0 libxcb-shape0 libxcb-render-util0 sudo apt install libdbus-1-dev libfontconfig1-dev libssl-dev这里有个细节libxcb-*这类库是Qt的xcb平台插件运行时依赖经常有程序编译通过、一运行就崩最后查出来就是少了其中某一个小库。所以别嫌多先一次装齐。3.2 用apt安装Qt开发组件与IDE在线安装的命令本身不复杂sudo apt install qt5-default qtbase5-dev qtchooser qtcreator麒麟V10桌面版如果基于Debian 10系列qt5-default基本可以直接装上它会把默认的qmake和开发头文件关联好。qtbase5-dev是Qt5基础模块的开发包包含Widgets、Network、Core这些日常用得最多的库。需要额外模块时再单独装比如libqt5charts5-dev、libqt5webengine5-dev。这里要提醒一点apt源里的Qt版本不一定恰好是5.12装完先验证一下qmake -query QT_VERSION dpkg -l | grep qtbase5-dev如果显示的是5.11或者其他版本而项目又必须要求5.12那就老老实实回到第2节的离线安装路线。apt装的版本适合做环境快速验证但对版本有硬性要求的交付项目建议还是用离线包锁定版本。3.3 apt安装之后的版本差异与验证当系统里存在多个Qt版本时qtchooser是用来切换版本的工具。你可以用qtchooser -list-versions查看当前有哪些版本记录。手动安装的Qt 5.12和apt装的Qt如果同时存在Qt Creator里可以把两套都注册进来再配合不同的构建套件切换不过对新手来说同时维护两套版本很容易把自己的机器搞乱如果没有明确的版本兼容需求建议只保留一个主版本。在线安装的好处是系统升级时会跟着软件源更新补丁但也有个风险——某次apt upgrade可能动到Qt库导致之前的项目突然编不过。正式环境里可以把关键包锁定住不让系统自动升级替换sudo apt-mark hold qtbase5-dev qt5-default需要恢复时用apt-mark unhold。项目环境里小的依赖更新可能引起连锁反应锁版本是很多做过现场交付的人都会做的一步。4. Qt Creator套件配置让编译器、qmake、调试器对接环境变量配好、qmake能输出版本并不代表Qt Creator就能顺利编译项目。非常多人在这一步掉坑新建工程时提示No suitable kits或者套件名旁边一个黄色感叹号其实就是编译器、qmake、调试器这三个关键角色没对上。4.1 手动添加gcc/g编译器打开Qt Creator进入Tools - Options - Kits - Compilers面板。如果列表里已经有可用的GCC直接用没有的话手动添加Add - GCC - CName填GCC x86_64 (Kylin)Compiler path选/usr/bin/gccAdd - GCC - CCompiler path选/usr/bin/g。编译器路径里如果没有/usr/bin/gcc说明前面 build-essential 这步没装成功先回去补上。Qt Creator本质上是在调用系统编译器完成构建它自己不带gcc所以这步不做套件永远是废的。4.2 添加Qt Version并创建Kit切到Qt Versions标签页点击Add选择/opt/Qt5.12.12/5.12.12/gcc_64/bin/qmake。添加成功后会自动读取该qmake对应的Qt版本信息。注意qmake路径必须指向手动安装的那一份别选到/usr/bin/qmake——如果系统里同时有apt装的Qt这俩很可能不是同一个版本。接着去Kits标签页点击Add名字随便起建议叫Qt 5.12.12 KylinDevice type选DesktopCompiler选择刚才添加的gcc/gQt version选择Qt 5.12.12CMake选/usr/bin/cmakeDebugger选/usr/bin/gdb。配置完成后套件前面的状态应该变成绿色对勾。这里有个常见的低级错误Qt版本是64位的编译器却配成了32位交叉工具链两者位数不一致编译的时候会报各种各样的链接错误。确认套件里的qmake和编译器架构匹配否则Qt Creator再聪明也救不了你。4.3 用一个小项目验证环境是否正常套件配置好以后新建一个Qt Widgets Application构建套件选刚创建的Kylin Kit直接点运行。程序弹出一个空白窗口基本就说明整条链路通了。我习惯在验证项目里放一个QLabel显示一行Kylin Qt OK再点几个按钮确认信号槽正常。这一步跑通之后再开始正式写业务代码免得把环境和业务问题混在一起查。如果窗口能弹出来但是显示全黑、灰屏或者卡住不动大概率是OpenGL相关的问题下面第5节会说排查思路。5. 安装和开发中常见问题排查实录这部分算是整篇精华把实际踩过的坑按症状整理出来遇到问题对着抄就行。5.1 “xcb platform plugin”报错与缺失库处理这是Qt程序在Linux上运行最常见的报错没有之一。完整信息一般是This application failed to start because no Qt platform plugin could be initialized.后面可能还跟着xcb这样的关键字。原因是系统缺少Qt xcb平台插件依赖的X11相关运行库。第一步先打开调试模式让程序告诉你具体缺哪个库export QT_DEBUG_PLUGINS1 ./你的程序看到日志里报Cannot load library后面跟着的.so文件名基本就是缺哪个。通常把这一串装齐就够了sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-image0 libxcb-shape0 libxcb-render-util0 libxkbcommon-x11-0有些系统还额外需要libxcb-cursor0这个库在部分Debian 10源里没有如果没有就不要强行装了Qt 5.12并不强制依赖它。如果只是在服务器上做无界面测试可以用QT_QPA_PLATFORMoffscreen ./程序临时跑起来但这只能验证逻辑不能当正常显示环境用。5.2 缺少OpenGL头文件和运行库的处理编译阶段报GL/gl.h: No such file or directory是典型开发头文件缺失运行阶段报libGL.so.1: cannot open shared object file则是运行库缺失。两种情况各装各的sudo apt install libgl1-mesa-dev libglu1-mesa-dev mesa-utilslibgl1-mesa-dev提供头文件mesa-utils提供glxinfo等调试工具装完可以先用glxinfo | grep OpenGL version确认图形栈是否正常。在虚拟机和部分老显卡机器上即使库装全了Qt Creator本身的界面也可能花屏、发黑。这种情况下不要跟驱动较劲直接把OpenGL渲染切成软件模式。启动Qt Creator前加export QT_OPENGLsoftware ./qtcreator或者在Tools - Options - Environment里把图形系统改成Software。这个方法在信创项目的老旧机器上实测相当管用。5.3 中文输入法与字体显示问题Qt Creator里能输入英文数字但切不到中文输入法这是很多刚上手的人会遇到的痛点。原因通常是Qt 5.12没有加载到输入法插件。如果用的是fcitx输入法先装桥接库sudo apt install fcitx-frontend-qt5然后在~/.bashrc或/etc/profile里加三行export QT_IM_MODULEfcitx export GTK_IM_MODULEfcitx export XMODIFIERSimfcitx重新登录或source ~/.bashrc后再启动Qt Creator。如果你用的是ibus方案对应装ibus-qt5包环境变量里的fcitx换成ibus。字体方面程序里中文显示成方块多半是中文字体没装执行sudo apt install fonts-noto-cjk装完在系统设置里把默认字体切一下界面和程序里的中文基本就正常了。5.4 ARM架构和虚拟机的特殊注意点aarch64架构的机器上第一原则是不要尝试运行x86_64的.run包系统会直接拒绝执行命令和错误信息都容易让人误以为安装包损坏。ARM平台的Qt安装路径建议优先找厂商或者系统发行方提供的适配包很多芯片原厂都维护了自己的软件仓库直接用apt安装对应版本比下载官方包省事得多。虚拟机上装Qt的时候OpenGL是最大的不稳定因素。常见的现象是Qt Creator启动后窗口闪烁、菜单点不动或者程序运行起来灰屏这通常和虚拟显卡驱动有关。VMware虚拟机建议安装open-vm-tools-desktopQEMU/KVM虚拟机安装qemu-guest-agent同时把Qt渲染模式调成软件模式。还有一个容易被忽略的点虚拟机的系统时间如果不准Qt安装器或者部分证书校验会失败装到一半直接退出。这种问题排查很隐蔽遇到安装过程异常时可以顺手看看date输出对不对。下面是一个常见问题的速查表可以截图保存症状可能原因快速处理安装器无法启动缺少X11运行库安装libxrender1、libxinerama1等qmake -v 版本不对多个Qt版本冲突用 which qmake 定位调整PATHNo suitable kits未添加编译器/qmake按第4节手动配置xcb platform plugin报错缺失xcb相关库安装libxcb-*系列库GL/gl.h找不到缺OpenGL开发头文件安装 libgl1-mesa-dev找不到libGL.so.1缺Mesa运行库安装 libgl1、mesa-utilsQt Creator花屏虚拟机/显卡驱动问题设置 QT_OPENGLsoftware中文输入法无法启用缺fcitx/ibus适配插件安装对应插件并设置环境变量我在实际项目里总结了两个小技巧这里也分享出来。一个是多机部署时把环境变量配置写到/etc/profile.d/qt.sh里而不是只写进某个用户的~/.bashrc这样后面所有用户登录都能直接用不用每台机器重复手工配置。另一个是装完Qt之后一定要先用一个小项目完整跑一遍构建运行流程再交付给别人别只看到qmake -v有输出就以为大功告成。套件配置这种问题当场发现只要几分钟后面到了现场再查可能就要耗费半天。Qt 5.12.12虽然是相对老的版本但在银河麒麟V10这类偏保守的系统上它反而是最稳定的选择。软件的“新”不等于“适合”尤其是项目要长期维护、现场环境复杂的时候一个被反复验证过的版本比什么都重要。