独立Qt项目运行时找不到XCB平台插件的解决求助

我正尝试用CMake构建Qt项目，但有以下严格要求：

• 软件及所有依赖通过解压单个zip包即可完成任意位置安装
• 不得依赖预安装的系统库
• 禁止修改/usr/local和/usr目录
• 所有依赖均从源码构建
• 必须使用动态链接

目前已编写脚本构建Qt、libxcb和xcb-proto，但运行程序时出现错误：

qt.qpa.plugin: Could not find the Qt platform plugin "xcb" in ""
This application failed to start because no Qt platform plugin could be initialized.  Reinstalling the application may fix this problem.

已知这是Qt运行时配置问题，无法通过target_link_libraries解决，尝试过在应用目录放置qt.conf但无效。当前CMake脚本如下：

cmake_minimum_required(VERSION 3.22)
project("My Project")

include(ExternalProject)
include(FetchContent)

# xcb-proto
set(EXTERNALPROJECT_XCB_PROTO_INSTALL ${CMAKE_CURRENT_BINARY_DIR}/xcb-proto-build)
ExternalProject_Add(
    xcb-proto
    URL "${CMAKE_CURRENT_SOURCE_DIR}/external/xcb_proto/xcb-proto-1.14.tar.gz"
    INSTALL_DIR "${EXTERNALPROJECT_XCB_PROTO_INSTALL}"
    CONFIGURE_COMMAND "<SOURCE_DIR>/configure --prefix ${EXTERNALPROJECT_XCB_PROTO_INSTALL}"
    BUILD_COMMAND make -j ${CMAKE_BUILD_PARALLEL_LEVEL}
    INSTALL_COMMAND make install
)
ExternalProject_Get_Property(xcb-proto INSTALL_DIR)
set(EXTERNAL_PROJECT_XCB_PROTO_PKGCONFIG_DIR ${INSTALL_DIR}/lib/pkgconfig) #Required for libxcb to find.

#libxcb
set(EXTERNALPROJECT_XCB_INSTALL ${CMAKE_CURRENT_BINARY_DIR}/xcb-build)
ExternalProject_Add(
    xcb
    URL "${CMAKE_CURRENT_SOURCE_DIR}/external/xcb/libxcb-1.14.tar.gz"
    INSTALL_DIR "${EXTERNALPROJECT_XCB_INSTALL}"
    CONFIGURE_COMMAND "<SOURCE_DIR>/configure 
        --prefix ${EXTERNALPROJECT_XCB_INSTALL}"
        --enable-shared
        --disable-static
        --disable-devel-docs
        --enable-randr
        --enable-rendr
        --enable-shape
        --enable-shm
        --enable-sync
        --enable-xfixes
        --enable-xkb
    BUILD_COMMAND make -j ${CMAKE_BUILD_PARALLEL_LEVEL}
    INSTALL_COMMAND make install
    DEPENDS xcb-proto
)

#qt
FetchContent_Declare(qt
    URL "${CMAKE_CURRENT_SOURCE_DIR}/external/qt/qt-base-src-6.9.1.tar.gz"
    FIND_PACKAGE_ARGS COMPONENTS Widgets
)
FetchContent_MakeAvailable(qt)

# add_executable and link qt targets as normal

接下来计划研究QLibraryInfo，尝试注入XCB的正确路径。

1. 构建Qt时指定依赖的xcb库路径 #

问题根源之一是Qt构建时没有使用你编译的libxcb，而是默认查找系统库。需要在Qt的构建配置中明确传递本地依赖路径：

FetchContent_Declare(qt
    URL "${CMAKE_CURRENT_SOURCE_DIR}/external/qt/qt-base-src-6.9.1.tar.gz"
    FIND_PACKAGE_ARGS COMPONENTS Widgets
    CMAKE_ARGS
        -DCMAKE_PREFIX_PATH=${EXTERNALPROJECT_XCB_INSTALL};${EXTERNALPROJECT_XCB_PROTO_INSTALL}
        -DXCB_INCLUDE_DIR=${EXTERNALPROJECT_XCB_INSTALL}/include
        -DXCB_LIBRARY=${EXTERNALPROJECT_XCB_INSTALL}/lib/libxcb.so
        -DQT_BUILD_EXAMPLES=OFF
        -DQT_BUILD_TESTS=OFF
        -DCMAKE_INSTALL_PREFIX=${CMAKE_CURRENT_BINARY_DIR}/qt-install # 指定Qt安装到本地目录
)

这样Qt会优先使用你编译的xcb库，确保生成的插件和依赖路径与本地构建环境匹配。

2. 正确配置qt.conf文件 #

之前的qt.conf无效大概率是路径配置错误。针对单zip部署需求，必须使用相对路径，确保解压到任意位置都能生效。

假设最终zip包结构如下：

my-app/
├── bin/
│   └── MyProject # 可执行文件
├── lib/
│   ├── libxcb*.so # xcb相关库
│   └── Qt6/ # Qt库文件目录
└── plugins/
    └── platforms/ # Qt平台插件（如libqxcb.so）

在bin目录下创建qt.conf，内容如下：

[Paths]
Prefix=..
Libs=lib/Qt6
Plugins=plugins

Qt会以可执行文件的位置为基准，通过相对路径找到库和插件目录。

3. 确保运行时能找到动态库 #

系统默认不会查找本地构建的库路径，可通过以下两种方式解决：

• 设置rpath：在CMake中为可执行文件添加相对rpath，让程序启动时自动查找依赖：

add_executable(MyProject main.cpp)
target_link_libraries(MyProject PRIVATE Qt6::Widgets)

# 设置rpath为相对路径，适配zip包结构
set_target_properties(MyProject PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
    BUILD_WITH_INSTALL_RPATH ON
)

$ORIGIN代表可执行文件所在目录，$ORIGIN/../lib会指向zip包中的lib目录。

• 编写启动脚本：如果rpath不适用，可写一个shell脚本设置LD_LIBRARY_PATH后启动程序：

#!/bin/bash
DIR=$(dirname "$(readlink -f "$0")")
export LD_LIBRARY_PATH="$DIR/../lib:$LD_LIBRARY_PATH"
exec "$DIR/MyProject" "$@"

将脚本放在bin目录下，用户运行脚本即可启动程序。

4. 用QLibraryInfo手动注入路径（备选） #

如果上述方法仍有问题，可在程序启动时通过代码指定插件路径：

#include <QLibraryInfo>
#include <QCoreApplication>

int main(int argc, char *argv[])
{
    // 以相对路径设置Qt插件目录
    QString pluginPath = QCoreApplication::applicationDirPath() + "/../plugins";
    QCoreApplication::setAttribute(Qt::AA_PluginApplication);
    QLibraryInfo::setLibraryPath(pluginPath);

    QApplication app(argc, argv);
    // ... 程序逻辑
    return app.exec();
}

这种方式直接在代码中配置，无需依赖外部文件。

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