Raspbian Lite运行交叉编译Qt GUI程序报错，如何无桌面运行Qt窗口程序？

在树莓派的Raspbian Lite（无桌面环境）下运行交叉编译的Qt图片显示程序时，出现如下报错：

pi@raspberrypi:~ $ ./qtGui
qt.qpa.xcb: could not connect to display :0.0
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. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.

Aborted

已知报错原因是系统无桌面环境，但需了解如何在此环境下运行Qt窗口类程序（如主窗口、QML应用）。以下是程序代码及构建配置：

主程序代码（main.cpp） #

#include <QApplication>
#include <QLabel>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    QImage myImage;
    myImage.load("/home/ulas/test.jpg");

    QLabel myLabel;
    myLabel.setPixmap(QPixmap::fromImage(myImage));

    myLabel.show();

    return a.exec();
}

CMakeLists.txt配置 #

cmake_minimum_required(VERSION 3.5)

project(qtGui LANGUAGES CXX)
message("CMAKE_SYSROOT " ${CMAKE_SYSROOT})
message("CMAKE_LIBRARY_ARCHITECTURE " ${CMAKE_LIBRARY_ARCHITECTURE})
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)

set(CMAKE_C_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -Wl,-rpath-link, ${CMAKE_SYSROOT}/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE} -L${CMAKE_SYSROOT}/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE}")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -Wl,-rpath-link,${CMAKE_SYSROOT}/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE} -L${CMAKE_SYSROOT}/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE}")

# include_directories(/home/julian/qt6rpi/include/)

add_executable(qtGui main.cpp)

target_link_libraries(qtGui Qt6::Core Qt6::Gui Qt6::Widgets)

解决方案 #

报错核心是Qt默认尝试使用依赖X11桌面的xcb平台插件，但无桌面环境下没有X11服务，因此需要改用Qt提供的嵌入式无桌面平台插件。常用选项为eglfs（支持硬件加速）和linuxfb（基于帧缓冲）。

1. 运行时临时指定平台插件 #

直接在启动程序时通过环境变量指定平台，无需修改代码或构建配置：

# 使用eglfs（推荐，利用树莓派GPU硬件加速）
QT_QPA_PLATFORM=eglfs ./qtGui

# 或使用linuxfb（基于系统帧缓冲，无硬件加速）
QT_QPA_PLATFORM=linuxfb ./qtGui

2. 编译时默认指定平台插件 #

如果希望程序启动时自动使用指定平台，可在CMakeLists.txt中添加编译定义，将平台插件设置为默认项：
在target_link_libraries之前添加以下代码：

# 设置默认平台为eglfs
target_compile_definitions(qtGui PRIVATE QT_QPA_DEFAULT_PLATFORM="eglfs")

重新编译程序后，直接运行./qtGui即可，无需额外环境变量。

注意事项 #

• 从报错信息看，你的Qt交叉编译包已包含eglfs和linuxfb插件，无需额外编译插件
• 使用eglfs时，确保树莓派的硬件加速已启用（Raspbian Lite默认开启）
• 若使用linuxfb，可能需要调整程序窗口大小以适配屏幕分辨率，或修改帧缓冲配置

内容的提问来源于stack exchange，提问作者Julian