Linux系统解决Qt platform plugin "xcb"缺失问题

当 Qt 报告“已找到 xcb 插件，但无法加载”，可能是插件依赖缺失、Qt 库混用，也可能是无法连接显示服务器。下面以 Debian/Ubuntu 上的诊断流程为例。

1. 读取插件加载日志

QT_DEBUG_PLUGINS=1 python app.py

该变量在程序运行、加载插件时生效，不是编译器选项。对 C++ 程序，将 python app.py 换成对应可执行文件。日志会显示实际选择的 libqxcb.so 路径及失败原因。

2. 检查缺失的依赖

将日志中的真实插件路径代入；只对可信的本地二进制运行：

ldd /path/to/platforms/libqxcb.so

如果明确缺少 libxcb-xinerama.so.0，检查并安装发行版对应包：

apt-cache policy libxcb-xinerama0
sudo apt-get install libxcb-xinerama0

其他缺失库应按日志逐项定位，包名随发行版与 Qt 版本变化。

3. 不要用软链接掩盖 ABI 不匹配

libxcb-util.so.0 与 libxcb-util.so.1 的 SONAME 不同。把旧文件软链接成新名称不能保证 ABI 兼容，可能把加载错误变成运行时崩溃。应安装对应运行时，或使用针对本机依赖构建的 Qt 包。

4. 检查显示连接

printenv DISPLAY WAYLAND_DISPLAY XDG_SESSION_TYPE

“could not connect to display”应检查实际桌面会话、SSH 转发与访问权限。手工设置 DISPLAY=:0 不会创建显示服务器，也不会自动授予访问权限。

仅做无窗口测试时，可以尝试 QT_QPA_PLATFORM=offscreen，但它不保证支持应用所需的 OpenGL 上下文。

完成后恢复常规启动方式，验证窗口、输入事件和程序退出。参考 Qt 插件部署文档。

阅读自测与验收

• 使用 QT_DEBUG_PLUGINS 记录实际插件路径，再对该二进制执行依赖检查；不要对系统中另一份同名插件下结论。
• 在匹配的解释器、架构和显示会话中验证最小窗口；伪造 soname 链接可能绕过报错，却留下 ABI 风险。