Linux下Qt显示环境变量配置与常见报错排查指南

你是不是也遇到过这种情况:在 Linux 上辛苦编译完一个 Qt 程序,双击或命令行一跑,窗口没弹出来,终端里却甩出一堆qt.qpa.plugin: could not find the qt platform plugin linuxfb或者cannot mix incompatible qt library (version ex50601) with this library之类的报错,然后程序直接退出。这种问题十有八九不是代码逻辑写错了,而是显示环境变量没配对。我最早被这个问题折磨的时候,也以为是 Qt 版本装错了,后来才明白,Linux 下 Qt 的显示环境变量设置,直接影响程序能不能找到正确的图形平台插件,以及能不能在对应的显示服务器上把窗口画出来。今天这篇就围绕这块,把我这几年排查 Qt 显示环境变量的经验完整梳理一遍。1. 为什么Qt一跑就崩:显示环境变量到底管着什么要理解环境变量为什么这么重要,得先知道 Qt 的图形界面底层是怎么工作的。Qt 本身没有直接去调用显卡驱动或写 framebuffer,而是通过一套叫做 QPA(Qt Platform Abstraction)的抽象层来和不同的图形系统打交道。你写的 QWidget 或 QML 窗口,最后都是交给某个“平台插件”去真正显示出来的。而 Qt 在启动时根据哪个环境变量选择插件呢?就是QT_QPA_PLATFORM。如果这个变量没有设对,或者指向的插件找不到,程序自然起不来。最常见的几个平台插件有:xcb:对应 X Window System,是传统 Linux 桌面的标准显示服务器,X11 之下基本都用它。wayland:对应 Wayland 显示协议,现在很多新发行版(如 Fedora、Ubuntu 22.04 的默认会话)走的就是 Wayland。linuxfb:直接操作 Linux 的 framebuffer 设备(比如/dev/fb0),不需要 X11/Wayland,常用于嵌入式设备或开发板。eglfs:基于 OpenGL ES 的全屏渲染插件,适合嵌入式环境且需要 GPU 加速的场景。offscreen / minimal:不真正显示窗口,用于单元测试、QSS 截图或 headless 环境。Qt 启动时,会按照这个优先级决定加载哪个插件:首先看QT_QPA_PLATFORM环境变量,然后看代码里是否用QApplication::setPlatformName显式指定,最后才是编译时配置的默认值。所以,当你在一个没有 X 服务的嵌入式板子上运行程序,而QT_QPA_PLATFORM还默认是xcb时,它自然找不到 XCB 插件,于是报错。反过来,在普通桌面环境下你强行设成linuxfb,可能又会因为无法打开/dev/fb0或缺少相应平台插件而崩溃。有人会问:环境变量不就是export一下吗,有什么好讲的?其实坑就藏在细节里。DISPLAY、WAYLAND_DISPLAY、XDG_RUNTIME_DIR、QT_QPA_PLATFORM_PLUGIN_PATH、QT_QPA_FB_DRM这些变量,组合在一起才构成一套完整的显示链路。任何一个变量缺失或值不对,都可能让 Qt 程序打不开窗口。下面我会按两种最常见的场景——桌面环境和嵌入式环境——分别拆解。2. 桌面环境下的显示变量配置与排查2.1 DISPLAY和xcb:传统X11下的基础配置在 X11 环境下,DISPLAY变量告诉客户端程序要连接哪个 X server。它的格式一般是hostname:display_number.screen_number,本地图形界面通常就是:0或:0.0。如果你在 Linux 桌面终端里运行echo $DISPLAY,大概率会看到:0或:1。Qt 的 xcb 插件自身不会解析 DISPLAY,但底层的 XCB 库会依赖它,因此这个变量必须正确设置,否则连连接服务器都做不到。很多远程场景下,DISPLAY 的坑最容易踩。比如通过 SSH 登录一台 Linux 服务器,想跑一个 Qt 程序把窗口显示回本地,光有 DISPLAY 还不够,还需要在 SSH 连接时开启 X11 转发(通常加-X或-Y参数),同时本地要有 X server 在运行。这时候 SSH 服务端会自动帮你设置一个临时 DISPLAY,如localhost:10.0。如果你手动覆盖成:0,反而连不上,因为那是服务器本地的 X server,你根本没有权限访问。我的习惯是:不需要手动改 DISPLAY,除非你知道自己在干什么;如果确实需要指定,用export DISPLAY:0.0这种格式,这比冒号后只写一个数字更严谨。对于普通桌面环境,QT_QPA_PLATFORM不设置也能跑,Qt 会自动探测。但如果你设置了它,值必须和你实际使用的图形系统匹配。在 X11 会话下用xcb,在 Wayland 会话下用wayland或xwayland。有一个比较省心的做法是,写一个启动脚本,检测当前会话类型再决定导出哪个平台:if [ $XDG_SESSION_TYPE wayland ]; then export QT_QPA_PLATFORMwayland else export QT_QPA_PLATFORMxcb fi但这只是基础。真正让很多人困惑的是插件路径问题。Qt 安装后会有一个plugins/platforms/目录,里面放着libqxcb.so、libqwayland.so、libqlinuxfb.so等插件。如果QT_QPA_PLATFORM_PLUGIN_PATH指到了错误的位置,Qt 就会在默认路径里找不到插件,于是出现开头说的could not find the qt platform plugin xcb之类报错。检查方法很简单:确认你安装的 Qt 版本对应的插件目录,比如/opt/Qt/5.15.2/gcc_64/plugins/platforms,然后ls看是否包含libqxcb.so。如果是用系统包管理器安装的 Qt,路径通常在/usr/lib/x86_64-linux-gnu/qt5/plugins/platforms/。遇到插件缺失,优先从这两个方向查。2.2 Wayland会话下的特殊变量接下来是 Wayland。从 Ubuntu 22.04 开始,很多发行版默认登录会话已经切到 Wayland 了。Qt 程序跑在 Wayland 下,需要加载wayland插件,并且它依赖一组环境变量:XDG_RUNTIME_DIR和WAYLAND_DISPLAY。XDG_RUNTIME_DIR通常指向/run/user/uid,里面放着 Wayland socket。如果你通过su切换用户,或者用某些服务管理工具启动程序时没有正确继承这些变量,Qt 就会提示找不到 Wayland 平台。Wayland 下另一个常见问题是 Qt 版本与 Wayland 协议不匹配。比如系统是 Qt 5.12,而你程序链接的是 Qt 5.15,可能就会因为协议版本不一致导致窗口运行时崩溃或功能异常。我在实际项目里常用的检查命令是这样的:printenv | grep -E XDG_RUNTIME_DIR|WAYLAND_DISPLAY|DISPLAY|QT_QPA如果没有输出XDG_RUNTIME_DIR,可以手动指定:export XDG_RUNTIME_DIR/run/user/$(id -u)另外,有些 Qt 程序为了兼容性和稳定性,会强制指定QT_QPA_PLATFORMxcb,即使当前是 Wayland 会话,它也会通过 XWayland 运行。这种方式能避免部分 Wayland 下的字体渲染和窗口缩放问题,代价是失去 Wayland 原生的优点。如果你的程序在 Wayland 下显示模糊或 DPI 不对,试试用xcb跑,通常很快能定位是不是 Wayland 合成器的兼容问题。2.3 环境变量持久化和systemd场景调试时用export设置变量,只能在当前终端生效。真正上线部署时,你需要把变量写到持久化配置文件里。有两个选择:一是写到用户的~/.bashrc或~/.profile,这适合手动运行程序的场景;二是写到/etc/environment,这是系统级的环境变量配置,所有用户和图形会话都会读取。需要注意的是,/etc/environment里不支持变量展开,你不能写QT_QPA_PLATFORM_PLUGIN_PATH$HOME/Qt/plugins,必须写绝对路径。如果你把 Qt 程序做成 systemd service,那就更要注意了。systemd 默认不会继承图形会话的环境变量,你需要用Environment或EnvironmentFile显式声明。一个常见的错误是:在终端里跑没问题,一做成开机自启就黑屏或崩溃,原因就是 DISPLAY 没传给 service。对于一个面向 X11 的 systemd service,我通常会在 unit 文件里加这些:[Service] EnvironmentDISPLAY:0 EnvironmentQT_QPA_PLATFORMxcb EnvironmentXAUTHORITY/home/yourname/.Xauthority注意XAUTHORITY也很关键,很多程序明明 DISPLAY 对了,却因为拿不到 X server 的授权而在 connect 时报Authorization required错误。在开机自启场景下,建议把XAUTHORITY指到实际登录用户的.Xauthority文件,否则 Qt 程序没有权限连上 X server。2.4 查看插件加载过程的调试手段环境变量设置好后,程序依然起不来怎么办?别急着猜,先开 Qt 的插件调试输出:export QT_DEBUG_PLUGINS1 ./your_app运行后你会看到一堆日志,类似:QFactoryLoader::QFactoryLoader() checking directory path /opt/Qt/5.15.2/gcc_64/plugins/platforms ... Found metadata in lib /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so这些日志会明确指出 Qt 在哪些目录里找过插件,以及为什么某个插件被拒绝(通常是因为 Qt 版本不匹配或依赖库缺失)。日志里如果出现Cannot load library后面还跟着ld错误,那就说明插件本身的动态链接有问题,比如缺少libxcb-cursor0等系统库。这时候用ldd检查插件依赖是下一步要做的事。这个习惯帮我省下了大量定位时间——很多时候不是环境变量的问题,而是系统库版本不对,导致插件加载失败。3. 嵌入式Linux和linuxfb平台插件全解析3.1 linuxfb与eglfs的应用场景到了嵌入式 Linux,情况就完全不一样了。没有 X server,也没有 Wayland,Qt 程序要直接写/dev/fb0或通过 DRM/KMS 显示。最常用的两个平台插件是linuxfb和eglfs。linuxfb不依赖 GPU,直接把 framebuffer 内存映射到用户空间,然后往里面画点;eglfs则需要 OpenGL ES 和 DRM 支持,适合带 GPU 的板子,渲染效率高很多。它们的共同特点是:不需要DISPLAY环境变量,而是需要QT_QPA_PLATFORM明确指定。很多做嵌入式开发的朋友,把宿主机上编好的 Qt 程序拷贝到板子上跑,结果报:qt.qpa.plugin: could not find the qt platform plugin linuxfb in 这个报错我见过太多次了。原因有两个:一是你编译时根本没把linuxfb插件编进 Qt,或者编进去了但插件目录没一并拷贝到板子;二是QT_QPA_PLATFORM_PLUGIN_PATH没有指向板子上存放插件的位置。如果程序用绝对路径加载 Qt 动态库,而插件又在可执行文件旁边,可以这样启动:export QT_QPA_PLATFORMlinuxfb export QT_QPA_PLATFORM_PLUGIN_PATH/opt/app/plugins ./your_app这里QT_QPA_PLATFORM_PLUGIN_PATH帮助 Qt 快速找到插件目录,省去默认路径搜索过程。如果插件目录就是 Qt 安装目录的plugins,那可以把整个plugins/platforms目录拷过去,并保证路径一致。还有一点容易被忽略:插件不仅要找到,还要能加载成功。如果插件依赖的 Qt 库和你程序链接的 Qt 库版本不一致,或者缺少某些 libstdc 符号,插件一样加载失败。用ldd libqlinuxfb.so检查一下依赖,能避免很多“找不到平台插件”的误判。3.2 framebuffer设备与环境变量联动linuxfb插件运行时会默认打开/dev/fb0作为显示设备。如果你的板子有多个显示接口,需要指定具体用哪个 framebuffer,可以通过设置QT_QPA_FB_DRM或用linuxfb:/dev/fb1这种带参数的形式:export QT_QPA_PLATFORMlinuxfb:/dev/fb1另外,linuxfb插件初始化时读取一些屏幕参数,比如分辨率、色深,如果/dev/fb0的驱动没设置好,可能会出现屏幕显示偏移或颜色不对。这时用fbset或cat /sys/class/graphics/fb0/virtual_size查看实际参数。有些板子的 framebuffer 默认分辨率是 800x600,程序如果按照 1920x1080 去画,内容会被裁剪,所以最好在程序里显式setGeometry或者用QT_QPA_FB_DRM配合 DRM 后端来获取真实分辨率。还有一种情况:你的板子根本没有/dev/fb0节点,或者权限不够。检查方式是:ls -l /dev/fb*如果节点存在但没有读权限,用chmod 666 /dev/fb0或把运行用户加到video组。有些文件系统会动态创建设备节点,如果缺少/dev/fb0,大概率是内核配置里的CONFIG_FB没开或者驱动没加载。这种时候linuxfb无论如何都起不来,需要考虑改用eglfs或者直接修内核配置。3.3 交叉编译场景下的路径陷阱树莓派或其他 ARM 板子上跑 Qt,通常要交叉编译。交叉编译时的环境变量坑,和本机编译完全不同。一个典型错误是:在 x86 主机上把程序、插件、Qt 库都编好了,拷贝到 ARM 板子后,启动时找到插件了,却报cannot mix incompatible qt library。这个报错我后面会详细讲,这里先提醒一个关键点:交叉编译时必须保证主机的 Qt 工具链和板子上跑的 Qt 库版本完全一致,包括补丁号。我建议在板子本地编译 Qt 或者使用厂商提供的完整 SDK,而不是只拷贝几个 so 文件,因为 Qt 库之间可能存在运行时依赖路径问题。交叉编译环境里设置QT_QPA_PLATFORM_PLUGIN_PATH时,要写板子上的绝对路径,不能沿用主机的路径。比如你交叉编译时 Qt 安装到了/opt/qt-arm,但板子上实际部署在/usr/local/qt,那启动脚本里的路径必须改成后者。别小看这个细节,我做项目时多次发现,调试时明明echo出来的变量都正常,程序却依然找不到插件,最后就是路径写死在了编译参数里。如果用的是 CMake,可以这样检查最终的可执行文里写入了哪些 rpath:readelf -d your_app | grep -i rpath如果有硬编码的 rpath 指向了不存在的目录,Qt 会优先去那里找插件,找不到再退回标准路径搜索,这也会拖慢启动甚至误导排查。我的做法是启动脚本里统一export LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH,避免依赖编译时的默认路径。4. 版本兼容问题:从cannot mix incompatible qt library说起4.1 解密报错中的版本号另一类高频报错,是在终端里运行 Qt 程序时直接蹦出一句:fatal: cannot mix incompatible qt library (version ex50601) with this library这句话说的是:程序加载了一个 Qt 库,版本为ex50601(这是 Qt 5.6.1 的版本标记),而当前正在使用的另一个 Qt 库版本和它不兼容,两者不能混用。ex50601这种编码规则很好认:e表示这是 Qt 5(qt的导出前缀),x可能表示某个特性,后两位01表示源码版本号。如果看到ex50710,那就是 5.7.1;ex50900就是 5.9.0。出现这个报错的根本原因,通常不是你的程序有问题,而是它同时加载了两套不同版本的 Qt 动态库。比如系统里有/usr/lib/x86_64-linux-gnu/libQt5Core.so.5这个 symlink,指向 5.15.2,而你的程序又在LD_LIBRARY_PATH指向的另一个目录里找到了 Qt 5.6.1 的库。Qt 内部一旦检测到两个库的版本不一致,就会为了安全起见直接拒绝运行,免得内存布局和函数 ABI 不匹配导致崩溃。4.2 定位混用源的三种方法解决和排查这类问题,我有三个比较实用的手段。第一个是看链接顺序:ldd your_app | grep Qt5Core如果输出显示libQt5Core.so.5 /some/path/libQt5Core.so.5,但你的程序实际编译时用的不是这个路径,那么问题就出现在运行时动态链接上。这时可以:export LD_LIBRARY_PATH/opt/Qt/5.15.2/gcc_64/lib让程序优先加载正确的 Qt 版本。不过要注意,LD_LIBRARY_PATH优先级比系统默认路径高,但低于 DT_RPATH(如果编译时设了)。如果修改后依然加载旧版库,再检查一下程序的 rpath:readelf -d your_app | grep -i path第二,查启动时到底加载了哪个 Qt 库,可以用:LD_DEBUGlibs ./your_app 21 | grep -i qt5core这个能输出动态链接器实际解析到的每个库路径,比 ldd 更精确,因为它考虑了 LD_LIBRARY_PATH 和 rpath 的最终效果。我之前遇到一个奇葩问题:ldd看到的路径是新的,但程序跑起来后却加载了旧库,最后发现是启动脚本里里面有source一个setup.sh,这个脚本把LD_LIBRARY_PATH覆盖了。用LD_DEBUG一下就定位到了。第三,也是最容易忽略的:程序使用了 Qt 插件,插件里嵌入的 Qt 版本和主程序不一致。举个例子,你的程序链接的是 Qt 5.15,但platforms/目录下的libqxcb.so是从旧版本拷贝过来的,那么 Qt 加载插件时依然会报 incompatibility。所以不仅要检查主程序的链接,还要检查插件文件自身的链接:ldd /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep Qt5Core如果插件指向的系统 Qt 路径和程序用的不一致,优先统一。4.3 多版本Qt共存的管理思路为什么会出现这种混用?因为很多开发机上不止一套 Qt。系统自带的 Qt(比如/usr/lib/qt5)是一套,你自己装到/opt的 Qt 是一套,Qt Creator 里 Kit 选的又是一套。如果 CMake 或 qmake 生成的 Makefile 里写死了某个版本的路径,但运行时又被环境变量干扰,就会发生混用。管理多版本 Qt 的最好办法,是每个项目都独立设置环境,不要全局改LD_LIBRARY_PATH。我自己的习惯是给每个 Qt 版本写一个环境配置文件,比如qt-5.15.sh,内容如下:export QT_BASE/opt/Qt/5.15.2/gcc_64 export PATH$QT_BASE/bin:$PATH export LD_LIBRARY_PATH$QT_BASE/lib:$LD_LIBRARY_PATH export QT_QPA_PLATFORM_PLUGIN_PATH$QT_BASE/plugins export PKG_CONFIG_PATH$QT_BASE/lib/pkgconfig:$PKG_CONFIG_PATH使用时source qt-5.15.sh,退出项目就 unset 或者新开终端。这种模式能保证编译、运行、插件三方都指向同一套库,从源头消灭 incompatible 问题。如果你用的是 CMake,还可以在 CMakeLists 里显式指定 Qt 路径:set(CMAKE_PREFIX_PATH /opt/Qt/5.15.2/gcc_64) find_package(Qt5 COMPONENTS Core Gui Widgets REQUIRED)但请记住:CMAKE_PREFIX_PATH 只影响编译期,runtime 还是要靠启动脚本维护LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH。5. 从报错到定位:一套可直接照抄的排查流程5.1 观察报错类型,缩小范围遇到 Qt 启动失败,先看报错关键词。如果是could not find the qt platform plugin,问题聚焦在插件搜索路径或插件不存在;如果是cannot mix incompatible qt library,问题聚焦在 Qt 库版本冲突;如果是Failed to create vertex shader或EGL Error,问题多半在图形驱动;如果是QXcbConnection: Could not connect to display,则和DISPLAY未设置或 X server 访问权限有关。我在项目里会把这类报错做成分类表,团队新同事排查时直接按图索骥。这里给一个我实测有效的排查顺序:先看终端输出的第一条报错,而不是后面的崩溃信息。Qt 通常会在启动早期打印最关键的错误,后面的 segfault 往往只是连锁反应。echo $DISPLAY和echo $QT_QPA_PLATFORM,确认预期。如果是嵌入式板子,确认/dev/fb0存在。开QT_DEBUG_PLUGINS1,观察 Qt 搜索插件的路径是否符合预期,是否因为权限或库依赖而拒绝加载某个插件。如果报cannot mix incompatible,用ldd和readelf检查所有 Qt 相关 so 的路径是否统一。确认当前运行环境的会话类型:echo $XDG_SESSION_TYPE,若是wayland,检查XDG_RUNTIME_DIR和WAYLAND_DISPLAY。如果程序中用到了自定义平台插件或窗口系统集成,确认所以插件编译时的 Qt 版本和运行时一致。5.2 常用命令速查与实战示例我挑几个最高频的命令,配合注释整理出来。# 查看关键环境变量 printenv | grep -E QPA|DISPLAY|WAYLAND|XDG|LD_LIBRARY_PATH # 查看 Qt 实际使用的平台插件搜索路径 QT_DEBUG_PLUGINS1 ./your_app 21 | grep checking directory # 查看动态库链接关系 ldd ./your_app | grep -E Qt5|qt # 查看可执行文件的 RPath readelf -d ./your_app | grep -E RPATH|RUNPATH # 查看某个插件依赖的 Qt 版本 strings /path/to/plugins/platforms/libqxcb.so | grep Qt 5 # 手动指定 framebuffer 设备启动 QT_QPA_PLATFORMlinuxfb:/dev/fb1 ./your_app这里有个小技巧:如果程序在桌面环境下一直报xcb插件加载失败,但你又不想花时间查依赖,可以直接用QT_QPA_PLATFORMoffscreen跑一下。如果程序能启动并做后台逻辑,至少能验证逻辑部分没问题,把问题隔离到显示链条上。不过这只是权宜之计,不能替代真正的排查。5.3 一个典型问题的完整复盘有一次,我在一块 ARM 板子上部署 Qt 应用,启动报could not find the qt platform plugin linuxfb,但ls板子的/usr/local/qt/plugins/platforms/明明有libqlinuxfb.so。我花了十分钟检查路径,发现程序是从/opt/app启动的,启动脚本里设置了QT_QPA_PLATFORM_PLUGIN_PATH/opt/app/plugins,但插件实际却部署在了/usr/local/qt/plugins。也就是说,Qt 只去脚本指定的那个目录里找,找不到就直接放弃,不会自动去/usr/local/qt/plugins找。这是QT_QPA_PLATFORM_PLUGIN_PATH的一个隐藏特性:一旦你手动设置了它,它就会覆盖 Qt 的默认搜索路径,而不是追加。所以如果你手动设置了该变量,必须确保它包含所有需要的插件目录,或者干脆不设置,让 Qt 按默认路径搜。那次之后,我把启动脚本改成:export QT_QPA_PLATFORMlinuxfb export QT_QPA_PLATFORM_PLUGIN_PATH/usr/local/qt/plugins程序立刻正常。这个坑在官方文档里写了,但很多人不注意:这个变量是“替代”而非“追加”。另外还有一次,程序报cannot mix incompatible qt library (version ex50601)但 ldd 里又看不出问题,后来发现是程序里用dlopen手动加载了一个 Qt 插件,那个插件本身链接的是旧版 Qt。这种隐式加载最难查,只能逐个dlopen可疑模块,或者把程序用LD_DEBUG跑起来看加载顺序。如果你遇到了类似情况,可以把所有可疑插件都放到同一个目录,确保它们链接的 Qt 版本一致,就没有这个烦恼了。6. 常见报错与解决方案速查表为了便于以后查阅,我把工作中最常碰到的 Qt 显示环境变量问题整理成一张表,每一个都对应具体的解决动作。报错或现象可能原因解决动作could not find the qt platform plugin xcb缺少 xcb 插件,或插件路径没找到安装libxcb-cursor0等依赖;确认QT_QPA_PLATFORM_PLUGIN_PATH指向正确的plugins/platforms目录could not find the qt platform plugin linuxfbin linuxfb 插件未编译,或路径不对/被覆盖重新编译 Qt 时包含 linuxfb;检查启动脚本是否把QT_QPA_PLATFORM_PLUGIN_PATH写成了不存在的路径cannot mix incompatible qt library (version ex50601) with this library同一进程加载了两套不同版本 Qt 库统一LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH,确保所有 Qt so 和插件同源QXcbConnection: Could not connect to display :0DISPLAY 未设置,或 X server 权限不足export DISPLAY:0;检查XAUTHORITY;远程场景开启 SSH X11 转发qt.qpa.plugin: Could not load the Qt platform plugin waylandWayland 插件依赖缺失,或XDG_RUNTIME_DIR不对设置XDG_RUNTIME_DIR/run/user/$(id -u);安装qtwayland包程序启动闪退,调试日志显示QXcbConnection: Failed to initialize XCBxcb 插件依赖的 X11 库缺失或冲突用ldd libqxcb.so检查缺失 so,安装对应库在嵌入式板子上窗口显示偏移或颜色不对framebuffer 设备的分辨率/色深与插件设置不匹配用fbset -s查看/dev/fb0参数,或通过QT_QPA_PLATFORMlinuxfb:/dev/fb1切换设备程序在 systemd service 下跑不起来service 没继承图形会话环境变量在 unit 文件里添加EnvironmentDISPLAY:0、QT_QPA_PLATFORMxcb、XAUTHORITY...Qt 程序在 Wayland 下 DPI 异常、图标缩放不正确Qt 检测到的屏幕缩放因子不对export QT_ENABLE_HIGHDPI_SCALING1,或者改用QT_QPA_PLATFORMxcb在 XWayland 下运行FATAL: cannot mix incompatible qt library发生在dlopen手动加载插件时插件链接的 Qt 版本和主程序不同统一插件编译时使用的 Qt SDK,不要在运行时混装多个 Qt 版本qt.qpa.plugin: Could not find the Qt platform plugin eglfseglfs 插件未部署,或图形驱动未初始化确认插件文件已拷贝;用eglinfo检查 EGL 支持;确保/dev/dri/*权限可用这张表并不能覆盖所有场景,但它至少可以帮你把脑子里“一堆环境变量绕不清”的状态,收敛成几个明确的操作项。在多数实际项目里,解决这类问题花的时间通常不超过半小时,大部分时间都浪费在试错而不是观察报错上。我个人在走完这些排查流程后的体会是:Linux 下 Qt 的显示环境变量,说到底是“路径”和“版本”两个字。路径对了,插件能找到;版本对了,ABI 能配上。只要牢牢抓住这两个核心,桌面 X11/Wayland 和嵌入式 linuxfb/eglfs 的种种报错,都能顺着线索一步步查到底。上面这套方法,我每次换开发板、换新系统、或者帮同事看诡异报错时都用得上,今天整理出来,希望能让你少走一些弯路。