装 Qt 这件事在 Ubuntu 上可能就三行命令但在统信 UOS 上我前后折腾了差不多两天才把整套环境跑通——不是难是坑藏得深。UOS 专业版的内核血统是 Debian桌面是 DDE包管理器还是 apt表面上和 Debian 系一模一样可它的软件源是自建的、包版本偏保守、部分包名直接跟上游对不上你在网上搜到的 Ubuntu 教程十有八九会在某一步卡住。这篇就按我实际踩过的路线把 Linux 统信 UOS 上搭建 Qt 开发环境的完整过程拆开讲从系统体检、依赖清单到 apt 直装 Qt5/Qt6、官方离线包落地、xcb 插件报错、中文输入法与高分屏再到最后的依赖打包和 deb 制作。不管你是第一次在国产系统上写 Qt还是从 Windows 迁过来想找个靠谱的落地路径看完应该能少走不少弯路。1. 为什么统信UOS上的Qt环境不能照搬Ubuntu那套刚上手的时候我也是直接 CtrlC 了一段 Ubuntu 的安装命令结果第一条sudo apt install qt5-default就报无法定位软件包。当时第一反应是软件源没更新apt update跑了三遍还是不行才意识到问题不在网络而在包本身。1.1 UOS的底层血统与软件源差异UOS 专业版也叫统信桌面操作系统专业版底层基于 Debian但具体跟哪个版本对齐不同发行批次是有差异的有的是 Debian 10 的底子有的往 11 靠。这对 Qt 开发的影响主要有三点。第一qt5-default这个包在 Debian 10 之后的仓库里已经被移除了上游把它拆成了qtbase5-dev、qt5-qmake、qtchooser等一组包。你在 CSDN 上刷到的老教程里那句apt install qt5-default在 UOS 上必然失败。这不是 UOS 特意改的是跟着上游走的。第二UOS 官方仓库里的 Qt 版本通常偏旧常见的是 5.11 到 5.12 这个区间。做一般的上位机、串口工具、工控界面完全够用但如果你要用 Qt 6 的新特性或者项目要求 5.14/5.15就只能走官方离线安装包这条路。第三很多单位的 UOS 机器是内网环境外网访问受限在线安装器Qt Online Installer跑到正在获取组件列表就会一直转圈。这时候离线安装包几乎是唯一解。提示判断能不能直接用 apt先跑一次apt-cache policy qtbase5-dev看仓库里到底有没有这个包、版本号是多少比盲目搜索快得多。1.2 三条安装路线的取舍逻辑我把在 UOS 上装 Qt 归纳成三条路线各有各的适用场景选错了会在后面反复返工。路线适用场景优点代价apt 直装只做内网工具、版本要求不高一次装全依赖自动解决卸载干净版本偏旧Qt6 支持视仓库而定官方在线安装器有外网、要指定版本组件可选能装 Qt Creator 和附加模块内网跑不动安装目录容易越滚越大官方离线安装包内网、要固定版本、要交付完全离线版本可控包体大组件需要提前想清楚我的建议很直接如果只是做个串口调试工具或者简单的上位机走 apt五分钟搞定如果要长期维护、版本要跟团队对齐走离线包把安装目录放在/opt下统一管理在线安装器基本只在你有顺畅外网、又想试新版本的时候用。还有一点容易被忽略Qt Creator 作为 IDE在 UOS 上有个独立的包叫qtcreator它跟 Qt 库本身是两回事。你完全可以用 apt 装 Qt Creator再用离线包里的 Qt 库二者通过 Kit 关联起来。这个组合在 UOS 上其实是最省心的。2. 动手前的系统体检与依赖清单我见过太多人一上来就敲安装命令装到一半报缺库然后开始一顿乱装最后系统里堆了一堆半成品。花五分钟做个体检后面能省两小时。2.1 确认系统版本、架构与可用磁盘先看系统身份。UOS 有多个架构版本x86_64 是最常见的但信创项目里 aarch64飞腾/鲲鹏、loongarch64龙芯也不少架构对不上安装包直接白下。cat /etc/os-release uname -m dpkg --print-architecture/etc/os-release会告诉你发行版名称和版本号uname -m给出内核架构注意内核架构和用户态架构在极少数定制机型上可能不一致所以再补一条dpkg --print-architecture看 apt 认的架构。然后是磁盘。Qt 离线包安装完加上 Qt Creator 和几个附加模块占个 8 到 15 GB 很正常如果勾了源码和文档20 GB 都打不住。df -h /opt df -h $HOME du -sh ~/.cache 2/dev/null/opt通常挂在根分区上$HOME可能是独立分区。我一般把 Qt 装在/opt/Qt一来路径固定好记二来团队里所有人的环境变量可以写成同一份脚本。如果/opt空间紧张就装到家目录但要记得路径里带用户名脚本不能通用。提示UOS 的安装器特别是 .run 格式的在创建快捷方式、写~/.local/share/applications时如果你是用 sudo 跑的文件属主会变成 root之后普通用户改不了、删不掉还会出现菜单里有图标但点不开的诡异现象。一定用普通用户身份运行。2.2 软件源与apt使用注意UOS 的 apt 源配置文件在/etc/apt/sources.list有的版本还会在/etc/apt/sources.list.d/下放额外的源。先看看内容确认仓库是否可达。cat /etc/apt/sources.list ls /etc/apt/sources.list.d/ sudo apt updateapt update报错的话常见就两种一是源地址不通内网没开白名单二是 GPG 密钥过期。前者只能找运维后者可以用sudo apt-key adv或者把密钥放到/etc/apt/trusted.gpg.d/下解决。我不建议随便往 sources.list 里加第三方源来凑齐 Qt 的包UOS 的库版本是有整体一致性的混源容易把系统搞出依赖冲突得不偿失。另外一个小细节UOS 默认可能开了自动锁屏和休眠长时间编译到一半锁屏某些显卡驱动下会导致 Qt Creator 的渲染出现花屏。在控制中心 - 电源管理里把自动锁屏时间调长或者干脆关掉编译体验会好很多。2.3 编译工具链一次性装齐Qt 只是框架它底下还要靠编译器、构建工具和一堆开发头文件撑着。我习惯用一个命令把基础工具链一次装好避免后面报错来回补。sudo apt install -y \ build-essential \ gcc g make \ cmake ninja-build \ pkg-config \ git \ gdb \ ccache逐个说下为什么要它们。build-essential是元包会带上 gcc、g、make、libc6-dev 这些基础件几乎是必备cmake和ninja-build是给 CMake 工程用的Qt 从 5.15 开始官方推荐 CMake 构建Ninja 比 make 快一截尤其在中大型工程上差距明显pkg-config有些第三方库比如 OpenCV、FFmpeg的头文件路径要靠它来找gdb是调试用Qt Creator 里断点调试全靠它ccache是编译缓存反复重编译时能省一半以上时间我个人强烈建议装上配置也就是加个软链接的事。想启用 ccache在~/.bashrc里加一行就行export PATH/usr/lib/ccache:$PATH这样 gcc/g 会优先走 ccache 包装器编译命令完全不用改。第一次编译没变化第二次开始就能看到命中率了用ccache -s可以查看统计。3. 路线一用apt把Qt5基础开发包装进系统这条路线适合绝大多数我就想在 UOS 上写个小工具的场景。装完之后系统和 Qt 库是融为一体的升级、卸载都用 apt 管非常干净。3.1 核心包与可选包清单基础开发包其实就两三个但我一般会把常用的附加模块一起装上省得后面缺什么补什么。sudo apt install -y \ qtbase5-dev \ qtbase5-dev-tools \ qt5-qmake \ qtchooser \ qttools5-dev-tools \ libqt5serialport5-dev \ libqt5svg5-dev \ qtmultimedia5-dev \ qtdeclarative5-dev每个包的作用值得说清楚不然你不知道该装哪个。qtbase5-dev是核心包含 QtCore、QtGui、QtWidgets、QtNetwork 这些最常用的模块头文件和链接库qtbase5-dev-tools带的是 moc、uic、rcc 这类元对象编译工具没有它连信号槽都编译不过qt5-qmake是 qmake 构建系统本体qtchooser是版本选择器后面讲多版本共存会用到。qttools5-dev-tools里有个 Linguist 系列工具做多语言翻译时要用libqt5serialport5-dev是串口模块工控和嵌入式调试场景几乎必装这个包在 UOS 上名字和 Ubuntu 一致可以直接装libqt5svg5-dev处理 SVG 图标qtmultimedia5-dev管音视频qtdeclarative5-dev是 QML/Quick 相关。如果你的 UOS 仓库里已经有 Qt6也可以顺手装上两代可以共存apt-cache policy qt6-base-dev sudo apt install -y qt6-base-dev qt6-tools-dev装之前用apt-cache policy确认一下有没有没有就别硬来报无法定位软件包的时候心情会不太好。3.2 验证qmake、版本切换与qmake -query装完别急着开 IDE先在命令行验证。这一步能提前暴露 80% 的环境问题。qmake -v which qmake qmake -queryqmake -v会输出类似QMake version 3.1和Using Qt version 5.12.8 in /usr/lib/x86_64-linux-gnu的信息。如果qmake命令找不到多半是 qtchooser 没配好或者 PATH 里没包含 Qt 的 bin 目录。系统里同时有 Qt5 和 Qt6 的时候qmake究竟指向哪个就要靠 qtchooser 管了qtchooser -list-versions export QT_SELECTqt5 qmake -vqtchooser -list-versions会列出当前可选的版本用QT_SELECT环境变量切换。但说实话qtchooser 在 UOS 上偶尔会抽风明明装了却列不出来。这种情况下我一般直接用绝对路径最省心/usr/lib/qt5/bin/qmake -v /usr/lib/qt6/bin/qmake -v用绝对路径的好处是没有任何歧义写脚本、配 IDE 都不会错。代价就是路径写死了跨机器要改。这是个取舍看你的场景。编译一个最小工程验证一下比什么都直观。建个目录写个main.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(QStringLiteral(UOS 上的 Qt 跑起来了)); label.setAlignment(Qt::AlignCenter); label.resize(360, 120); label.show(); return app.exec(); }用 qmake 编译qmake -project qmake make ./项目名如果窗口弹出来了说明库、编译器、链接器整条链路都是通的。这一步过了后面基本就是 IDE 配置的事了。3.3 Qt Creator 的安装与 Kit 配置Qt Creator 在 UOS 上可以直接 apt 装sudo apt install -y qtcreator装完之后从启动器里能找到Qt Creator。第一次打开会进到首选项 - 构建套件Kit页面这里是新手最容易懵的地方。我解释一下三个核心概念。Qt VersionsQt 版本指向qmake可执行文件的路径Qt Creator 通过它反向推导出 Qt 的头文件目录、库目录和版本号。apt 装的 Qt 一般是/usr/bin/qmake或/usr/lib/qt5/bin/qmake点添加选上就行。Compilers编译器C 编译器路径apt 装的就是/usr/bin/gC 是/usr/bin/gcc。一般 Qt Creator 会自动检测到检测不到手动加。Kits构建套件把上面两者加上调试器组合起来的一套配置。名字随便起比如UOS-Desktop-Qt5关键是Qt Version和Compiler两项要选对还有Debugger要指向/usr/bin/gdb。配好之后新建工程编译运行如果报没有可用的构建套件九成是 Kit 里某一项是红的。挨个看红的那项就是问题所在。提示如果你用离线包装的 QtKit 里的 qmake 路径要指向~/Qt/5.14.2/gcc_64/bin/qmake这类位置而不是/usr/bin/qmake。两套环境混用的时候工程切换构建套件要记得同步切换不然会出现头文件是新的、库是旧的这种典型链接错误。4. 路线二官方离线安装包落地UOS的完整流程需要指定 Qt 版本或者机器在内网就走这条。流程比 apt 长但可控性高得多。4.1 选版本、下载与赋权版本怎么选我的经验是新项目优先 5.15.x这是 Qt5 的最后一个长期支持系列生态最成熟第三方库兼容性最好如果项目要求 Qt6那就 6.5 或更高的 LTS 版本。5.14.2 是老项目里出现频率很高的版本很多既有代码都基于它迁移成本低所以也常被选。下载下来的文件是个.run后缀的自解压安装器名字类似qt-opensource-linux-x64-5.14.2.run。关键一步是赋可执行权限chmod x qt-opensource-linux-x64-5.14.2.run ./qt-opensource-linux-x64-5.14.2.run注意前面不要加 sudo。我一开始图省事加了 sudo装完结果 Qt Creator 的配置目录属主是 root一打开就提示无法写入配置改都改不动。只能把装好的目录整个删掉重来白白浪费半小时。还有一点安装器是图形界面的必须在桌面会话里跑不能通过 SSH 无界面执行。4.2 安装器卡住、组件勾选与离线包缺失如果是离线安装包安装器启动后会先让你登录 Qt 账号新版本必须老版本 5.14.2 可以跳过然后进入组件选择页。这一步是整个流程里最需要动脑的地方。安装路径我建议/opt/Qt或者$HOME/Qt。/opt/Qt更规范但要保证普通用户对该目录有写权限sudo mkdir -p /opt/Qt sudo chown $USER:$USER /opt/Qt这样安装器就能正常写入了同时又不用 sudo 运行安装器一举两得。组件勾选最少要勾这几项——Qt 对应版本下的Desktop gcc 64-bit这是 x86_64 桌面开发的核心库Qt CreatorIDE 本体Qt Charts做图表、Qt Serial Port串口这类项目实际会用到的附加模块Sources和Debugging Tools看个人磁盘空间调试时能跳进 Qt 源码对排查问题帮助很大关于卡住离线包理论上不需要网络但安装器启动阶段有时仍会尝试连服务器校验内网环境下这一步会卡很久甚至超时。我的做法是先断网再启动安装器或者在/etc/hosts里把相关域名指向 127.0.0.1让它快速失败然后继续走离线流程。这个办法不优雅但实测有效。4.3 环境变量与多版本共存装完之后Qt 并不会自动加到 PATH 里。要在终端直接敲qmake得配环境变量。我不建议全局改/etc/profile那样会污染整个系统一旦哪天想换版本就会牵一发动全身。写在~/.bashrc里更灵活export QTDIR$HOME/Qt/5.14.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATHLD_LIBRARY_PATH这一条要谨慎。它会覆盖系统默认的库搜索路径如果设得不对可能导致系统自带的 Qt 程序UOS 桌面本身就有不少 Qt 程序启动异常。更安全的做法是不设LD_LIBRARY_PATH而是在编译时通过-Wl,-rpath指定运行时库路径或者干脆只在构建脚本里临时导出。多版本共存的话我习惯用 shell 函数来切换比记住一堆路径靠谱qt514() { export QTDIR$HOME/Qt/5.14.2/gcc_64 export PATH$QTDIR/bin:$PATH qmake -v } qt65() { export QTDIR$HOME/Qt/6.5.0/gcc_64 export PATH$QTDIR/bin:$PATH qmake -v }写进~/.bashrc需要哪个版本就敲哪个命令当前在用哪个版本一目了然。这个小技巧我在好几个项目上用了切换成本几乎为零。5. 让程序真正跑起来xcb、输入法、字体与高分屏库装好了、代码编译通过了双击运行却弹不出窗口——这是 UOS 上 Qt 新手最容易被劝退的环节。问题基本集中在四类平台插件、输入法、字体、缩放。5.1 could not load the Qt platform plugin xcb 的完整解法这是出现频率最高的报错完整信息通常是这样的qt.qpa.plugin: Could not load the Qt platform plugin xcb in even though it was found. This application failed to start because no Qt platform plugin could be initialized.很多人看到even though it was found就懵了既然找到了为什么加载不了原因是 Qt 的平台插件libqxcb.so本身依赖一批 xcb 相关的系统库这些库缺失时插件的动态加载就会失败但 Qt 的错误信息不会告诉你缺了哪个库。排查方法很直接打开插件的调试输出export QT_DEBUG_PLUGINS1 ./你的程序它会打印出加载libqxcb.so的全过程最后几行会明确写出Cannot load library ... libxcb-xxx.so.1: cannot open shared object file缺哪个装哪个。常见的缺失库和对应包如下报错中缺失的库对应的包名libxcb-xinerama.so.0libxcb-xinerama0libxcb-icccm.so.4libxcb-icccm4libxcb-image.so.0libxcb-image0libxcb-keysyms.so.1libxcb-keysyms1libxcb-randr.so.0libxcb-randr0libxcb-render-util.so.0libxcb-render-util0libxcb-shape.so.0libxcb-shape0libxkbcommon-x11.so.0libxkbcommon-x11-0libxcb-xkb.so.1libxcb-xkb1不想一个个排查的话可以一次性把这些都装上反正体积不大sudo apt install -y \ libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \ libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ libxcb-shape0 libxcb-xkb1 libxkbcommon-x11-0还有一个隐藏坑如果QT_QPA_PLATFORM_PLUGIN_PATH这个环境变量被设成了错误的路径或者你手动设过QT_QPA_PLATFORM插件就可能在错误的目录里找。检查一下env | grep QT_如果没有特殊需求这些变量一个都不要设让 Qt 自动推断最省事。跑unset QT_QPA_PLATFORM_PLUGIN_PATH清掉之后往往问题就没了。提示如果你是在 root 用户下运行 Qt 程序还可能碰到另一个问题——root 用户没有继承普通用户的 DISPLAY 和 XAUTHORITY 环境变量导致连不上 X 服务器。用sudo -E保留环境变量或者先xhost local:再运行都能绕过。5.2 中文输入法与字体输入法问题在 UOS 上很典型程序能跑但输入框里打不出中文或者输入法候选框位置跑到屏幕左上角去了。UOS 默认用的是基于 fcitx 的输入法框架搜狗、讯飞之类都是它的前端。Qt5 程序要通过 fcitx 输入中文需要libfcitx-qt5这个插件并且环境变量要对export QT_IM_MODULEfcitx export XMODIFIERSimfcitx export GTK_IM_MODULEfcitx检查插件是否存在的办法是看 Qt 的输入法插件目录ls /usr/lib/x86_64-linux-gnu/qt5/plugins/platforminputcontexts/正常情况下应该能看到libfcitxplatforminputcontextplugin.so。如果没有说明libfcitx-qt5相关的包没装sudo apt install -y fcitx-frontend-qt5如果你用的是离线包安装的 Qt那问题会麻烦一点——那个输入法插件是针对系统 Qt 编译的二进制层面跟离线包的 Qt 版本可能不匹配需要自己把插件编译一份放到离线包的插件目录里。做法是拿系统的插件先试不行再编译源码。字体这块UOS 自带了一套中文字体常见的是方正系列一般不需要额外装。但如果你的 Qt 程序在启动时显示方框或者乱码通常是两个原因一是源码文件的编码不是 UTF-8二是字符串没有正确转换。Qt5 之后的默认编码已经是 UTF-8QStringLiteral和QString::fromUtf8都能正确处理中文。老代码里那些QTextCodec::setCodecForTr的写法可以直接删掉反而容易出问题。判断字体是否真的生效可以在启动时打印一下qDebug() QFontDatabase().families().mid(0, 10);5.3 高分屏与显示缩放UOS 支持在控制中心里设置缩放比例125%、150% 很常见。Qt5 程序在非整数缩放下的表现一直是个痛点要么模糊要么控件重叠要么鼠标点击位置和视觉位置错位。Qt5 需要在程序启动前开启高 DPI 支持#include QApplication int main(int argc, char *argv[]) { QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps); QApplication app(argc, argv); // ... }这两行必须在QApplication构造之前调用写在后面就无效了这是个很容易忽略的顺序问题。AA_EnableHighDpiScaling让控件按缩放比例放大AA_UseHighDpiPixmaps让图标用高清版本而不是放大后模糊。运行时还可以用环境变量临时调export QT_AUTO_SCREEN_SCALE_FACTOR1 export QT_SCALE_FACTOR1.25QT_AUTO_SCREEN_SCALE_FACTOR1让 Qt 跟随系统的缩放设置自动计算QT_SCALE_FACTOR则是强制指定一个倍率。调试布局的时候我经常临时设QT_SCALE_FACTOR来模拟不同缩放下的效果比反复改系统设置快多了。6. 从能编译到能交付依赖梳理与打包自己机器上跑起来只是一半另一半是把程序交到别人手上还能跑。UOS 上分发 Qt 程序最容易出的问题是我这儿好好的同事那儿双击没反应。6.1 ldd 与依赖梳理先把程序依赖了哪些库摸清楚。ldd是最直接的工具ldd ./你的程序 | grep /输出会列出所有运行时需要的共享库。顺序上我建议分成两类看系统库libc、libstdc、libX11 这些不用管UOS 自带并且版本稳定Qt 相关库libQt5Core、libQt5Gui、libQt5Widgets 等要重点关注因为不同机器上的 Qt 版本可能不一样。如果程序用了 Qt 的插件比如platforms/libqxcb.so、imageformats/libqjpeg.so、sqldrivers/libqsqlite.so这些是不出现在ldd输出里的但运行时必须要。这是新手最容易漏的点——你拷了所有.so程序还是起不来就差在插件目录上。6.2 打包方案手动拷贝加rpathlinuxdeployqt是社区里流传很广的自动打包工具思路是扫描可执行文件、把依赖库拷到一起、用patchelf改 rpath。它在 Ubuntu 上比较好用但在 UOS 上我踩过坑它依赖的一些工具版本对不上而且它扫描出来的一些系统库被一起打进去后反而在目标机器上引起冲突。所以我的做法是半手动逻辑清楚、出了问题也好定位。目录结构按 Qt 自己的布局来发布包/ ├── 你的程序 (可执行文件) ├── lib/ (Qt 的 .so 都在这里) │ ├── libQt5Core.so.5 │ ├── libQt5Gui.so.5 │ └── ... ├── plugins/ │ ├── platforms/libqxcb.so │ ├── imageformats/ │ └── ... └── 你的程序.sh (启动脚本)然后用patchelf把可执行文件的 rpath 指向libpatchelf --set-rpath $ORIGIN/lib 你的程序$ORIGIN是个特殊变量表示可执行文件自身所在目录这样整个包放到哪个路径下都能找到库。启动脚本里把插件路径指出来#!/bin/bash DIR$(cd $(dirname $0) pwd) export QT_QPA_PLATFORM_PLUGIN_PATH$DIR/plugins/platforms export QT_PLUGIN_PATH$DIR/plugins exec $DIR/你的程序 $这几个环境变量的含义值得记一下QT_QPA_PLATFORM_PLUGIN_PATH只管平台插件就是那个 xcbQT_PLUGIN_PATH管其他所有插件图片格式、数据库驱动等。两个都设上最保险。6.3 打成deb包并安装验证裸目录分发适合临时用正式一点还是打成 deb。deb 包本质上就是个特定结构的压缩包手工做并不难。先建目录骨架mkdir -p pkg/DEBIAN mkdir -p pkg/opt/myapp mkdir -p pkg/usr/share/applications cp -r 发布包/* pkg/opt/myapp/写控制文件pkg/DEBIAN/controlPackage: myapp Version: 1.0.0 Section: utils Priority: optional Architecture: amd64 Depends: libxcb-xinerama0, libxcb-icccm4, libxcb-image0, libxcb-keysyms1 Maintainer: 你的名字 youexample.com Description: 基于 Qt 的某某工具 一句话功能说明。Architecture要跟你实际打包的平台一致x86_64 写amd64ARM64 写arm64。Depends里列出那些 xcb 相关的库这样安装时 apt 会自动帮你补依赖用户就不用自己去查缺哪个包了。再放一个桌面入口文件pkg/usr/share/applications/myapp.desktop[Desktop Entry] TypeApplication NameMyApp Exec/opt/myapp/你的程序.sh Icon/opt/myapp/icon.png CategoriesDevelopment; Terminalfalse最后打包dpkg-deb --build pkg myapp_1.0.0_amd64.deb验证环节不能省一定要在一台干净的 UOS 机器上装一遍。用sudo dpkg -i装如果报依赖问题用sudo apt -f install补齐。装完从启动器点开能正常出窗口、能输入中文、缩放正常才算真的交付完成。有个小细节.desktop文件里的Exec用绝对路径最稳妥如果用了启动脚本记得给脚本加可执行权限否则双击没反应排查起来很浪费时间。7. 我在UOS上踩过的具体坑与排查清单前面讲的是应该怎么做这一节讲讲我实际踩到的、文档里不会写的那些坑以及一套我常用的排查顺序。7.1 几个印象深刻的坑坑一sudo 跑安装器导致后续全乱。第一次装离线包的时候我图省事sudo ./qt-opensource-linux-x64-5.14.2.run结果 Qt Creator 的配置目录、缓存目录属主全是 root。表现是打开 Qt Creator 后任何设置都保存不了Kit 配好重启就没了。解决方式不是改权限而是把~/.config/QtProject和安装目录一起删掉重装。这个教训让我之后所有 GUI 安装器都坚持用普通用户跑需要写系统目录就提前chown。坑二qt5-default 不存在绕了一大圈。就是开头说的那个一开始以为是自己源配错了折腾半天换源、清缓存最后才发现是包名跟着上游变了。后来我养成了一个习惯装任何包之前先apt-cache search或者apt-cache policy确认一下比盲目试快得多。坑三串口模块缺失导致链接失败。项目里用了QtSerialPortapt 里装的是libqt5serialport5-dev但我用的是离线包 Qt头文件和库不在离线包里编译直接报找不到QtSerialPort/QSerialPort。解决办法是在安装器里勾上 Qt Serial Port 组件或者用系统那一份库但要注意 ABI 匹配。离线包安装时组件一定要一次性想清楚补装虽然可以再跑一次安装器但会覆盖已有配置比较烦。坑四输入法在 Qt6 上失效。Qt5 时代的fcitx-frontend-qt5对 Qt6 无效Qt6 需要单独的输入法插件。如果你用 Qt6 开发中文输入一时半会儿可能搞不定我的临时方案是用 Qt5 做界面开发或者给 Qt6 编译对应的 fcitx 插件。这个坑当时卡了我整整一个下午。坑五离线包 Qt 和系统 Qt 混用的库冲突。程序在开发机上跑得好好的拷到测试机上启动就段错误。排查半天发现是开发机上LD_LIBRARY_PATH指向了离线包的 Qt程序链接的是 5.14 的库而测试机上加载到了系统的 5.12 库ABI 不兼容直接崩。这也是我前面强调 rpath 而不是LD_LIBRARY_PATH的原因。7.2 一张随手可查的排查表遇到问题先别急着搜按下面的顺序过一遍大部分情况三轮之内就能定位。现象首要排查方向常用命令找不到 qmakePATH 或 qtchooser 配置which qmake、qtchooser -list-versionsxcb 插件加载失败缺 xcb 系列系统库QT_DEBUG_PLUGINS1 ./程序窗口弹出后立即退出段错误或库版本冲突ldd ./程序、gdb ./程序输入框打不出中文输入法插件或环境变量echo $QT_IM_MODULE、查插件目录中文显示成方框字体缺失或编码问题fc-list界面模糊或错位高 DPI 未开启检查AA_EnableHighDpiScaling换机器就跑不起来插件未打包或 rpath 不对patchelf --print-rpath 程序编译速度慢得离谱没开 ccache 或并行度低ccache -s、make -j$(nproc)这张表是我压在桌面上的东西每次换新机器搭环境都会对照着走一遍。它的价值不在于解决具体问题而在于让你在慌乱的时候有个固定的起点不至于东一榔头西一棒子。最后再说一个我个人觉得挺有用的小习惯把整套环境搭建过程写成一个 shell 脚本从装依赖、配环境变量到创建目录全部固化下来。UOS 的发行批次之间包名偶尔会有细微差异但绝大部分命令是通用的脚本跑一遍就能在新机器上复现环境比口头跟同事说你先装这个再装那个高效太多。脚本里加上set -e任何一步失败就停住避免错误累积到最后才发现。这套东西我在三台不同配置的 UOS 机器上跑过除了个别包名需要微调整体非常省事。
