麒麟V10 x86_64下Qt开发环境搭建与编译问题解决指南

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.x，Qt 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.run

2.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/plugins

QTDIR指向具体的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版本。有时候系统里装了多个Qt，qmake用的是另一个版本的，自然找不到模块。

还有一种情况是模块装了但版本不匹配，比如用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 常见问题速查表

4. 实操心得与避坑经验

这部分是我这些年攒下来的“非文档级”经验，很多是踩了坑才记住的。

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 ldconfig

4.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 Creator，File -> 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.h

5.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的兼容性最好。如果遇到本文没覆盖的报错，优先看编译输出的第一行错误，那通常是根因，后面的报错往往是连锁反应。把第一行错误解决了，后面一大串可能自动消失。