1. 为什么在麒麟V10上装Qt值得单独写一篇麒麟V10银河麒麟桌面操作系统V10在政企、金融、能源等行业的桌面终端上铺得越来越广很多团队原本在Windows或通用Linux发行版上跑得好好的Qt项目一迁移到麒麟V10的x86_64环境就开始出各种幺蛾子。我自己前后在麒麟V10上部署过不下十套Qt开发环境从Qt 5.9一直折腾到Qt 6.x踩过的坑足够写满一个笔记本。这篇文章面向的是需要在麒麟V10 x86_64上搭建Qt开发环境、或者正在被编译报错卡住的开发者。不管你是刚接触Qt的新手还是从Windows转过来的老手我都会把安装路径选择、依赖补齐、编译报错的根因和修复方法讲透。核心关键词就几个麒麟V10、Qt、x86_64、编译问题全文围绕这四个词展开不跑题。先说一个反直觉的结论在麒麟V10上装Qt最省事的方案不是用系统自带的包管理器装而是下载官方离线安装包手动装。原因后面会详细拆这里先给个引子——麒麟V10的软件源里Qt版本往往偏旧而且缺模块是常态你用apt install qt5-default装完大概率会发现serialport、sqlite这些模块根本找不到然后就是无尽的Unknown module(s) in Qt: serialport报错。2. 安装前的环境摸底与方案选型2.1 先确认你的系统到底是不是x86_64这一步听起来废话但真有人栽过。麒麟V10有飞腾ARM64、鲲鹏ARM64、兆芯/海光x86_64等多个版本镜像拿错了后面全白搭。执行uname -m输出x86_64才是本文讨论的环境。如果输出aarch64那是ARM64架构安装包和依赖都不一样别混用。顺便把系统版本也确认一下cat /etc/kylin-release cat /etc/os-release麒麟V10的SP1、SP2、SP3之间包依赖有差异记下你的具体版本号后面排查问题时有用。2.2 三种安装方式的取舍在麒麟V10上装Qt主流就三条路我把它们的优缺点列成表格你对着选安装方式优点缺点适用场景系统包管理器apt/yum命令简单依赖自动处理版本旧、模块缺失严重、无法多版本共存只跑简单Demo不推荐生产官方在线安装器版本可选、模块可勾选需要稳定网络、下载量大网络条件好的开发机官方离线安装包不依赖网络、可批量部署、版本可控安装包体积大1-3GB内网环境、生产部署、多机统一我个人的选择是离线安装包。原因很直接麒麟V10很多部署环境是内网在线安装器根本连不上而且离线包可以放在U盘或内网文件服务器上给整个团队统一版本避免你装5.15.2我装5.12.9导致的编译差异。2.3 离线安装包从哪来Qt官方离线包在Qt官网的下载归档区可以找到文件名类似qt-opensource-linux-x64-5.15.2.run。注意选linux-x64后缀的这就是x86_64版本。5.15.2是LTS版本社区用得最多兼容性也最稳我建议优先选它。如果你要上Qt 6选6.2或6.5的LTS版本。下载完先校验一下文件完整性chmod x qt-opensource-linux-x64-5.15.2.run ls -lh qt-opensource-linux-x64-5.15.2.run文件大小对得上5.15.2大概1.3GB左右再往下走。3. 离线安装包在麒麟V10上的完整落地过程3.1 补齐安装器运行所需的底层依赖麒麟V10默认安装的桌面环境依赖比较精简直接跑.run安装器经常报缺库。先把这些装上sudo apt update sudo apt install -y libgl1-mesa-dev libglu1-mesa-dev libx11-dev \ libxext-dev libxrender-dev libxcb1-dev libx11-xcb-dev \ libxcb-glx0-dev libxcb-keysyms1-dev libxcb-image0-dev \ libxcb-shm0-dev libxcb-icccm4-dev libxcb-sync-dev \ libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev \ libxcb-render-util0-dev libxkbcommon-dev libxkbcommon-x11-dev \ libfontconfig1-dev libfreetype6-dev这一长串不是凑数每一个都对应Qt GUI模块编译或运行时的真实依赖。比如libxcb-xfixes0-dev缺了Qt Creator启动时可能直接闪退libxkbcommon-x11-dev缺了键盘输入会异常。提示如果apt update报Cannot find a valid baseurl for repo说明你的软件源配置有问题先检查/etc/apt/sources.list里的源地址是否可达或者换成内网镜像源。3.2 安装器的图形化安装与组件勾选依赖补齐后用普通用户不要用root运行安装器./qt-opensource-linux-x64-5.15.2.run安装器会走图形界面。几个关键选择安装路径默认是~/Qt我建议保持默认。装到/opt下虽然看起来正规但后续权限问题会让你头疼尤其是Qt Creator创建项目时写文件。组件勾选至少勾选Desktop gcc 64-bit这是x86_64的编译套件、Qt Creator、Sources方便调试时看源码。如果你要做数据库开发把Qt Debug Information Files也勾上。不要勾Android/iOS套件除非你明确要做移动端否则这些套件会多占好几个GB还容易在编译时引入无关的路径问题。安装过程大概10-20分钟取决于磁盘速度。3.3 环境变量的正确配置姿势安装完不配环境变量命令行里敲qmake会提示找不到命令。编辑~/.bashrcexport QTDIR$HOME/Qt/5.15.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins然后source ~/.bashrc验证qmake -v应该输出QMake version 3.1和Using Qt version 5.15.2。如果输出的是系统自带的旧版本说明PATH顺序不对把$QTDIR/bin往前提。注意LD_LIBRARY_PATH这个变量是把双刃剑。它能让你的程序找到Qt库但如果系统里同时存在多个Qt版本它可能导致程序加载到错误的库。生产环境我更推荐用rpath方式在编译时写死库路径而不是依赖LD_LIBRARY_PATH。4. 那些让人抓狂的编译报错逐个击破4.1 Unknown module(s) in Qt: serialport 的根因与修复这是麒麟V10上最高频的报错没有之一。你在.pro文件里写了QT serialport一编译就报Project ERROR: Unknown module(s) in Qt: serialport根因有两个层面。第一层你用的Qt安装包里根本没勾选Qt Serial Port模块。第二层即使勾选了麒麟V10的pkg-config路径没配好qmake找不到模块的.pri文件。先确认模块是否存在ls $QTDIR/lib/cmake/Qt5SerialPort/ ls $QTDIR/include/QtSerialPort/如果目录不存在说明安装时没勾。重新运行安装器在组件列表里找到Qt Serial Port补勾。如果目录存在但还报错检查$QTDIR/mkspecs/modules/下有没有qt_lib_serialport.pri文件没有的话说明安装不完整重装。修复后清理项目重新qmakemake distclean qmake make4.2 编译时链接不到 libGL 或 libGLU报错长这样cannot find -lGL cannot find -lGLU这是OpenGL开发库没装。麒麟V10默认可能只装了运行时库没装开发库。补上sudo apt install -y libgl1-mesa-dev libglu1-mesa-dev如果装完还报错用locate libGL.so确认库文件位置然后手动在.pro里指定LIBS -L/usr/lib/x86_64-linux-gnu -lGL -lGLU4.3 qmake 找不到编译器或编译器版本不匹配麒麟V10自带的GCC版本可能是7.x或9.x而你的Qt安装包可能是用更高版本GCC编译的。报错通常是error: #error This file requires compiler and library support for the ISO C 2011 standard或者链接时出现undefined reference to std::__cxx11::...。这是ABI不兼容的典型症状。解决方案是统一编译器版本。先看系统GCCgcc --version g --version如果系统GCC太旧装个新的sudo apt install -y gcc-9 g-9 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-9 90然后在Qt Creator的Kits设置里把编译器手动指向/usr/bin/g-9重新构建。4.4 中文输入法与Qt程序的光标错位这个不算编译错误但属于麒麟V10上Qt开发的高频体验问题。现象是在Qt程序里用中文输入法打字候选框位置和光标对不上或者输入法根本不激活。根因是Qt的输入法插件libcomposeplatforminputcontextplugin.so或libibusplatforminputcontextplugin.so没被正确加载。检查ls $QTDIR/plugins/platforminputcontexts/如果缺ibus插件装依赖后重新编译该插件或者直接把系统里的输入法插件软链过来ln -s /usr/lib/x86_64-linux-gnu/qt5/plugins/platforminputcontexts/libibusplatforminputcontextplugin.so \ $QTDIR/plugins/platforminputcontexts/然后在程序启动时设置环境变量export QT_IM_MODULEibus4.5 打包发布后目标机器运行报缺库你在开发机上跑得好好的程序拷到另一台麒麟V10上就报error while loading shared libraries: libQt5Core.so.5: cannot open shared object file这是因为目标机器没装Qt或者Qt版本不一致。解决办法是用linuxdeployqt打包把依赖库一起带上./linuxdeployqt-continuous-x86_64.AppImage your_app -appimage如果linuxdeployqt在麒麟V10上跑不起来它本身也是Qt程序可以先在开发机上用ldd手动收集依赖ldd your_app | grep / | awk {print $3} | xargs -I {} cp {} ./libs/然后把libs目录和可执行文件一起打包目标机器上用启动脚本设置LD_LIBRARY_PATH指向该目录。5. 麒麟V10特有的系统级坑点5.1 安全机制对Qt程序的影响麒麟V10默认开启了较严格的安全策略某些情况下会拦截Qt程序创建共享内存或访问特定设备。典型表现是程序启动后卡死或者串口/摄像头打不开。排查方法是看系统日志sudo journalctl -xe | grep -i denied如果看到avc: denied之类的记录说明是安全策略拦截。临时验证可以调整策略模式但生产环境建议针对你的程序添加白名单规则而不是直接关闭安全机制。5.2 文件路径中的中文与空格麒麟V10的桌面环境默认用中文目录名如桌面文档Qt程序如果硬编码了英文路径读写文件就会失败。更隐蔽的是某些第三方库对含中文的路径处理有bug导致程序崩溃。我的做法是在程序里统一用QStandardPaths获取标准路径不要自己拼字符串QString dataPath QStandardPaths::writableLocation(QStandardPaths::AppDataLocation);这样无论系统语言是什么路径都能正确解析。5.3 系统自带Qt与手动安装Qt的冲突麒麟V10可能预装了Qt库给系统自带应用用的。你手动装了Qt 5.15.2后如果环境变量没配好编译时可能链接到系统自带的旧版本运行时又加载了你的新版本导致各种诡异崩溃。诊断方法which qmake qmake -query QT_VERSION ldd your_app | grep Qt5Core确保which qmake指向你手动安装的路径ldd输出的Qt库路径也是你的安装路径。不一致就回去检查PATH和LD_LIBRARY_PATH的顺序。6. 一套可复用的环境验证清单装完环境别急着写业务代码先跑一遍验证把问题扼杀在摇篮里。我整理了一份清单每次新机器部署都过一遍验证项命令预期结果架构确认uname -mx86_64qmake版本qmake -v指向手动安装的Qt版本编译器g --version与Qt编译版本匹配GUI模块编译一个空QWidget程序正常弹出窗口串口模块.pro加QT serialport编译通过数据库模块.pro加QT sql编译通过中文输入在QLineEdit里输入中文候选框位置正确打包运行拷贝到另一台机器运行无缺库报错这套清单跑通基本可以确认环境没问题了。7. 几个能省下大量时间的实操心得第一个心得把离线安装包和依赖清单一起归档。我见过太多团队某台机器环境坏了要重装结果发现当初的安装包找不到了依赖清单也没记只能从头再踩一遍坑。建议建一个qt-env-setup目录里面放安装包、apt依赖列表用dpkg --get-selections导出、环境变量脚本新机器一键部署。第二个心得Qt Creator的Kits配置要导出备份。Qt Creator的编译器、调试器、Qt版本配置都保存在~/.config/QtProject/下换机器时直接拷过去省得重新配。尤其是手动指定编译器路径的情况重配一次很烦。第三个心得编译报错先看完整输出别只看最后一行。Qt的编译错误经常是连锁的最后一行报的错往往是前面某个依赖缺失导致的。用make 21 | tee build.log把完整日志存下来从头往下找第一个error那才是根因。第四个心得善用qmake -query排查路径问题。这个命令会输出Qt的所有关键路径头文件、库、插件、mkspecs当你怀疑qmake找错地方时跑一下它比翻文档快得多。第五个心得内网环境提前准备好所有.deb包。麒麟V10的内网机器往往连不上外网源apt install会失败。在能联网的机器上用apt-get download把依赖包下下来拷到内网用dpkg -i装。注意依赖顺序缺依赖时dpkg -i会报错用apt-get install -f补。8. 关于版本选择的一点个人建议Qt 5.15.2是我在麒麟V10 x86_64上用得最顺的版本LTS支持到2025年社区资料也最全。Qt 6.x虽然新但在麒麟V10上遇到的兼容问题明显更多尤其是图形栈相关的部分除非项目有明确要求否则不建议在麒麟V10上贸然上Qt 6。如果你确实需要Qt 6建议选6.2或6.5的LTS版本并且提前在测试机上把GUI、网络、数据库这几个核心模块都验证一遍。我遇到过Qt 6.5在麒麟V10上OpenGL上下文创建失败的情况最后是靠切换渲染后端QT_QUICK_BACKENDsoftware绕过去的但性能会打折扣。版本这东西稳定比新更重要。生产环境上跑的东西能不动就不动这是我踩了无数次坑之后最深的体会。