国产Linux桌面这几年在工控、轨道交通、电力这些行业铺得很快统信UOS是出镜率相当高的一个。很多做上位机、HMI、仪器仪表界面的团队原来在Windows上用Qt Creator写得好好的一转到统信UOS上就发现事情没那么顺手软件源里的Qt版本偏老、装完Qt Creator打不开、xcb插件报错、中文输入法在编辑器里不弹候选框。这些问题单看都不难堆在一起就足够耗掉一个礼拜。这篇就把我在统信UOS上搭Qt开发环境的完整过程摊开讲一遍从系统准备、依赖补齐、三条安装路线的取舍到Qt Creator的Kit配置、第一个工程的跑通、交叉编译到ARM板的补充最后整理一份常见故障速查表。内容偏实操适合两类人一是第一次在国产Linux桌面上做Qt开发的工程师二是已经在上面装过但总被各种报错卡住的朋友。我尽量把每个选择背后的理由也讲清楚省得你照着敲完命令还是一头雾水。1. 先想清楚统信UOS做Qt开发方案怎么选1.1 统信UOS的底子和Qt的匹配度统信UOS专业版走的是Debian系的包管理apt、dpkg、deb包这一套是通的这一点很关键因为它意味着绝大多数Debian/Ubuntu上的Qt安装经验可以直接迁移过来而不需要重新学一套。UOS 20系列的桌面环境是自研的DDE窗口管理器、输入法框架、字体渲染链路都做过定制Qt的默认平台插件是xcb走的是X11协议栈兼容性总体没有大问题但在几个地方容易翻车一个是系统预装的Qt运行库和你要装的开发版Qt可能版本打架另一个是DDE对窗口装饰、托盘图标、高分屏的处理有自己的逻辑Qt程序跑起来界面可能跟你在Windows上看到的不完全一样。Qt本身对Linux的支持是相当成熟的从Qt 5.9 LTS到5.15 LTS再到Qt 6.x源码里对X11、Wayland、EGLFS都有完整实现。在UOS上做开发你大概率会碰到两种落地形态一种是纯桌面应用跑在UOS自带的X11会话上按普通桌面程序的路子走另一种是嵌入式HMI本机开发、交叉编译后丢到ARM板子上跑这时候本机环境其实只是个编译主机对界面效果的要求没那么高重点反而是交叉工具链和sysroot的配置。我个人的判断是如果你是第一次在UOS上搭Qt先把心态放平不要指望一条命令搞定也不要急着上最新的Qt 6。把系统依赖、图形库、字体、输入法这四个基础盘理清楚后面的安装反而快。1.2 三条安装路线什么时候用哪条在统信UOS上装Qt能走的路其实就三条各有各的适用场景我按省事程度和可控程度做个对照你可以直接对号入座。路线具体做法优点缺点适合谁A系统源安装apt install qtcreator qtbase5-dev等依赖自动解决和系统库版本一致版本偏旧组件不全只想快速验证、做小工具B官方离线安装包下载.run安装包图形化勾选组件版本可选、组件完整、可多版本共存需要手动补依赖包体大正经做项目的人推荐C源码编译configuremakemake install完全可控能裁剪、能定制耗时长依赖坑多有特殊裁剪需求、要做交叉编译我个人在项目里最常用的是路线B。理由很实在官方离线包能一口气把Qt Creator、多个Qt版本、Qt Charts、Qt SerialPort、Qt Virtual Keyboard这些模块都装齐装完就是一个独立的目录跟你系统自带的Qt互不干扰哪天搞坏了直接删目录重来不用去动系统的包状态。路线A适合临时用一下比如你只是想跑个demo看看串口通不通装个 qtbase5-dev 加 qtcreator 就够了。路线C我一般只在两种情况下用一是目标板子的Qt需要裁剪掉WebEngine这种巨型模块二是官方包里的某个组件和我的交叉工具链不匹配。1.3 Qt版本怎么定别一上来就追新版本这块我踩过坑值得单独说。Qt 5.15是最后一个5.x的LTS生态最成熟社区资料最多第三方库兼容性最好Qt 6.x 在图形栈上换成了RHI对高分屏、Vulkan、Metal支持更好但很多老项目的.pro文件直接迁过去会报一堆废弃警告第三方库比如某些工业通信SDK还在用Qt 5的API。统信UOS系统源里带的通常是Qt 5.11到5.15之间的某个版本具体看你装的UOS版本。如果你做的是工业上位机依赖Modbus、串口、CAN、OPC UA这类库我建议锁死Qt 5.15.x别折腾。如果是从零开始的新项目又不需要太多历史包袱可以考虑Qt 6.5 LTS但一定要确认你用的所有第三方库都有Qt 6的适配版本否则编译期就会发现一堆no member named。还有一个容易忽略的点Qt Creator的版本和Qt库的版本是两码事。Qt Creator 4.11、4.15、10、12这些是IDE自身的版本它可以管理从Qt 4到Qt 6的所有Kit。你完全可以装一个较新的Qt Creator然后用它去编译Qt 5.15的项目这是官方支持的用法不用强迫自己版本对齐。2. 装之前必须做的事系统准备与依赖补齐2.1 确认系统版本、架构和软件源状态动手之前先摸清家底这一步花两分钟能省掉后面半小时的困惑。打开终端依次执行下面几条命令把结果记下来。cat /etc/os-release # 看系统版本UOS 20 还是其他 uname -m # 看架构x86_64 还是 aarch64/loongarch64 dpkg --print-architecture # 确认包架构 free -h # 看内存源码编译很吃内存 df -h /opt # 看 /opt 剩余空间离线包通常要 5G 以上架构这条特别重要。统信UOS覆盖了x86_64、ARM64、LoongArch、SW64等多个平台Qt官方的离线安装包只提供x86_64版本如果你手上是ARM64的机器比如某些国产笔记本或者飞腾、鲲鹏平台的整机路线B直接就走不通只能走系统源或者源码编译。我在一台飞腾平台的机器上折腾过最后是用系统源装的Qt 5.15加自己编译的Qt Creator过程比x86平台麻烦不少。软件源这边UOS的源配置一般在/etc/apt/sources.list或者/etc/apt/sources.list.d/下面。先执行sudo apt update看能不能正常拉到索引。如果报无法连接或者速度极慢检查一下是不是源地址被改过、网络是否走了内网代理。有些企业内网环境会自建镜像源这种情况下让运维给一份正确的源地址别自己去网上抄。2.2 一次性装齐编译工具链与图形依赖Qt在Linux上跑表面上是缺这个库缺那个库实际上就是这几个大类的依赖编译工具链、OpenGL/GLES相关、X11的xcb系列、字体渲染、输入法框架、音频和多媒体。我习惯一次性装齐避免装到一半报错再回头补。sudo apt update sudo apt install -y \ build-essential cmake ninja-build pkg-config git \ gdb valgrind strace \ libgl1-mesa-dev libglu1-mesa-dev libegl1-mesa-dev \ libx11-dev libxext-dev libxrender-dev libxi-dev \ libxkbcommon-dev libxkbcommon-x11-dev \ libxcb1-dev libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \ libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ libxcb-shape0 libxcb-shm0 libxcb-sync1 libxcb-xfixes0 \ libfontconfig1 libfreetype6 libdbus-1-dev \ libssl-dev libasound2-dev libpulse-dev \ libnss3 libxcursor1 libxcomposite1 libxdamage1 libxtst6 \ fonts-noto-cjk fonts-wqy-microhei这里每一组都有明确的用途我挑几个重点解释。libxcb-xinerama0是很多人卡住的那个库——Qt程序启动时报 Could not load the Qt platform plugin xcb八成就是缺它或者它旁边的兄弟库。libxkbcommon-x11-dev关系到键盘布局和输入法缺了会出现输入法候选框不弹出、快捷键失灵。fonts-noto-cjk和fonts-wqy-microhei是中文显示的基础缺字体的话界面上的中文会变成一排方块这个现象在刚装完的干净系统上非常常见。libasound2-dev和libpulse-dev是给Qt Multimedia用的如果你项目里有音视频播放这两个必须装否则QT multimedia一编译就报错。提示装依赖这一步不管走哪条安装路线都要做。很多人以为用官方离线包就不需要系统依赖结果装完Qt Creator双击没反应回头查半天才发现是xcb库缺失。2.3 开发者模式、sudo权限和磁盘空间统信UOS默认给普通用户的权限是收紧的尤其是较早的版本root密码是不公开的需要用户自己在控制中心里开启开发者模式。开启路径大致是控制中心 → 通用 → 开发者模式 → 进入开发者模式按提示操作后重启。开启之后你的账号就有了sudo权限前面那些apt命令才能执行。这一步听起来像是废话但我见过不止一个人卡在这里终端里敲sudo apt update提示密码不对然后开始怀疑是不是装系统时设错了密码其实根本没开开发者模式。另外要注意部分企业版UOS的开发者模式需要走离线激活得先申请机器码、拿到离线证书文件再导入这个过程可能需要一两天建议提前办。磁盘空间也是提前要看的。官方离线安装包解开之后如果勾选了Qt 5.15的全部组件加Qt 6轻松超过15GB。源码编译的话Qt Base单独编译完大概3到5GB如果把Qt WebEngine算进去中间产物能到20GB以上。所以/opt或者你准备放Qt的目录最好留出30GB以上的空间。我一般会把Qt装在/opt/Qt下面源码编译的中间目录放在家目录两个分开方便管理和清理。2.4 中文输入法的坑提前处理输入法这事看起来很边缘但对日常写代码影响巨大。UOS自带的是fcitx框架拼音输入法默认是有的。Qt程序要通过fcitx输入中文依赖的是Qt的platforminputcontext插件这个插件在系统源装的Qt里一般会自带用官方离线包装的Qt则需要手动确认。装完之后在终端里验证echo $QT_IM_MODULE # 期望输出 fcitx echo $XMODIFIERS # 期望输出 imfcitx如果这两个变量是空的可以在~/.profile或者~/.bashrc里补上export QT_IM_MODULEfcitx export XMODIFIERSimfcitx export GTK_IM_MODULEfcitx改完记得重新登录一次会话别只重开终端环境变量对图形程序生效需要重新走一遍登录流程。验证方法是打开Qt Creator在代码编辑器里切到中文输入法打几个字候选框能正常跟随光标就没问题了。注意如果你用的是Qt自带的那种极简桌面会话或者在某些远程桌面环境下输入法的行为会不太一样。远程场景下建议先确认本地输入法的按键事件有没有正确透传过去不然你会以为是Qt的问题。3. 三条路线实操从apt到离线包再到源码编译3.1 路线Aapt仓库直接装十分钟能跑这条路最快适合验证环境和跑小demo。系统源里的相关包名大致是这些sudo apt install -y qtcreator qtbase5-dev qtchooser qt5-qmake \ qtbase5-dev-tools libqt5serialport5-dev libqt5charts5-dev \ qttools5-dev-tools qtdeclarative5-dev装完直接命令行敲qtcreator就能启动。启动之后会自动扫描系统里的Qt版本一般不需要额外配置Kit新建工程就能编译。这条路的短板有两个一是版本UOS源里的Qt大概率是5.11到5.15之间的某个版本具体看源二是组件某些模块比如Qt Virtual Keyboard、Qt WebEngine在源里不一定有对应的dev包缺了只能自己补。有个细节值得说Debian 10以后的版本把qt5-default这个包给去掉了如果你在教程里看到apt install qt5-default在UOS上执行可能会报没有可安装候选。这时候不要慌装qtbase5-dev qtchooser qt5-qmake这套组合效果是一样的。qtchooser是用来在多个Qt版本之间切换的如果你后面又装了官方离线包它可能带来一些路径上的混乱我倾向于在走路线B之前把它卸掉避免qmake -v输出了错误版本。3.2 路线B官方离线安装包最推荐的干净方案这是我最推荐的路线也是用得最久的。流程分几步下载安装包、赋执行权限、运行图形化安装、补依赖、配置环境变量。下载地址在Qt官方的归档站点路径结构是archive/qt/5.15/5.15.2/文件名类似qt-opensource-linux-x64-5.15.2.run。企业内网不方便直连的话可以在一台能上网的机器上下好用U盘或者内网共享拷过去安装包大概1.5GB左右。下载完之后chmod x qt-opensource-linux-x64-5.15.2.run sudo ./qt-opensource-linux-x64-5.15.2.run之所以加sudo是为了让它能默认装到/opt这类系统目录。如果你打算装到家目录下就不需要sudo但要注意路径里不要有中文和空格。安装向导启动后要登录Qt账号没有账号的话可以注册一个也可以选择跳过部分版本支持。组件选择页面是关键我一般这么勾Qt 5.15.2 下的 Desktop gcc 64-bit这是核心Qt Charts、Qt Data Visualization、Qt Virtual Keyboard按项目需要Qt Network Authorization、Qt WebEngine看情况WebEngine体积很大不用就别勾Developer and Designer Tools 下的 Qt Creator、Qt Designer、Qt LinguistAdditional Libraries 里的 Qt Serial Port、Qt Multimedia装完之后Qt会装在/opt/Qt之类的目录下。接下来配环境变量我习惯写进~/.bashrcexport QTDIR/opt/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 in /opt/Qt/5.15.2/gcc_64/lib which qtcreator如果qmake -v输出的还是系统自带的版本说明PATH顺序不对或者qtchooser在中间捣乱。可以先which qmake看一下实际调用的是哪个再决定是调整PATH还是把qtchooser移除。实操心得不要把LD_LIBRARY_PATH无脑加到全局。如果你同时在做别的项目比如某些依赖系统Qt的桌面应用全局改LD_LIBRARY_PATH会让它们加载到错误版本的Qt库出现莫名其妙的崩溃。我的做法是只在开发Qt项目时用脚本临时设置或者干脆在Qt Creator的Kit里配置好不动系统全局变量。3.3 路线C源码编译给特殊需求留的后路源码编译适合两种场景需要裁剪模块或者目标平台没有现成的二进制包。流程不算复杂但耗时长一台8核16G的机器编Qt Base大概要40分钟到1小时具体看配置。tar -xf qt-everywhere-src-5.15.2.tar.xz cd qt-everywhere-src-5.15.2 ./configure -prefix /opt/Qt5.15.2-src \ -opensource -confirm-license \ -release -nomake examples -nomake tests \ -qt-xcb -xcb \ -skip qtwebengine -skip qtwebkit \ -no-openssl make -j$(nproc) sudo make install几个参数的解释值得仔细看。-prefix决定安装路径建议单独放一个目录跟离线包装的Qt区分开。-nomake examples -nomake tests能砍掉大量编译时间除非你要参考示例代码否则没必要编。-skip qtwebengine是大头Qt WebEngine本质上是打包了一个Chromium编译它需要额外的一堆依赖编译时间能翻好几倍不做浏览器相关开发就直接跳过。-j$(nproc)是按CPU核心数并行编译nproc会自动返回核心数8核就是-j8。内存不够的机器不要盲目加高并行度一般每核心配1.5到2GB内存比较稳16G内存配8核是合适的32G内存可以上到16核。编译过程中如果报错停住先看最后一个错误信息通常是缺某个dev包。常见的几个缺libxcb-xinerama0-dev、缺libfontconfig1-dev、缺libssl-dev。补装之后不用从头来configure生成的Makefile还在直接再跑make会接着编。注意事项源码编译时如果中途改了configure参数一定要先make distclean再重新配置否则缓存会导致一些诡异的链接错误。这个坑我踩过一次找了大半天。3.4 Qt Creator里的Kit到底怎么配才对IDE装好了不代表能编译Kit构建套件才是决定成败的地方。打开Qt Creator进 工具 → 选项 → 构建套件重点看三个标签页Qt版本、编译器、构建套件。Qt版本页要手动添加你安装的qmake路径比如/opt/Qt/5.15.2/gcc_64/bin/qmake添加后Creator会自动识别出版本号。如果这里显示红色感叹号说明qmake不可执行或者依赖库缺失可以在终端里直接跑一下这个qmake看报什么错。编译器页一般会自动检测到系统里的GCC如果没检测到手动指定/usr/bin/gcc和/usr/bin/g。构建套件页是把Qt版本、编译器、调试器组合起来调试器选/usr/bin/gdb。配置完成后套件名称旁边的圆圈会变绿这时候才算是真正可用了。我遇到过一种情况套件显示正常但一编译就报cannot find -lQt5Core。这通常是Kit里选错了Qt版本或者你在.pro里写死了某个库路径。排查方法是在Qt Creator的编译输出面板里看完整的链接命令把-L路径和实际的库目录对一遍问题基本就定位了。4. 跑起第一个工程项目配置与工具链打通4.1 新建工程与.pro、CMakeLists的差别Qt Creator建工程时会让选构建系统qmake 和 CMake 二选一。这事没有绝对的对错但我给个明确的建议如果是维护老项目、或者团队里都是Qt 5的老手用qmake.pro文件写起来直观语法也简单如果是新项目、或者未来有迁到Qt 6的打算用CMake因为Qt 6已经把CMake作为一等公民qmake的支持在逐步弱化。一个典型的.pro长这样QT core gui widgets serialport network greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET UosQtDemo TEMPLATE app CONFIG c11 SOURCES main.cpp mainwindow.cpp HEADERS mainwindow.h注意这里的QT serialport network加模块就是在这一行加这是Qt开发里最常见的改动。很多人编译报unknown module in qt:serialport就是因为.pro里没写或者是模块没装。对应的CMakeLists.txt写法cmake_minimum_required(VERSION 3.16) project(UosQtDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 11) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTORCC ON) find_package(Qt5 COMPONENTS Widgets SerialPort Network REQUIRED) add_executable(UosQtDemo main.cpp mainwindow.cpp) target_link_libraries(UosQtDemo PRIVATE Qt5::Widgets Qt5::SerialPort Qt5::Network)CMake的好处是依赖查找失败时会给比较清楚的提示比如Could not find a package configuration file provided by Qt5SerialPort直接告诉你哪个模块没找到。缺点是写法比.pro啰嗦。4.2 串口、网络这些模块报unknown module怎么办qt unknown module in qt:serialport 这个报错在搜索里的出现频率很高我单独拆开讲。它的含义很直白Qt的qmake在配置阶段找不到SerialPort模块。原因无非两个模块没装或者装了但qmake看不见。如果是路线A装的Qt补装对应的dev包就行sudo apt install libqt5serialport5-dev如果是路线B的离线包打开Qt目录下的MaintenanceTool重新勾选Qt Serial Port组件它会下载并安装到对应版本目录下。装完在终端确认一下ls /opt/Qt/5.15.2/gcc_64/lib/ | grep -i serial # 期望看到 libQt5SerialPort.so 之类的文件 ls /opt/Qt/5.15.2/gcc_64/include/ | grep -i serial # 期望看到 QtSerialPort 目录两处都在才说明模块真正可用。只有so没有头文件一样编译不过。如果两处都在但qmake还是报找不到检查一下是不是开了多个Qt版本导致qmake指错了地方qmake -query QT_INSTALL_LIBS可以打印出当前qmake认定的库目录拿它跟实际目录对一下。网络模块的情况类似QT network对应的底层是libQt5Network一般不用单独装因为它是qtbase的一部分。但如果你用的是系统的SSL可能会在运行期报TLS相关错误这时候补libssl-dev并确认Qt编译时启用了OpenSSL支持。4.3 调试器、Git和代码补全的配置调试器这块系统自带的gdb一般够用但要确认版本不要太老太老的话对C11以上标准的调试信息解析会有问题。装完gdb之后在Qt Creator里指定路径即可。如果你想用更现代一点的调试体验可以试试lldb或者Qt Creator自带的调试器不过gdb在Linux上依然是最稳的选择。Git集成是Qt Creator自带的功能在 偏好设置 → 版本控制 里填上用户名和邮箱就行。日常我常用的操作是在Creator里直接看diff、提交遇到复杂的分支操作再切回命令行。这里有个小技巧如果你的项目用了submodule或者大文件可以在Creator里关闭自动刷新文件系统否则它会频繁扫描目录IDE会有一卡一卡的感觉。代码补全依赖的是clang的解析引擎Qt Creator默认会启用。如果补全很慢或者不准检查一下项目是不是太大导致解析超时可以在 工具 → 选项 → C → Clang Code Model 里调整。文件大小限制和解析超时这两个参数调大一点大项目的补全体验会明显变好。4.4 交叉编译到ARM板子的补充说明这块是给嵌入式方向的朋友准备的纯桌面开发者可以跳过。交叉编译的核心是三样东西交叉工具链、目标平台的sysroot、跟目标平台版本一致的Qt源码。大概流程是先拿到厂商给的交叉工具链通常在/opt下类似gcc-linaro-xxx的目录。然后用这个工具链去编译一份Qt./configure -prefix /opt/Qt5.15.2-arm \ -opensource -confirm-license \ -release -nomake examples -nomake tests \ -xplatform linux-aarch64-gnu-g \ -sysroot /opt/sysroot \ -no-opengl -linuxfb \ -skip qtwebengine make -j$(nproc) sudo make install关键是-xplatform和-sysroot。-xplatform指定mkspecQt源码里有现成的linux-aarch64-gnu-g可以用如果你的工具链前缀和它默认的不一样可能需要在mkspec文件里改QMAKE_CC和QMAKE_CXX。-sysroot指向目标系统的根文件系统副本里面要有目标板的头文件和库一般从板子的SDK或者直接导出根文件系统得到。-no-opengl -linuxfb这两个参数是给没有GPU的板子用的直接走framebuffer省去OpenGL ES的依赖。如果你的板子有GPU就换成对应的EGLFS配置。编译完之后在Qt Creator里新建一个Kit把Qt版本指向这份交叉编译的Qt编译器指向交叉工具链的g就可以在IDE里直接编译并部署到板子了。实操心得交叉编译最容易出问题的地方不是编译本身而是运行期的库路径。板子上跑程序时如果报缺libQt5Core.so.5把编译出来的Qt库拷到板子的/usr/lib下或者设置LD_LIBRARY_PATH指向你放的目录。另外要注意板子和主机的glibc版本差异差异太大时编译出来的程序在板子上会报GLIBC_2.xx not found这种情况只能换一个和板子版本接近的交叉工具链。5. 常见问题与排查实录5.1 启动类故障速查表这类问题的特点是程序装好了但打不开或者打开了闪退。我整理了一张表按报错信息查命中率比较高。现象或报错常见原因处理办法Could not load the Qt platform plugin xcb缺xcb相关库装 libxcb-xinerama0 等一整套xcb库双击Qt Creator无反应缺图形依赖或权限问题终端里运行看报错补装 libgl1-mesa-dev启动报error while loading shared libraries: libQt5Core.so.5LD_LIBRARY_PATH未设置或版本冲突检查环境变量确认指向正确Qt目录界面能起来但菜单是方块字缺中文字体装 fonts-noto-cjk、fonts-wqy-microhei输入法候选框不显示QT_IM_MODULE未设置设置 QT_IM_MODULEfcitxGLIBC_2.xx not found编译环境glibc比运行环境新换工具链或在目标环境编译Qt platform plugin eglfs加载失败目标板缺EGL库或配置检查板子的GPU驱动和qt.conf查xcb插件问题有个很有效的技巧设置export QT_DEBUG_PLUGINS1然后再启动程序Qt会把插件加载的全过程打印出来具体缺哪个库、在哪个路径找的一目了然。这比一个个试错快得多。export QT_DEBUG_PLUGINS1 ./YourApp输出的内容会比较长重点看 Cannot load library 和 not found 这两类关键字顺藤摸瓜去补对应的包。5.2 中文乱码与解压乱码Linux上的中文乱码分两种一种是界面显示乱码一种是文件名乱码处理思路完全不同。界面显示乱码多半是字体问题。Qt程序默认会通过fontconfig找字体如果系统里没装中文字体就会退化成方块。装完fonts-noto-cjk之后一般能解决。如果装了还是不行可以在程序里显式指定字体QFont font(Noto Sans CJK SC); font.setPointSize(10); qApp-setFont(font);文件名乱码的根源是编码Windows下压缩包常用GBK或者GB18030编码文件名Linux下默认按UTF-8解析自然就乱了。解决办法是解压时指定编码# 用 unzip 指定 GBK unzip -O GBK archive.zip -d output/ # 用 unar 自动探测编码成功率更高 sudo apt install unar unar archive.zipunar这个工具在编码识别上比unzip聪明不少碰到乱七八糟的压缩包我一般直接用它。如果已经解压乱码了不想重新解压可以用convmv批量改回UTF-8sudo apt install convmv convmv -f GBK -t UTF-8 -r --notest ./乱码目录顺便说一句如果你要在UOS和Windows之间传文件尽量用支持UTF-8编码的压缩工具或者干脆用文件共享、局域网传输工具从源头上避开这个问题。5.3 运行期缺库与发布打包开发阶段跑得好好的程序拷到另一台机器上就报缺库这是Linux下分发Qt程序的经典问题。Qt程序默认链接的是动态库目标机器上如果没装对应版本的Qt运行库就跑不起来。最省事的做法是用linuxdeployqt打包成AppImage它会自动把依赖的Qt库和插件收集到一起# 下载 linuxdeployqt 可执行文件后 chmod x linuxdeployqt-continuous-x86_64.AppImage ./linuxdeployqt-continuous-x86_64.AppImage YourApp \ -appimage -unsupported-allow-new-glibc打包过程中如果提示缺少某些库按提示补装即可。打出来的AppImage文件可以直接拷到其他机器运行不需要目标机器装Qt。这个方法有个前提打包机器上的glibc版本不能比目标机器新否则还是会报GLIBC版本错误。所以正式打包最好在一个相对老的基础环境里做兼容性会更好。另一个常见做法是写一个启动脚本在里面设置LD_LIBRARY_PATH并把Qt库一起打包进发行目录#!/bin/bash DIR$(cd $(dirname $0) pwd) export LD_LIBRARY_PATH$DIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$DIR/plugins exec $DIR/YourApp $这种做法更可控缺点是得自己收集库文件。可以用ldd YourApp打印出所有依赖再配合readelf -d看间接依赖一个个拷进lib目录。麻烦是麻烦点但胜在透明出了问题好排查。6. 我在实际项目中攒下的几个经验写到这里把这几条压箱底的经验补上都是文档里不写但实际会遇到的东西。第一条关于系统自带Qt和你自己装Qt的冲突。UOS上有些系统组件本身就依赖Qt所以系统里必然有一份Qt运行库。你自己再装一份两者混在一起的时候最容易出现的就是我的程序在我机器上跑得好SysV IPC的插件加载了系统那份。规避方法很简单给Qt Creator的启动脚本单独设置环境变量不要往全局的/etc/profile里塞。再有就是打包的时候用ldd确认每个库的实际路径别想当然。第二条关于备份和重装。UOS有保留数据的重装方式但Qt环境这种东西重装之后基本等于从零来。我的做法是把Qt安装目录整个放到单独分区重装系统时挂载回来然后在~/.bashrc里重新配一下PATH和LD_LIBRARY_PATH就能继续用。前提是系统的glibc版本没有大变化否则编译好的二进制可能不兼容。源码编译的那种更保险因为它跟系统库的耦合更少。第三条关于版本锁定。团队协作时一定要把Qt的确切版本号写进项目文档包括补丁号。Qt 5.15.2 和 5.15.9 在某些模块的行为上是有差异的尤其是Qt Network和Qt GUI。我在一个项目上遇到过两边版本不一致导致断点续传逻辑表现不同的情况查了两天才定位到是Qt小版本差异。第四条善用官方文档和源码自带的示例。Qt安装目录下的Examples和Demos里几乎覆盖了所有模块的用法比网上的二手教程靠谱。碰到某个类不知道怎么用直接在Qt Creator里按F1调出帮助文档这是最省时间的路径。最后提一个实际部署时会碰到的小事Qt程序的图标和桌面快捷方式。UOS用的是freedesktop规范需要准备一个.desktop文件放到/usr/share/applications/再配一个图标文件。.desktop里的Exec字段如果程序依赖环境变量记得写成调用启动脚本而不是直接调可执行文件很多桌面图标点开报缺库、终端里跑就正常的问题根源都在这里。 统信UOS下Qt开发环境搭建与避坑实战
国产Linux桌面这几年在工控、轨道交通、电力这些行业铺得很快统信UOS是出镜率相当高的一个。很多做上位机、HMI、仪器仪表界面的团队原来在Windows上用Qt Creator写得好好的一转到统信UOS上就发现事情没那么顺手软件源里的Qt版本偏老、装完Qt Creator打不开、xcb插件报错、中文输入法在编辑器里不弹候选框。这些问题单看都不难堆在一起就足够耗掉一个礼拜。这篇就把我在统信UOS上搭Qt开发环境的完整过程摊开讲一遍从系统准备、依赖补齐、三条安装路线的取舍到Qt Creator的Kit配置、第一个工程的跑通、交叉编译到ARM板的补充最后整理一份常见故障速查表。内容偏实操适合两类人一是第一次在国产Linux桌面上做Qt开发的工程师二是已经在上面装过但总被各种报错卡住的朋友。我尽量把每个选择背后的理由也讲清楚省得你照着敲完命令还是一头雾水。1. 先想清楚统信UOS做Qt开发方案怎么选1.1 统信UOS的底子和Qt的匹配度统信UOS专业版走的是Debian系的包管理apt、dpkg、deb包这一套是通的这一点很关键因为它意味着绝大多数Debian/Ubuntu上的Qt安装经验可以直接迁移过来而不需要重新学一套。UOS 20系列的桌面环境是自研的DDE窗口管理器、输入法框架、字体渲染链路都做过定制Qt的默认平台插件是xcb走的是X11协议栈兼容性总体没有大问题但在几个地方容易翻车一个是系统预装的Qt运行库和你要装的开发版Qt可能版本打架另一个是DDE对窗口装饰、托盘图标、高分屏的处理有自己的逻辑Qt程序跑起来界面可能跟你在Windows上看到的不完全一样。Qt本身对Linux的支持是相当成熟的从Qt 5.9 LTS到5.15 LTS再到Qt 6.x源码里对X11、Wayland、EGLFS都有完整实现。在UOS上做开发你大概率会碰到两种落地形态一种是纯桌面应用跑在UOS自带的X11会话上按普通桌面程序的路子走另一种是嵌入式HMI本机开发、交叉编译后丢到ARM板子上跑这时候本机环境其实只是个编译主机对界面效果的要求没那么高重点反而是交叉工具链和sysroot的配置。我个人的判断是如果你是第一次在UOS上搭Qt先把心态放平不要指望一条命令搞定也不要急着上最新的Qt 6。把系统依赖、图形库、字体、输入法这四个基础盘理清楚后面的安装反而快。1.2 三条安装路线什么时候用哪条在统信UOS上装Qt能走的路其实就三条各有各的适用场景我按省事程度和可控程度做个对照你可以直接对号入座。路线具体做法优点缺点适合谁A系统源安装apt install qtcreator qtbase5-dev等依赖自动解决和系统库版本一致版本偏旧组件不全只想快速验证、做小工具B官方离线安装包下载.run安装包图形化勾选组件版本可选、组件完整、可多版本共存需要手动补依赖包体大正经做项目的人推荐C源码编译configuremakemake install完全可控能裁剪、能定制耗时长依赖坑多有特殊裁剪需求、要做交叉编译我个人在项目里最常用的是路线B。理由很实在官方离线包能一口气把Qt Creator、多个Qt版本、Qt Charts、Qt SerialPort、Qt Virtual Keyboard这些模块都装齐装完就是一个独立的目录跟你系统自带的Qt互不干扰哪天搞坏了直接删目录重来不用去动系统的包状态。路线A适合临时用一下比如你只是想跑个demo看看串口通不通装个 qtbase5-dev 加 qtcreator 就够了。路线C我一般只在两种情况下用一是目标板子的Qt需要裁剪掉WebEngine这种巨型模块二是官方包里的某个组件和我的交叉工具链不匹配。1.3 Qt版本怎么定别一上来就追新版本这块我踩过坑值得单独说。Qt 5.15是最后一个5.x的LTS生态最成熟社区资料最多第三方库兼容性最好Qt 6.x 在图形栈上换成了RHI对高分屏、Vulkan、Metal支持更好但很多老项目的.pro文件直接迁过去会报一堆废弃警告第三方库比如某些工业通信SDK还在用Qt 5的API。统信UOS系统源里带的通常是Qt 5.11到5.15之间的某个版本具体看你装的UOS版本。如果你做的是工业上位机依赖Modbus、串口、CAN、OPC UA这类库我建议锁死Qt 5.15.x别折腾。如果是从零开始的新项目又不需要太多历史包袱可以考虑Qt 6.5 LTS但一定要确认你用的所有第三方库都有Qt 6的适配版本否则编译期就会发现一堆no member named。还有一个容易忽略的点Qt Creator的版本和Qt库的版本是两码事。Qt Creator 4.11、4.15、10、12这些是IDE自身的版本它可以管理从Qt 4到Qt 6的所有Kit。你完全可以装一个较新的Qt Creator然后用它去编译Qt 5.15的项目这是官方支持的用法不用强迫自己版本对齐。2. 装之前必须做的事系统准备与依赖补齐2.1 确认系统版本、架构和软件源状态动手之前先摸清家底这一步花两分钟能省掉后面半小时的困惑。打开终端依次执行下面几条命令把结果记下来。cat /etc/os-release # 看系统版本UOS 20 还是其他 uname -m # 看架构x86_64 还是 aarch64/loongarch64 dpkg --print-architecture # 确认包架构 free -h # 看内存源码编译很吃内存 df -h /opt # 看 /opt 剩余空间离线包通常要 5G 以上架构这条特别重要。统信UOS覆盖了x86_64、ARM64、LoongArch、SW64等多个平台Qt官方的离线安装包只提供x86_64版本如果你手上是ARM64的机器比如某些国产笔记本或者飞腾、鲲鹏平台的整机路线B直接就走不通只能走系统源或者源码编译。我在一台飞腾平台的机器上折腾过最后是用系统源装的Qt 5.15加自己编译的Qt Creator过程比x86平台麻烦不少。软件源这边UOS的源配置一般在/etc/apt/sources.list或者/etc/apt/sources.list.d/下面。先执行sudo apt update看能不能正常拉到索引。如果报无法连接或者速度极慢检查一下是不是源地址被改过、网络是否走了内网代理。有些企业内网环境会自建镜像源这种情况下让运维给一份正确的源地址别自己去网上抄。2.2 一次性装齐编译工具链与图形依赖Qt在Linux上跑表面上是缺这个库缺那个库实际上就是这几个大类的依赖编译工具链、OpenGL/GLES相关、X11的xcb系列、字体渲染、输入法框架、音频和多媒体。我习惯一次性装齐避免装到一半报错再回头补。sudo apt update sudo apt install -y \ build-essential cmake ninja-build pkg-config git \ gdb valgrind strace \ libgl1-mesa-dev libglu1-mesa-dev libegl1-mesa-dev \ libx11-dev libxext-dev libxrender-dev libxi-dev \ libxkbcommon-dev libxkbcommon-x11-dev \ libxcb1-dev libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \ libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ libxcb-shape0 libxcb-shm0 libxcb-sync1 libxcb-xfixes0 \ libfontconfig1 libfreetype6 libdbus-1-dev \ libssl-dev libasound2-dev libpulse-dev \ libnss3 libxcursor1 libxcomposite1 libxdamage1 libxtst6 \ fonts-noto-cjk fonts-wqy-microhei这里每一组都有明确的用途我挑几个重点解释。libxcb-xinerama0是很多人卡住的那个库——Qt程序启动时报 Could not load the Qt platform plugin xcb八成就是缺它或者它旁边的兄弟库。libxkbcommon-x11-dev关系到键盘布局和输入法缺了会出现输入法候选框不弹出、快捷键失灵。fonts-noto-cjk和fonts-wqy-microhei是中文显示的基础缺字体的话界面上的中文会变成一排方块这个现象在刚装完的干净系统上非常常见。libasound2-dev和libpulse-dev是给Qt Multimedia用的如果你项目里有音视频播放这两个必须装否则QT multimedia一编译就报错。提示装依赖这一步不管走哪条安装路线都要做。很多人以为用官方离线包就不需要系统依赖结果装完Qt Creator双击没反应回头查半天才发现是xcb库缺失。2.3 开发者模式、sudo权限和磁盘空间统信UOS默认给普通用户的权限是收紧的尤其是较早的版本root密码是不公开的需要用户自己在控制中心里开启开发者模式。开启路径大致是控制中心 → 通用 → 开发者模式 → 进入开发者模式按提示操作后重启。开启之后你的账号就有了sudo权限前面那些apt命令才能执行。这一步听起来像是废话但我见过不止一个人卡在这里终端里敲sudo apt update提示密码不对然后开始怀疑是不是装系统时设错了密码其实根本没开开发者模式。另外要注意部分企业版UOS的开发者模式需要走离线激活得先申请机器码、拿到离线证书文件再导入这个过程可能需要一两天建议提前办。磁盘空间也是提前要看的。官方离线安装包解开之后如果勾选了Qt 5.15的全部组件加Qt 6轻松超过15GB。源码编译的话Qt Base单独编译完大概3到5GB如果把Qt WebEngine算进去中间产物能到20GB以上。所以/opt或者你准备放Qt的目录最好留出30GB以上的空间。我一般会把Qt装在/opt/Qt下面源码编译的中间目录放在家目录两个分开方便管理和清理。2.4 中文输入法的坑提前处理输入法这事看起来很边缘但对日常写代码影响巨大。UOS自带的是fcitx框架拼音输入法默认是有的。Qt程序要通过fcitx输入中文依赖的是Qt的platforminputcontext插件这个插件在系统源装的Qt里一般会自带用官方离线包装的Qt则需要手动确认。装完之后在终端里验证echo $QT_IM_MODULE # 期望输出 fcitx echo $XMODIFIERS # 期望输出 imfcitx如果这两个变量是空的可以在~/.profile或者~/.bashrc里补上export QT_IM_MODULEfcitx export XMODIFIERSimfcitx export GTK_IM_MODULEfcitx改完记得重新登录一次会话别只重开终端环境变量对图形程序生效需要重新走一遍登录流程。验证方法是打开Qt Creator在代码编辑器里切到中文输入法打几个字候选框能正常跟随光标就没问题了。注意如果你用的是Qt自带的那种极简桌面会话或者在某些远程桌面环境下输入法的行为会不太一样。远程场景下建议先确认本地输入法的按键事件有没有正确透传过去不然你会以为是Qt的问题。3. 三条路线实操从apt到离线包再到源码编译3.1 路线Aapt仓库直接装十分钟能跑这条路最快适合验证环境和跑小demo。系统源里的相关包名大致是这些sudo apt install -y qtcreator qtbase5-dev qtchooser qt5-qmake \ qtbase5-dev-tools libqt5serialport5-dev libqt5charts5-dev \ qttools5-dev-tools qtdeclarative5-dev装完直接命令行敲qtcreator就能启动。启动之后会自动扫描系统里的Qt版本一般不需要额外配置Kit新建工程就能编译。这条路的短板有两个一是版本UOS源里的Qt大概率是5.11到5.15之间的某个版本具体看源二是组件某些模块比如Qt Virtual Keyboard、Qt WebEngine在源里不一定有对应的dev包缺了只能自己补。有个细节值得说Debian 10以后的版本把qt5-default这个包给去掉了如果你在教程里看到apt install qt5-default在UOS上执行可能会报没有可安装候选。这时候不要慌装qtbase5-dev qtchooser qt5-qmake这套组合效果是一样的。qtchooser是用来在多个Qt版本之间切换的如果你后面又装了官方离线包它可能带来一些路径上的混乱我倾向于在走路线B之前把它卸掉避免qmake -v输出了错误版本。3.2 路线B官方离线安装包最推荐的干净方案这是我最推荐的路线也是用得最久的。流程分几步下载安装包、赋执行权限、运行图形化安装、补依赖、配置环境变量。下载地址在Qt官方的归档站点路径结构是archive/qt/5.15/5.15.2/文件名类似qt-opensource-linux-x64-5.15.2.run。企业内网不方便直连的话可以在一台能上网的机器上下好用U盘或者内网共享拷过去安装包大概1.5GB左右。下载完之后chmod x qt-opensource-linux-x64-5.15.2.run sudo ./qt-opensource-linux-x64-5.15.2.run之所以加sudo是为了让它能默认装到/opt这类系统目录。如果你打算装到家目录下就不需要sudo但要注意路径里不要有中文和空格。安装向导启动后要登录Qt账号没有账号的话可以注册一个也可以选择跳过部分版本支持。组件选择页面是关键我一般这么勾Qt 5.15.2 下的 Desktop gcc 64-bit这是核心Qt Charts、Qt Data Visualization、Qt Virtual Keyboard按项目需要Qt Network Authorization、Qt WebEngine看情况WebEngine体积很大不用就别勾Developer and Designer Tools 下的 Qt Creator、Qt Designer、Qt LinguistAdditional Libraries 里的 Qt Serial Port、Qt Multimedia装完之后Qt会装在/opt/Qt之类的目录下。接下来配环境变量我习惯写进~/.bashrcexport QTDIR/opt/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 in /opt/Qt/5.15.2/gcc_64/lib which qtcreator如果qmake -v输出的还是系统自带的版本说明PATH顺序不对或者qtchooser在中间捣乱。可以先which qmake看一下实际调用的是哪个再决定是调整PATH还是把qtchooser移除。实操心得不要把LD_LIBRARY_PATH无脑加到全局。如果你同时在做别的项目比如某些依赖系统Qt的桌面应用全局改LD_LIBRARY_PATH会让它们加载到错误版本的Qt库出现莫名其妙的崩溃。我的做法是只在开发Qt项目时用脚本临时设置或者干脆在Qt Creator的Kit里配置好不动系统全局变量。3.3 路线C源码编译给特殊需求留的后路源码编译适合两种场景需要裁剪模块或者目标平台没有现成的二进制包。流程不算复杂但耗时长一台8核16G的机器编Qt Base大概要40分钟到1小时具体看配置。tar -xf qt-everywhere-src-5.15.2.tar.xz cd qt-everywhere-src-5.15.2 ./configure -prefix /opt/Qt5.15.2-src \ -opensource -confirm-license \ -release -nomake examples -nomake tests \ -qt-xcb -xcb \ -skip qtwebengine -skip qtwebkit \ -no-openssl make -j$(nproc) sudo make install几个参数的解释值得仔细看。-prefix决定安装路径建议单独放一个目录跟离线包装的Qt区分开。-nomake examples -nomake tests能砍掉大量编译时间除非你要参考示例代码否则没必要编。-skip qtwebengine是大头Qt WebEngine本质上是打包了一个Chromium编译它需要额外的一堆依赖编译时间能翻好几倍不做浏览器相关开发就直接跳过。-j$(nproc)是按CPU核心数并行编译nproc会自动返回核心数8核就是-j8。内存不够的机器不要盲目加高并行度一般每核心配1.5到2GB内存比较稳16G内存配8核是合适的32G内存可以上到16核。编译过程中如果报错停住先看最后一个错误信息通常是缺某个dev包。常见的几个缺libxcb-xinerama0-dev、缺libfontconfig1-dev、缺libssl-dev。补装之后不用从头来configure生成的Makefile还在直接再跑make会接着编。注意事项源码编译时如果中途改了configure参数一定要先make distclean再重新配置否则缓存会导致一些诡异的链接错误。这个坑我踩过一次找了大半天。3.4 Qt Creator里的Kit到底怎么配才对IDE装好了不代表能编译Kit构建套件才是决定成败的地方。打开Qt Creator进 工具 → 选项 → 构建套件重点看三个标签页Qt版本、编译器、构建套件。Qt版本页要手动添加你安装的qmake路径比如/opt/Qt/5.15.2/gcc_64/bin/qmake添加后Creator会自动识别出版本号。如果这里显示红色感叹号说明qmake不可执行或者依赖库缺失可以在终端里直接跑一下这个qmake看报什么错。编译器页一般会自动检测到系统里的GCC如果没检测到手动指定/usr/bin/gcc和/usr/bin/g。构建套件页是把Qt版本、编译器、调试器组合起来调试器选/usr/bin/gdb。配置完成后套件名称旁边的圆圈会变绿这时候才算是真正可用了。我遇到过一种情况套件显示正常但一编译就报cannot find -lQt5Core。这通常是Kit里选错了Qt版本或者你在.pro里写死了某个库路径。排查方法是在Qt Creator的编译输出面板里看完整的链接命令把-L路径和实际的库目录对一遍问题基本就定位了。4. 跑起第一个工程项目配置与工具链打通4.1 新建工程与.pro、CMakeLists的差别Qt Creator建工程时会让选构建系统qmake 和 CMake 二选一。这事没有绝对的对错但我给个明确的建议如果是维护老项目、或者团队里都是Qt 5的老手用qmake.pro文件写起来直观语法也简单如果是新项目、或者未来有迁到Qt 6的打算用CMake因为Qt 6已经把CMake作为一等公民qmake的支持在逐步弱化。一个典型的.pro长这样QT core gui widgets serialport network greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET UosQtDemo TEMPLATE app CONFIG c11 SOURCES main.cpp mainwindow.cpp HEADERS mainwindow.h注意这里的QT serialport network加模块就是在这一行加这是Qt开发里最常见的改动。很多人编译报unknown module in qt:serialport就是因为.pro里没写或者是模块没装。对应的CMakeLists.txt写法cmake_minimum_required(VERSION 3.16) project(UosQtDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 11) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTORCC ON) find_package(Qt5 COMPONENTS Widgets SerialPort Network REQUIRED) add_executable(UosQtDemo main.cpp mainwindow.cpp) target_link_libraries(UosQtDemo PRIVATE Qt5::Widgets Qt5::SerialPort Qt5::Network)CMake的好处是依赖查找失败时会给比较清楚的提示比如Could not find a package configuration file provided by Qt5SerialPort直接告诉你哪个模块没找到。缺点是写法比.pro啰嗦。4.2 串口、网络这些模块报unknown module怎么办qt unknown module in qt:serialport 这个报错在搜索里的出现频率很高我单独拆开讲。它的含义很直白Qt的qmake在配置阶段找不到SerialPort模块。原因无非两个模块没装或者装了但qmake看不见。如果是路线A装的Qt补装对应的dev包就行sudo apt install libqt5serialport5-dev如果是路线B的离线包打开Qt目录下的MaintenanceTool重新勾选Qt Serial Port组件它会下载并安装到对应版本目录下。装完在终端确认一下ls /opt/Qt/5.15.2/gcc_64/lib/ | grep -i serial # 期望看到 libQt5SerialPort.so 之类的文件 ls /opt/Qt/5.15.2/gcc_64/include/ | grep -i serial # 期望看到 QtSerialPort 目录两处都在才说明模块真正可用。只有so没有头文件一样编译不过。如果两处都在但qmake还是报找不到检查一下是不是开了多个Qt版本导致qmake指错了地方qmake -query QT_INSTALL_LIBS可以打印出当前qmake认定的库目录拿它跟实际目录对一下。网络模块的情况类似QT network对应的底层是libQt5Network一般不用单独装因为它是qtbase的一部分。但如果你用的是系统的SSL可能会在运行期报TLS相关错误这时候补libssl-dev并确认Qt编译时启用了OpenSSL支持。4.3 调试器、Git和代码补全的配置调试器这块系统自带的gdb一般够用但要确认版本不要太老太老的话对C11以上标准的调试信息解析会有问题。装完gdb之后在Qt Creator里指定路径即可。如果你想用更现代一点的调试体验可以试试lldb或者Qt Creator自带的调试器不过gdb在Linux上依然是最稳的选择。Git集成是Qt Creator自带的功能在 偏好设置 → 版本控制 里填上用户名和邮箱就行。日常我常用的操作是在Creator里直接看diff、提交遇到复杂的分支操作再切回命令行。这里有个小技巧如果你的项目用了submodule或者大文件可以在Creator里关闭自动刷新文件系统否则它会频繁扫描目录IDE会有一卡一卡的感觉。代码补全依赖的是clang的解析引擎Qt Creator默认会启用。如果补全很慢或者不准检查一下项目是不是太大导致解析超时可以在 工具 → 选项 → C → Clang Code Model 里调整。文件大小限制和解析超时这两个参数调大一点大项目的补全体验会明显变好。4.4 交叉编译到ARM板子的补充说明这块是给嵌入式方向的朋友准备的纯桌面开发者可以跳过。交叉编译的核心是三样东西交叉工具链、目标平台的sysroot、跟目标平台版本一致的Qt源码。大概流程是先拿到厂商给的交叉工具链通常在/opt下类似gcc-linaro-xxx的目录。然后用这个工具链去编译一份Qt./configure -prefix /opt/Qt5.15.2-arm \ -opensource -confirm-license \ -release -nomake examples -nomake tests \ -xplatform linux-aarch64-gnu-g \ -sysroot /opt/sysroot \ -no-opengl -linuxfb \ -skip qtwebengine make -j$(nproc) sudo make install关键是-xplatform和-sysroot。-xplatform指定mkspecQt源码里有现成的linux-aarch64-gnu-g可以用如果你的工具链前缀和它默认的不一样可能需要在mkspec文件里改QMAKE_CC和QMAKE_CXX。-sysroot指向目标系统的根文件系统副本里面要有目标板的头文件和库一般从板子的SDK或者直接导出根文件系统得到。-no-opengl -linuxfb这两个参数是给没有GPU的板子用的直接走framebuffer省去OpenGL ES的依赖。如果你的板子有GPU就换成对应的EGLFS配置。编译完之后在Qt Creator里新建一个Kit把Qt版本指向这份交叉编译的Qt编译器指向交叉工具链的g就可以在IDE里直接编译并部署到板子了。实操心得交叉编译最容易出问题的地方不是编译本身而是运行期的库路径。板子上跑程序时如果报缺libQt5Core.so.5把编译出来的Qt库拷到板子的/usr/lib下或者设置LD_LIBRARY_PATH指向你放的目录。另外要注意板子和主机的glibc版本差异差异太大时编译出来的程序在板子上会报GLIBC_2.xx not found这种情况只能换一个和板子版本接近的交叉工具链。5. 常见问题与排查实录5.1 启动类故障速查表这类问题的特点是程序装好了但打不开或者打开了闪退。我整理了一张表按报错信息查命中率比较高。现象或报错常见原因处理办法Could not load the Qt platform plugin xcb缺xcb相关库装 libxcb-xinerama0 等一整套xcb库双击Qt Creator无反应缺图形依赖或权限问题终端里运行看报错补装 libgl1-mesa-dev启动报error while loading shared libraries: libQt5Core.so.5LD_LIBRARY_PATH未设置或版本冲突检查环境变量确认指向正确Qt目录界面能起来但菜单是方块字缺中文字体装 fonts-noto-cjk、fonts-wqy-microhei输入法候选框不显示QT_IM_MODULE未设置设置 QT_IM_MODULEfcitxGLIBC_2.xx not found编译环境glibc比运行环境新换工具链或在目标环境编译Qt platform plugin eglfs加载失败目标板缺EGL库或配置检查板子的GPU驱动和qt.conf查xcb插件问题有个很有效的技巧设置export QT_DEBUG_PLUGINS1然后再启动程序Qt会把插件加载的全过程打印出来具体缺哪个库、在哪个路径找的一目了然。这比一个个试错快得多。export QT_DEBUG_PLUGINS1 ./YourApp输出的内容会比较长重点看 Cannot load library 和 not found 这两类关键字顺藤摸瓜去补对应的包。5.2 中文乱码与解压乱码Linux上的中文乱码分两种一种是界面显示乱码一种是文件名乱码处理思路完全不同。界面显示乱码多半是字体问题。Qt程序默认会通过fontconfig找字体如果系统里没装中文字体就会退化成方块。装完fonts-noto-cjk之后一般能解决。如果装了还是不行可以在程序里显式指定字体QFont font(Noto Sans CJK SC); font.setPointSize(10); qApp-setFont(font);文件名乱码的根源是编码Windows下压缩包常用GBK或者GB18030编码文件名Linux下默认按UTF-8解析自然就乱了。解决办法是解压时指定编码# 用 unzip 指定 GBK unzip -O GBK archive.zip -d output/ # 用 unar 自动探测编码成功率更高 sudo apt install unar unar archive.zipunar这个工具在编码识别上比unzip聪明不少碰到乱七八糟的压缩包我一般直接用它。如果已经解压乱码了不想重新解压可以用convmv批量改回UTF-8sudo apt install convmv convmv -f GBK -t UTF-8 -r --notest ./乱码目录顺便说一句如果你要在UOS和Windows之间传文件尽量用支持UTF-8编码的压缩工具或者干脆用文件共享、局域网传输工具从源头上避开这个问题。5.3 运行期缺库与发布打包开发阶段跑得好好的程序拷到另一台机器上就报缺库这是Linux下分发Qt程序的经典问题。Qt程序默认链接的是动态库目标机器上如果没装对应版本的Qt运行库就跑不起来。最省事的做法是用linuxdeployqt打包成AppImage它会自动把依赖的Qt库和插件收集到一起# 下载 linuxdeployqt 可执行文件后 chmod x linuxdeployqt-continuous-x86_64.AppImage ./linuxdeployqt-continuous-x86_64.AppImage YourApp \ -appimage -unsupported-allow-new-glibc打包过程中如果提示缺少某些库按提示补装即可。打出来的AppImage文件可以直接拷到其他机器运行不需要目标机器装Qt。这个方法有个前提打包机器上的glibc版本不能比目标机器新否则还是会报GLIBC版本错误。所以正式打包最好在一个相对老的基础环境里做兼容性会更好。另一个常见做法是写一个启动脚本在里面设置LD_LIBRARY_PATH并把Qt库一起打包进发行目录#!/bin/bash DIR$(cd $(dirname $0) pwd) export LD_LIBRARY_PATH$DIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$DIR/plugins exec $DIR/YourApp $这种做法更可控缺点是得自己收集库文件。可以用ldd YourApp打印出所有依赖再配合readelf -d看间接依赖一个个拷进lib目录。麻烦是麻烦点但胜在透明出了问题好排查。6. 我在实际项目中攒下的几个经验写到这里把这几条压箱底的经验补上都是文档里不写但实际会遇到的东西。第一条关于系统自带Qt和你自己装Qt的冲突。UOS上有些系统组件本身就依赖Qt所以系统里必然有一份Qt运行库。你自己再装一份两者混在一起的时候最容易出现的就是我的程序在我机器上跑得好SysV IPC的插件加载了系统那份。规避方法很简单给Qt Creator的启动脚本单独设置环境变量不要往全局的/etc/profile里塞。再有就是打包的时候用ldd确认每个库的实际路径别想当然。第二条关于备份和重装。UOS有保留数据的重装方式但Qt环境这种东西重装之后基本等于从零来。我的做法是把Qt安装目录整个放到单独分区重装系统时挂载回来然后在~/.bashrc里重新配一下PATH和LD_LIBRARY_PATH就能继续用。前提是系统的glibc版本没有大变化否则编译好的二进制可能不兼容。源码编译的那种更保险因为它跟系统库的耦合更少。第三条关于版本锁定。团队协作时一定要把Qt的确切版本号写进项目文档包括补丁号。Qt 5.15.2 和 5.15.9 在某些模块的行为上是有差异的尤其是Qt Network和Qt GUI。我在一个项目上遇到过两边版本不一致导致断点续传逻辑表现不同的情况查了两天才定位到是Qt小版本差异。第四条善用官方文档和源码自带的示例。Qt安装目录下的Examples和Demos里几乎覆盖了所有模块的用法比网上的二手教程靠谱。碰到某个类不知道怎么用直接在Qt Creator里按F1调出帮助文档这是最省时间的路径。最后提一个实际部署时会碰到的小事Qt程序的图标和桌面快捷方式。UOS用的是freedesktop规范需要准备一个.desktop文件放到/usr/share/applications/再配一个图标文件。.desktop里的Exec字段如果程序依赖环境变量记得写成调用启动脚本而不是直接调可执行文件很多桌面图标点开报缺库、终端里跑就正常的问题根源都在这里。