QT
树莓派 Qt6 交叉编译与环境搭建指南
注意事项：
- 本文所有指令千万不要直接复制执行，因为用户名及路径可能不同，请根据实际环境替换！
- 若使用 WSL2 进行构建，在
configure阶段需要等待很久，因为 WSL2 的跨盘/虚拟化 I/O 性能相对较差。
前置条件 1：检查 glibc 版本一致性
目标系统的 glibc 版本必须与编译机一致（例如：树莓派系统推荐编译机使用 Debian 12）。版本过高或过低都会导致链接失败。
不可使用第三方工具链（如 ARM 官方工具链），容易缺失特定依赖文件导致编译失败。
可以在目标机与编译机上分别执行以下指令查看 glibc 版本：
ldd --version前置条件 2：在目标系统上安装必要依赖并打包 sysroot
1. 安装编译与运行依赖
sudo apt update
sudo apt install build-essential libgl1-mesa-dev libfontconfig1-dev libdbus-1-dev libssl-dev libudev-dev libinput-dev libts-dev libxcb-xinerama0-dev libxcb-xkb-dev libxkbcommon-x11-dev libxcb-cursor-dev libxcb-util-dev libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev libxcb-render-util0-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev libxcb-sync-dev libxcb-xinput0Linux 桌面组件支持：
sudo apt install \
libfontconfig1-dev \
libfreetype-dev \
libgtk-3-dev \
libx11-dev \
libx11-xcb-dev \
libxcb-cursor-dev \
libxcb-glx0-dev \
libxcb-icccm4-dev \
libxcb-image0-dev \
libxcb-keysyms1-dev \
libxcb-randr0-dev \
libxcb-render-util0-dev \
libxcb-shape0-dev \
libxcb-shm0-dev \
libxcb-sync-dev \
libxcb-util-dev \
libxcb-xfixes0-dev \
libxcb-xkb-dev \
libxcb1-dev \
libxext-dev \
libxfixes-dev \
libxi-dev \
libxkbcommon-dev \
libxkbcommon-x11-dev \
libxrender-dev运行时与基础 XCB 库：
sudo apt install \
libxcb1 libx11-xcb1 libxrender1 libxi6 libxkbcommon0 libxext6 libxfixes3 libxrandr2 libxinerama1 libxcursor1 libxcomposite1 libxdamage1 libx11-dev \
libxkbcommon-dev libfontconfig1 libfreetype6 libpng-dev libglib2.0-0 libdbus-1-3 libdbus-1-dev \
libxcb1-dev libxcb-util1 libxcb-util-dev libxcb-icccm4 libxcb-icccm4-dev libxcb-image0 libxcb-image0-dev libxcb-keysyms1 libxcb-keysyms1-dev \
libxcb-render0 libxcb-render0-dev libxcb-shape0 libxcb-shape0-dev libxcb-shm0 libxcb-shm0-dev libxcb-sync1 libxcb-sync-dev libxcb-xfixes0 libxcb-xfixes0-dev \
libxcb-xinerama0 libxcb-xinerama0-dev libxcb-xkb1 libxcb-xkb-dev libxcb-randr0 libxcb-randr0-dev libxcb-composite0 libxcb-composite0-dev libxcb-damage0 libxcb-damage0-dev补充图形及系统支持库：
sudo apt-get install \
libxcb1-dev libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev \
libxcb-render0-dev libxcb-render-util0-dev libxcb-shape0-dev libxcb-shm0-dev \
libxcb-sync-dev libxcb-xfixes0-dev libxcb-xkb-dev libxcb-randr0-dev \
libxcb-cursor-dev libxcb-glx0-dev libxcb-xinput-dev libx11-dev libx11-xcb-dev \
libxkbcommon-dev libxkbcommon-x11-dev libxrender-dev libxext-dev libsm-dev libice-dev \
libfreetype6-dev libfontconfig1-dev libharfbuzz-dev libjpeg-dev libpng-dev libmd4c-dev \
libgl-dev libegl1-mesa-dev libgles2-mesa-dev libvulkan-dev zlib1g-dev libdrm-dev \
libinput-dev libts-dev libmtdev-dev libatspi2.0-dev libwayland-dev
sudo apt install "libxcb*"
sudo apt install "libxkbcommon*"
sudo apt-get install libmd4c-dev2. 同步与打包 sysroot
mkdir -p ~/sysroot方式一：基础同步指令
sudo rsync -avz --delete \
--exclude='/dev/*' \
--exclude='/proc/*' \
--exclude='/sys/*' \
--exclude='/tmp/*' \
--exclude='/run/*' \
--exclude='/mnt/*' \
--exclude='/media/*' \
--exclude='/home/*' \
--exclude='/lost+found' \
/ ~/sysroot方式二：精简同步指令（排除更多无关目录，加快速度）
sudo rsync -avz --delete \
--exclude='/dev/*' \
--exclude='/proc/*' \
--exclude='/sys/*' \
--exclude='/tmp/*' \
--exclude='/run/*' \
--exclude='/mnt/*' \
--exclude='/media/*' \
--exclude='/home/*' \
--exclude='/lost+found' \
--exclude='/var/lib/docker/*' \
--exclude='/var/run/*' \
--exclude='/var/tmp/*' \
--exclude='/var/cache/*' \
--exclude='/var/lock/*' \
--exclude='/swapfile' \
--exclude='/opt/containerd/*' \
--exclude='/opt/1panel/*' \
--exclude='/opt/pigpio/*' \
--exclude='/opt/Scratch 3/*' \
--exclude='/opt/WidevineCdm/*' \
--exclude='/opt/Wolfram/*' \
/ ~/sysroot打包并拷贝
sudo tar czf sysroot.tar.gz sysroot打包完成后，可通过 U 盘、网络传输或 SCP 拷贝到编译机。
前置条件 3：在编译机解压 sysroot 并安装交叉编译工具
1. 解压 sysroot
推荐解压到用户主目录或根目录下（需要 root 权限）：
- 单线程解压：
sudo tar xzf ~/sysroot.tar.gz -C ~/ - 推荐多线程解压（需安装 pigz）：
sudo tar --use-compress-program=pigz -xvf ~/sysroot.tar.gz
2. 安装交叉编译工具链
此处推荐安装 ninja 构建工具（解决 make 编译报错问题）：
sudo apt update
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu ninja-build libglib2.0-0 libglib2.0-dev libxkbcommon0 libxkbcommon-dev libgl1
sudo apt install -y build-essential cmake ninja-build libgl1 libgl-dev libegl1 libegl-dev libx11-6 libx11-dev libxext6 libxext-dev libxrender1 libxrender-dev libxcb1 libxcb1-dev libxkbcommon0 libxkbcommon-dev libfontconfig1 libfontconfig1-dev libfreetype6 libfreetype6-dev libpng16-16 libpng-dev libjpeg62-turbo libjpeg-dev libinput10 libinput-dev libwayland-client0 libwayland-dev libwayland-egl1 libdrm2 libdrm-dev libgbm1 libgbm-dev libssl-dev zlib1g-dev libsqlite3-dev libicu-dev libdbus-1-3 libdbus-1-dev3. 编译机安装 Qt
使用官方在线安装程序（可搭配南京大学镜像加速）：
./qt-online-installer-linux-x64-4.10.0.run --mirror [https://mirror.nju.edu.cn/qt/](https://mirror.nju.edu.cn/qt/)备注： WSL2 同样支持直接运行 Qt 官方安装器图形界面。
配置交叉编译环境与编译 Qt
1. 创建工具链配置文件
进入安装版本的源码目录（例如 /home/ska/Qt/6.7.3/Src），创建 toolchain.cmake：
set(CMAKE_SYSTEM_NAME Linux) # 目标机器系统
set(CMAKE_SYSTEM_PROCESSOR aarch64) # 目标架构
# 你的 sysroot 绝对路径（建议避免使用 ~ 相对路径）
set(CMAKE_SYSROOT /home/用户名/sysroot)
set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
set(CMAKE_C_COMPILER /usr/bin/aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER /usr/bin/aarch64-linux-gnu-g++)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
set(CMAKE_FIND_LIBRARY_SUFFIXES ".so;.a")将工具链配置文件复制一份至上一层目录：
cp ./toolchain.cmake ..2. 设置环境变量
# Qt 编译安装的目标路径
export INSTALL_PATH=/usr/local/raspi-qt6
# 编译机本地 Host Qt 路径
export QT_HOME=/home/用户名/Qt/6.7.3/gcc_643. 执行 Configure 配置
基础配置（跳过非必要模块与 OpenGL）：
../configure -release \
-platform linux-aarch64-gnu-g++ \
-device linux-aarch64-gnu-gcc \
-qt-host-path $QT_HOME \
-prefix $INSTALL_PATH \
-no-opengl \
-no-openssl \
-skip qtgrpc -skip qtprotobuf -skip qtwebengine -skip qtopcua \
-- -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake带 OpenGL ES2 支持：
../configure -release \
-platform linux-aarch64-gnu-g++ \
-device linux-aarch64-gnu-gcc \
-qt-host-path $QT_HOME \
-prefix $INSTALL_PATH \
-opengl es2 \
-no-openssl \
-skip qtgrpc -skip qtprotobuf -skip qtwebengine -skip qtopcua \
-- -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake带 XCB 支持（推荐完整桌面开发）：
export PKG_CONFIG_LIBDIR=/home/ska/sysroot/usr/lib/aarch64-linux-gnu/pkgconfig
export PKG_CONFIG_SYSROOT_DIR=/home/ska/sysroot
../configure -release \
-platform linux-aarch64-gnu-g++ \
-device linux-aarch64-gnu-gcc \
-qt-host-path $QT_HOME \
-prefix $INSTALL_PATH \
-opengl es2 \
-no-openssl \
-skip qtgrpc -skip qtprotobuf -skip qtwebengine -skip qtopcua \
-xcb \
-- -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
-DQT_FEATURE_system_md4c=OFF \
-DQT_FEATURE_md4c=OFF \
-DXKB_COMMON_X11_LIBRARY=/home/ska/sysroot/usr/lib/aarch64-linux-gnu/libxkbcommon-x11.so \
-DXKB_COMMON_X11_INCLUDE_DIR=/home/ska/sysroot/usr/include/xkbcommon4. 编译与安装
cmake --build . --parallel注意： 若编译过程中遇到 DBus 静态链接冲突错误，可重命名静态库：
sudo mv /home/用户名/sysroot/usr/lib/aarch64-linux-gnu/libdbus-1.a /home/用户名/sysroot/usr/lib/aarch64-linux-gnu/libdbus-1.a.bak
编译完成后安装到指定系统目录：
sudo cmake --install .5. 复制库到目标机器并在目标机配置环境
传输库文件：
scp -r /usr/local/raspi-qt6/* 目标机器用户名@ip地址:/home/用户名/qt6在目标机配置环境变量（修改 ~/.bashrc）：
vim ~/.bashrc在末尾添加：
export LD_LIBRARY_PATH=/home/用户名/qt6/lib:$LD_LIBRARY_PATH
export QT_PLUGIN_PATH=/home/用户名/qt6/plugins
export QML2_IMPORT_PATH=/home/用户名/qt6/qml
export PATH=/home/用户名/qt6/bin:$PATH刷新配置：
source ~/.bashrcIDE 与开发环境配置
方案 A：Qt Creator 配置 (参考)
- Qt 版本：配置编译安装后的 qmake/Qt 路径。
- 编译器：配置
aarch64-linux-gnu-gcc与aarch64-linux-gnu-g++。 - 设备连接：在“设备”选项中添加远程目标机 IP 与 SSH 凭据。
- 构建套件 CMake 配置：
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_SYSROOT /home/ska/sysroot)
set(CMAKE_FIND_ROOT_PATH /home/ska/sysroot /usr/local/raspi-qt6)
set(CMAKE_C_COMPILER /usr/bin/aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER /usr/bin/aarch64-linux-gnu-g++)
set(CMAKE_AR /usr/bin/aarch64-linux-gnu-ar)
set(CMAKE_RANLIB /usr/bin/aarch64-linux-gnu-ranlib)
set(CMAKE_OBJDUMP /usr/bin/aarch64-linux-gnu-objdump)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
set(CMAKE_PREFIX_PATH "/usr/local/raspi-qt6")
set(CMAKE_FIND_LIBRARY_SUFFIXES ".so;.a")补充处理： 若 Qt Creator 优先读取了 sysroot 里的 ninja，可重命名避免冲突：
sudo mv /home/ska/sysroot/usr/bin/ninja /home/ska/sysroot/usr/bin/ninja_bkup
方案 B：使用 VSCode 交叉编译（推荐）
1. 项目根目录创建 CMakePresets.json
{
"version": 8,
"configurePresets": [
{
"name": "cross",
"displayName": "GCC 12.2.0 aarch64-linux-gnu",
"description": "正在使用编译器: C = /usr/bin/aarch64-linux-gnu-gcc, CXX = /usr/bin/aarch64-linux-gnu-g++",
"binaryDir": "${sourceDir}/out/build/${presetName}",
"cacheVariables": {
"CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
"CMAKE_SYSTEM_NAME": "Linux",
"CMAKE_SYSTEM_PROCESSOR": "aarch64",
"CMAKE_SYSROOT": "/home/ska/sysroot",
"CMAKE_FIND_ROOT_PATH": "/home/ska/sysroot;/usr/local/raspi-qt6",
"CMAKE_C_COMPILER": "/usr/bin/aarch64-linux-gnu-gcc",
"CMAKE_CXX_COMPILER": "/usr/bin/aarch64-linux-gnu-g++",
"CMAKE_FIND_ROOT_PATH_MODE_PROGRAM": "NEVER",
"CMAKE_FIND_ROOT_PATH_MODE_LIBRARY": "ONLY",
"CMAKE_FIND_ROOT_PATH_MODE_INCLUDE": "ONLY",
"CMAKE_FIND_ROOT_PATH_MODE_PACKAGE": "ONLY",
"CMAKE_FIND_LIBRARY_SUFFIXES": ".so;.a",
"CMAKE_BUILD_TYPE": "Debug"
}
}
]
}2. 在 CMakeLists.txt 中指定 Qt 路径
set(QT_SDK_DIR /usr/local/raspi-qt6 CACHE PATH "QT SDK DIR" FORCE)如果该博客帮到了你，不妨请作者喝杯奶茶~
ska变老婆
嘿嘿
哈哈
谢谢up主
不客气。