1. 麒麟V10下Qt开发环境搭建的整体思路在国产操作系统上做Qt开发这几年我从一开始的“到处踩坑”到后来逐渐摸出一套相对稳定的流程。麒麟V10包括银河麒麟桌面版和服务器版基于Linux内核x86_64架构下的软件生态相对成熟但和主流的Ubuntu、CentOS相比软件源、依赖包命名、系统库版本都有不少差异。Qt作为跨平台C框架本身对Linux支持很好问题往往不出在Qt本身而是出在系统环境、依赖库、编译器版本这些“外围”环节上。这篇文章我打算把麒麟V10 x86_64下Qt安装的完整路径讲透包括在线安装、离线安装两种方式的选择逻辑以及编译过程中最常遇到的几类问题——比如unknown module(s) in qt: serialport、cannot find a valid baseurl for repo、passwd模块未知这些报错的根因和解决办法。适合刚接触麒麟V10的Qt开发者、需要把原有项目迁移到国产系统的团队以及负责搭建开发环境的管理员参考。先说一个核心判断在麒麟V10上装Qt最稳的路子不是追最新版而是选一个和系统glibc版本匹配的LTS版本。Qt 5.15.2是目前在麒麟V10上验证最充分的版本之一Qt 6系列虽然新但对系统库的要求更高在部分麒麟V10的SP版本上会遇到兼容性问题。下面我按“选型—安装—配置—编译—排错”的顺序展开。1.1 为什么版本选型是第一步很多人装Qt的习惯是直接去官网下最新版这在Ubuntu上通常没问题但在麒麟V10上要谨慎。麒麟V10的桌面版和服务器版底层依赖的glibc版本不同SP1、SP2、SP3之间也有差异。Qt的预编译二进制包对glibc有最低版本要求如果系统glibc低于Qt的要求运行时会直接报GLIBC_2.xx not found。我的经验是先执行ldd --version看系统glibc版本再对照Qt官方文档里各版本的最低要求。Qt 5.15.2一般要求glibc 2.17以上麒麟V10基本都满足Qt 6.2以上可能要求2.28甚至更高部分老SP版本就不够了。如果glibc不够又不想升级系统那就只能源码编译Qt但源码编译在麒麟V10上耗时很长依赖也多不是首选。另一个考虑是编译器。麒麟V10自带的GCC版本通常是7.x或8.xQt 5.15.2对GCC 7/8支持良好。如果系统GCC太老比如4.8那连Qt 5.15都编不了需要先升级编译器或使用devtoolset。1.2 在线安装与离线安装的取舍在线安装走的是Qt官方安装器需要联网下载组件优点是灵活、能按需选模块缺点是麒麟V10上安装器本身可能因为缺少某些图形库而跑不起来而且下载速度受网络影响大。离线安装包是官方提供的完整二进制包下载后解压即用不依赖网络。在麒麟V10这种可能处于内网环境的场景下离线包是更实际的选择。Qt 5.14、5.15.2都有离线包下载地址在Qt官方归档站。注意离线包分qt-opensource-linux-x64-5.15.2.run这种自解压格式和.tar.xz压缩包两种前者带安装向导后者解压后手动配置。提示如果目标机器完全无外网建议在有网的机器上下好离线包用U盘或内网传输过去。离线包体积在1GB到2GB之间提前确认存储空间。1.3 系统依赖的前置准备不管哪种安装方式麒麟V10上都需要先补齐一批基础依赖。这些依赖包括libgl1-mesa-dev、libglu1-mesa-dev、libx11-dev、libxext-dev、libxrender-dev、libfontconfig1-dev、libfreetype6-dev、libssl-dev、libsqlite3-dev等。缺了这些轻则Qt Creator界面显示异常重则编译时报找不到头文件。麒麟V10的包管理用的是apt桌面版或yum/dnf服务器版具体看版本。桌面版一般有apt源服务器版可能是yum。如果遇到cannot find a valid baseurl for repo: base/7/x86_64这类报错说明yum源配置有问题需要检查/etc/yum.repos.d/下的repo文件把baseurl指向可用的镜像地址。2. 麒麟V10 x86_64下Qt安装的完整实操这一部分我把在线和离线两条路都走一遍重点讲离线安装因为这是内网环境最常用的方式。每一步我都标注了操作意图和可能踩的坑。2.1 离线安装包的选择与校验先从Qt官方归档站下载对应版本的离线包。以Qt 5.15.2为例文件名类似qt-opensource-linux-x64-5.15.2.run。下载完成后务必校验文件完整性用sha256sum对比官方提供的哈希值。我遇到过下载中断导致安装到一半报错的情况校验能提前发现问题。sha256sum qt-opensource-linux-x64-5.15.2.run # 对比官方公布的哈希值校验通过后给文件加执行权限chmod x qt-opensource-linux-x64-5.15.2.run2.2 安装向导的运行与组件选择直接运行安装器./qt-opensource-linux-x64-5.15.2.run如果提示缺少图形库导致界面起不来可以先装依赖sudo apt install libgl1-mesa-dev libglu1-mesa-dev libx11-dev libxext-dev libxrender-dev libfontconfig1-dev libfreetype6-dev安装向导里会让你登录Qt账号离线安装可以跳过登录部分版本需要断网才能跳过。组件选择是关键Qt Creator必选Qt 5.15.2的Desktop gcc 64-bit必选Source组件按需选。如果你要做串口开发Qt Serial Port模块要勾上做数据库开发Qt SQL模块要勾上。这些模块如果安装时没选后面编译报unknown module(s) in qt: serialport就得重新跑安装器补装。安装路径建议放在/opt/Qt5.15.2或用户目录下避免路径里有中文或空格。安装完成后Qt Creator在Tools/QtCreator/bin/qtcreator。2.3 环境变量的配置安装完不配环境变量命令行编译会找不到qmake。编辑~/.bashrc或/etc/profile加入export QTDIR/opt/Qt5.15.2/5.15.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/pluginsQTDIR指向具体的gcc_64目录不是Qt安装根目录这点容易搞错。配完执行source ~/.bashrc然后qmake -v验证能输出版本信息就对了。注意LD_LIBRARY_PATH里加Qt的lib目录能解决运行时找不到libQt5Core.so.5的问题。但不要把这个变量设得太宽泛否则可能影响系统其他程序。2.4 在线安装的补充说明如果走在线安装先下载qt-unified-linux-x64-online.run同样加执行权限后运行。在线安装器对网络要求高麒麟V10上如果遇到SSL证书问题可能需要更新ca-certificates包。在线安装的好处是能自动处理部分依赖但组件下载慢建议在网络条件好的时候操作。2.5 验证安装是否成功装完后做三件事验证一是qmake -v看版本二是打开Qt Creator新建一个Widgets Application能正常创建就说明基本环境OK三是编译一个最简单的Hello World确认编译链路通畅。mkdir hello cd hello # 用Qt Creator创建项目后 qmake hello.pro make ./hello如果这一步就报错那问题在环境配置先别急着写业务代码。3. 编译过程中的高频问题与根因分析Qt在麒麟V10上编译报错大部分集中在模块缺失、依赖库找不到、编译器不兼容这三类。下面挑几个最典型的展开。3.1 unknown module(s) in qt: serialport 的解决这个报错的意思是你的.pro文件里写了QT serialport但当前Qt安装里没有Serial Port模块。根因有两种一是安装时没勾选该模块二是勾选了但qmake没找到对应的.pri文件。先确认模块是否存在ls $QTDIR/lib/cmake/Qt5SerialPort ls $QTDIR/mkspecs/modules/qt_lib_serialport.pri如果目录不存在说明模块没装重新跑安装器补装。如果目录存在但qmake还是报错检查QTDIR环境变量是否指向了正确的Qt版本。有时候系统里装了多个Qtqmake用的是另一个版本的自然找不到模块。还有一种情况是模块装了但版本不匹配比如用Qt 5.15的qmake去编译依赖Qt 5.12模块的项目。这种要统一版本。3.2 cannot find a valid baseurl for repo 的处理这个报错出现在yum/dnf安装依赖时说明repo配置里的baseurl不可达。麒麟V10服务器版默认的yum源可能指向内网地址或已失效的地址。解决方法是编辑/etc/yum.repos.d/下的repo文件把baseurl改成可用的镜像地址。# 查看当前repo配置 cat /etc/yum.repos.d/*.repo # 备份后修改baseurl sudo cp /etc/yum.repos.d/xxx.repo /etc/yum.repos.d/xxx.repo.bak sudo vi /etc/yum.repos.d/xxx.repo改完后执行sudo yum clean all sudo yum makecache刷新缓存。如果内网有自建的镜像源优先用内网地址速度稳定。3.3 passwd模块未知的排查passwd模块未知这个报错通常和PAM可插拔认证模块配置有关出现在系统层面而非Qt层面。如果你在麒麟V10上做用户认证相关的开发或者系统更新后出现这个提示检查/etc/pam.d/下的配置文件确认pam_unix.so等模块路径正确。这个问题的根因往往是系统升级后PAM模块版本和配置文件不匹配需要对照系统版本文档恢复默认配置。3.4 编译时找不到头文件或库这类报错形如fatal error: XXXX.h: No such file or directory或cannot find -lXXXX。根因是依赖库的开发包没装。麒麟V10上很多库的运行时包默认装了但-dev或-devel包没装。比如用到OpenSSL需要libssl-dev用到SQLite需要libsqlite3-dev。排查方法是先用dpkg -l | grep xxx桌面版或rpm -qa | grep xxx服务器版看包是否安装再用find / -name xxxx.h看头文件在不在。缺什么补什么。3.5 常见问题速查表报错信息根因解决方向unknown module(s) in qt: serialport模块未安装或qmake路径错误补装模块检查QTDIRcannot find a valid baseurl for repoyum源地址失效修改repo文件baseurlpasswd模块未知PAM配置与系统版本不匹配恢复PAM默认配置GLIBC_2.xx not found系统glibc版本低于Qt要求换低版本Qt或升级系统cannot find -lXXXX缺少开发包安装对应的-dev/-devel包qmake: command not found环境变量未配置配置PATH和QTDIR4. 实操心得与避坑经验这部分是我这些年攒下来的“非文档级”经验很多是踩了坑才记住的。4.1 环境隔离的重要性麒麟V10上可能同时存在系统自带的Qt和手动安装的Qt。如果不做环境隔离编译时很容易用到错误的qmake。我的做法是在项目里用.qmake.conf或直接在构建脚本里写死qmake的绝对路径避免依赖环境变量。另外可以用qtchooser工具管理多个Qt版本通过qtchooser -list-versions查看qtchooser -set-default切换。4.2 编译参数的选择Qt项目编译时-j参数控制并行编译的核数。麒麟V10如果是虚拟机核数少-j4就够了物理机可以-j$(nproc)。但并行编译遇到内存不足会OOM这时候要降-j值。我遇到过-j8编译大项目时内存爆掉改成-j2就稳了。4.3 动态库路径的运行时问题编译通过不代表运行通过。Qt程序运行时找不到动态库是常见问题。除了设LD_LIBRARY_PATH还可以在/etc/ld.so.conf.d/下加一个conf文件写入Qt的lib路径然后sudo ldconfig。这种方式比环境变量更持久对所有用户生效。echo /opt/Qt5.15.2/5.15.2/gcc_64/lib | sudo tee /etc/ld.so.conf.d/qt.conf sudo ldconfig4.4 插件加载失败的排查Qt程序运行时报This application failed to start because no Qt platform plugin could be initialized说明平台插件没找到。检查QT_PLUGIN_PATH是否指向$QTDIR/plugins以及$QTDIR/plugins/platforms/libqxcb.so是否存在。如果存在还报错用ldd libqxcb.so看它的依赖是否齐全缺什么补什么。4.5 离线部署时的库打包把Qt程序部署到没有Qt环境的麒麟V10机器上需要把依赖的Qt库一起打包。可以用linuxdeployqt工具自动收集依赖或者手动用ldd列出所有依赖库拷贝到目标机器的对应目录。注意目标机器的glibc版本不能低于编译机器否则运行不了。4.6 关于Qt 6的补充如果项目允许用Qt 6麒麟V10 SP3以上版本对Qt 6.2 LTS的支持已经比较好了。Qt 6的CMake构建系统比qmake更现代但迁移老项目有成本。我的建议是新项目可以直接上Qt 6老项目如果qmake跑得好不必为了新而新。5. 从安装到跑通第一个项目的完整记录最后我把一个最小可运行项目的完整流程走一遍作为前面内容的串联。5.1 创建项目打开Qt CreatorFile - New File or Project - Application (Qt) - Qt Widgets Application项目名用HelloKylin构建系统选qmake基类选QWidget。5.2 修改pro文件在HelloKylin.pro里按需加模块比如QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET HelloKylin TEMPLATE app SOURCES main.cpp widget.cpp HEADERS widget.h5.3 编译与运行在Qt Creator里点构建或者命令行cd HelloKylin qmake HelloKylin.pro make -j4 ./HelloKylin能弹出一个空窗口就说明整条链路通了。如果弹窗报平台插件错误回到4.4节排查。5.4 打包发布用linuxdeployqt打包linuxdeployqt HelloKylin -appimage生成的AppImage可以在其他麒麟V10机器上直接运行前提是glibc版本兼容。这套流程我在麒麟V10桌面版SP1和服务器版SP2上都验证过Qt 5.15.2的兼容性最好。如果遇到本文没覆盖的报错优先看编译输出的第一行错误那通常是根因后面的报错往往是连锁反应。把第一行错误解决了后面一大串可能自动消失。