鲁班猫5 RK3588 ubuntu24.04 安装QT6.8开发环境：从零到可编译的完整配置

1. 鲁班猫5 RK3588 上跑 Qt6.8先搞清楚这套环境到底难在哪鲁班猫5 用的是 RK3588这颗 SoC 是 4×Cortex-A76 4×Cortex-A55 的大小核架构GPU 是 Mali-G610NPU 算力 6 TOPS。板子出厂一般预装 Ubuntu 22.04 或者 Debian但你要跑 Qt6.8官方推荐的基础系统是 Ubuntu 24.04。Qt6.8 是 LTS 版本对 Wayland、OpenGL ES 3.2 的支持比 Qt5 完整得多RK3588 的 Mali-G610 在 Qt6 下能直接走 EGLFS 或者 Wayland 后端不需要额外打补丁。问题在于Qt6.8 的在线安装器在 ARM64 平台上并不像 x86 那么顺。你在板子上直接跑qt-unified-linux-arm64-online.run大概率会遇到两个坑一是缺libxcb-cursor.so.0这类 XCB 依赖安装器界面直接起不来二是安装完之后 Qt Creator 里默认的 Kit 是空的qmake 路径、编译器、调试器全要手动指。更麻烦的是如果你打算在 PC 上交叉编译再推到板子跑那还要配一套 aarch64 的交叉工具链和 sysroot这一步对新手来说最容易卡住。我自己的做法是分两条路走先在板子上装一套原生 Qt6.8保证能编译能跑验证硬件和驱动没问题然后再在 PC 上配交叉编译环境用于日常开发。这篇先聚焦板端原生环境把依赖、安装器、Qt Creator 配置、最小工程验证串起来。你跟着做最后能在鲁班猫5 的屏幕上看到一个自己编译的 Qt Widgets 窗口并且能用串口把调试信息打出来。适合谁看手里有鲁班猫5、系统已经刷成 Ubuntu 24.04、想用 Qt 做嵌入式 UI 或者工控界面的开发者。不需要你之前用过 Qt6但至少要会基本的apt和终端操作。下面所有命令我都在板子上实测过路径和包名直接复制就能用。2. 装 Qt6.8 之前先把 Ubuntu 24.04 的依赖和 TaoToken 配置理清楚Ubuntu 24.04 的软件源里 Qt6 的版本是 6.4 左右达不到 6.8所以必须走 Qt 官方在线安装器。但安装器本身是个动态链接的二进制依赖一堆 XCB 和图形库。你直接chmod x然后运行终端会报error while loading shared libraries: libxcb-cursor.so.0: cannot open shared object file。这不是安装器坏了是系统缺库。先把基础依赖一次性装齐。下面这条命令覆盖了安装器运行、Qt Creator 界面、OpenGL ES、串口调试所需的库sudo apt update sudo apt install -y libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 \ libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xkb1 \ libxkbcommon-x11-0 libgl1-mesa-dev libglu1-mesa-dev \ libegl1-mesa-dev libgles2-mesa-dev libinput-dev \ libfontconfig1 libdbus-1-3 libssl-dev libx11-xcb1 \ libxcb1 libxcb-glx0 libxcb-shm0 libxcb-util1 \ build-essential cmake ninja-build git \ python3 python3-pip python3-venv \ libserialport-dev minicom装完之后用ldd检查一下安装器还缺什么ldd ~/qt-unified-linux-arm64-online.run | grep not found如果输出为空说明依赖齐了。还有缺的按报错名字继续apt install对应的libxxx-dev包。接下来是 TaoToken 的配置。TaoToken 在这里的作用是给 Qt Creator 里的 AI 辅助插件、以及你后续可能用到的代码补全工具提供统一的模型接入入口。它的 API 地址是https://taotoken.net/api你需要在 TaoToken 控制台生成一个 API Key然后在 Qt Creator 的 AI 插件设置里填 Base URL 和 Key。这一步不是 Qt 编译的必需项但如果你想让 Qt Creator 里的代码助手能正常工作建议先配好。具体操作打开浏览器进 TaoToken 控制台创建一个 Key复制出来。然后在 Qt Creator 里找到 AI 插件一般是 Copilot 或者 Continue 类的插件把 Base URL 填成https://taotoken.net/apiKey 粘贴进去Model ID 填你控制台里看到的模型名。这样你在写 Qt 代码的时候补全和解释都能走 TaoToken 的通道不用单独去配每个模型的直连。有一点要注意TaoToken 的 API 地址不要加 UTM 参数直接写https://taotoken.net/api就行。控制台和 API Keys 页面分别是https://taotoken.net/console和https://taotoken.net/api-keys这两个链接带不带参数都能访问但填到配置文件里的时候用干净地址。依赖装完、Key 拿到之后再下载安装器。推荐从清华镜像站下速度比官方源稳wget https://mirrors.tuna.tsinghua.edu.cn/qt/archive/online_installers/4.8/qt-unified-linux-arm64-online.run chmod x qt-unified-linux-arm64-online.run版本号 4.8 是安装器版本不是 Qt 版本装的时候在界面里选 Qt 6.8 就行。下载完先别急着跑下一节讲安装器怎么配。3. 可复制的 Qt6.8 安装配置从在线安装器到 qmake 路径安装器跑起来之后第一步是登录 Qt 账号。没有账号的话在界面里注册一个免费账号就能装开源版。登录后选择安装路径我习惯放在/opt/Qt这样多用户都能用sudo mkdir -p /opt/Qt sudo chown $USER:$USER /opt/Qt ./qt-unified-linux-arm64-online.run安装器界面里组件选择这一步最关键。不要全选按下面这个清单勾Qt 6.8.0 下面的Desktop gcc 64-bit这是板端原生编译用的Qt 6.8.0 下面的Qt Debug Information Files可选调试用Developer and Designer Tools 下面的Qt Creator 14.xDeveloper and Designer Tools 下面的CMake、Ninja如果需要串口勾Qt Serial Port模块在 Qt 6.8.0 的 Additional Libraries 里装完之后Qt 的目录结构大概是/opt/Qt/6.8.0/gcc_64/bin/qmake /opt/Qt/6.8.0/gcc_64/bin/qt-cmake /opt/Qt/Tools/QtCreator/bin/qtcreatorqmake 路径要记牢后面配 Kit 的时候要用。如果你在 PC 上做交叉编译qmake 路径会变成/opt/Qt/6.8.0/gcc_arm64/bin/qmake这是另一套工具链别搞混。装完先验证 qmake 能不能跑/opt/Qt/6.8.0/gcc_64/bin/qmake --version正常输出应该是QMake version 3.1和Using Qt version 6.8.0。如果报cannot execute binary file说明你下的是 x86 的安装器重新下 arm64 版本。接下来配 Qt Creator 的 Kit。打开 Qt Creator进Edit Preferences Kits在 Qt Versions 标签页点 Add选/opt/Qt/6.8.0/gcc_64/bin/qmake。然后到 Kits 标签页新建一个 Kit配置如下配置项值NameRK3588-Native-Qt6.8Compiler C/usr/bin/gccCompiler C/usr/bin/gDebugger/usr/bin/gdbQt versionQt 6.8.0 (gcc_64)CMake Tool/opt/Qt/Tools/CMake/bin/cmakeNinja/opt/Qt/Tools/Ninja/ninja配好之后点 Apply。如果 Qt Creator 提示No valid kit检查 gcc 和 g 是不是装了which gcc能输出路径就行。如果你要用 TaoToken 的 coding plan 来做长期开发可以在 Qt Creator 的插件市场里装一个支持自定义 API 的 AI 插件然后把 Base URL 填https://taotoken.net/apiKey 填控制台生成的。这样你在写 Qt 代码的时候补全请求会走 TaoToken不用每个模型单独配。Coding Plan 的入口在https://taotoken.net/coding-plan适合需要长时间跑 Agent 的场景。串口调试这块Ubuntu 24.04 默认会把串口设备识别成/dev/ttyUSB0或者/dev/ttyS0。你需要把当前用户加到 dialout 组否则 minicom 打不开设备sudo usermod -aG dialout $USER改完要重新登录才生效。验证的话用ls -l /dev/ttyUSB*看权限组是 dialout 就对了。4. 验证请求编译一个最小 Qt Widgets 工程并在板端跑起来环境配好了得用一个真实工程验证。我写一个最小的 Qt Widgets 程序带一个按钮和一个标签点按钮改标签文字。这个工程能验证 qmake、编译器、链接器、Qt 库、显示后端整条链路。先建目录和文件mkdir -p ~/qt_test cd ~/qt_testmain.cpp#include QApplication #include QWidget #include QVBoxLayout #include QLabel #include QPushButton int main(int argc, char *argv[]) { QApplication app(argc, argv); QWidget window; window.setWindowTitle(RK3588 Qt6.8 Test); window.resize(400, 300); QVBoxLayout *layout new QVBoxLayout(window); QLabel *label new QLabel(Hello RK3588, window); label-setAlignment(Qt::AlignCenter); QPushButton *btn new QPushButton(Click Me, window); layout-addWidget(label); layout-addWidget(btn); QObject::connect(btn, QPushButton::clicked, [label]() { label-setText(Button Clicked!); }); window.show(); return app.exec(); }qt_test.proQT widgets TARGET qt_test TEMPLATE app SOURCES main.cpp编译/opt/Qt/6.8.0/gcc_64/bin/qmake qt_test.pro make -j8如果一切正常当前目录会生成qt_test可执行文件。用file qt_test看一下输出应该是ELF 64-bit LSB pie executable, ARM aarch64说明编译出来的是板端原生程序。运行之前先确认显示后端。鲁班猫5 如果接了 HDMI 显示器直接跑./qt_test窗口应该出现在屏幕上点按钮标签会变。如果报qt.qpa.plugin: Could not load the Qt platform plugin xcb说明 XCB 插件没装或者显示环境不对。试试指定 EGLFSexport QT_QPA_PLATFORMeglfs ./qt_testEGLFS 是直接走 framebuffer 和 GPU 的不依赖 X11在嵌入式板子上更常用。如果 EGLFS 也报错检查/opt/Qt/6.8.0/gcc_64/plugins/platforms/下面有没有libqeglfs.so没有的话说明安装的时候没勾 EGLFS 相关组件重新跑安装器补上。串口调试这边用 minicom 连上板子的调试串口sudo minicom -D /dev/ttyUSB0 -b 1500000RK3588 的调试串口波特率一般是 1500000不是常见的 115200。连上之后能看到内核日志和登录提示。如果你在 Qt 程序里要读串口数据用 Qt Serial Port 模块#include QSerialPort QSerialPort serial; serial.setPortName(/dev/ttyUSB0); serial.setBaudRate(1500000); if (serial.open(QIODevice::ReadWrite)) { qDebug() Serial opened; }编译的时候在.pro里加QT serialport。跑起来之后qDebug的输出会打到终端配合 minicom 就能同时看程序日志和串口数据。验证成功的标志窗口显示、按钮响应、终端没有报错、qDebug输出正常。到这一步Qt6.8 的开发环境就算通了。5. 本篇常见错排查401、local proxy failed、reading choices 这些报错怎么解装 Qt6.8 的过程中报错基本集中在依赖、路径、权限、网络四类。下面是我实际踩过的几个对照着看。报错一error while loading shared libraries: libxcb-cursor.so.0这是安装器启动时最常见的。原因就是系统缺 XCB 的 cursor 库。解决sudo apt install -y libxcb-cursor0如果装完还报别的libxcb-xxx用apt-file search找对应的包sudo apt install -y apt-file sudo apt-file update apt-file search libxcb-icccm4.so.4报错二qt.qpa.plugin: Could not load the Qt platform plugin xcb程序编译过了运行时报这个。说明 Qt 找不到 xcb 平台插件或者插件依赖的库缺失。先看插件在不在ls /opt/Qt/6.8.0/gcc_64/plugins/platforms/应该有libqxcb.so。然后用ldd查它缺什么ldd /opt/Qt/6.8.0/gcc_64/plugins/platforms/libqxcb.so | grep not found缺什么装什么。如果是在没有 X11 的环境里跑直接换 EGLFSexport QT_QPA_PLATFORMeglfs报错三local proxy failed或者Connection refused这个一般出现在 Qt Creator 里配了 AI 插件、或者在线安装器下载组件的时候。如果你在 Qt Creator 的 AI 插件里填了 TaoToken 的地址检查 Base URL 是不是写成了https://taotoken.net/api不要多写斜杠或者路径。Key 是不是从https://taotoken.net/api-keys复制的完整字符串。如果安装器下载组件卡住换清华镜像源在安装器界面里点 Settings把仓库地址改成https://mirrors.tuna.tsinghua.edu.cn/qt/。报错四reading choices或者安装器界面空白安装器启动后界面出不来终端报reading choices相关错误。这通常是 Qt 版本和系统库不匹配。试试用--platform minimal参数启动安装器./qt-unified-linux-arm64-online.run --platform minimal这样会跳过图形界面走命令行安装。命令行模式下按提示选组件效果一样。报错五OAuth登录失败Qt 账号登录走 OAuth如果板子网络时间不对OAuth 会失败。先同步时间sudo apt install -y ntpdate sudo ntpdate ntp.aliyun.com然后再登录。如果还是失败在 PC 上登录好账号把~/.local/share/Qt目录拷到板子上能跳过登录步骤。报错六Project ERROR: Unknown module(s) in QT: serialport.pro里写了QT serialport但编译报这个说明安装 Qt 的时候没勾 Serial Port 模块。重新跑安装器在 Qt 6.8.0 的 Additional Libraries 里勾上Qt Serial Port装完重新 qmake。排查的时候记住一个原则先看报错里缺的文件名用apt-file search找包装完再跑。Qt 的报错一般都很直白缺什么补什么就行。6. 环境跑通之后Qt Creator 里怎么接 TaoToken 做日常开发板端原生环境验证通过之后日常开发基本都在 Qt Creator 里。如果你想让代码补全、错误解释、文档查询这些走 TaoToken可以在 Qt Creator 的插件设置里配。具体路径是Edit Preferences AI Assistant不同版本菜单名可能不一样找到自定义 API 的选项填三个东西Base URLhttps://taotoken.net/apiAPI Key从https://taotoken.net/api-keys复制Model ID在https://taotoken.net/console里看你开通的模型配好之后在 Qt Creator 里写代码的时候补全请求会走 TaoToken 的通道。如果你要跑长时间的 Agent 任务比如批量生成 UI 代码或者做代码审查可以用 Coding Plan入口在https://taotoken.net/coding-plan。模型对话的入口在https://taotoken.net/chat适合临时问一些 Qt API 的用法。有一点要提醒TaoToken 是模型接入层不是 Qt 的替代品。Qt Creator 本身的编译、调试、Kit 配置还是走本地工具链TaoToken 只负责 AI 相关的请求。不要把 TaoToken 的地址填到 Qt 的 qmake 或者编译器路径里那是两回事。如果你在 PC 上做交叉编译Qt Creator 里可以配两套 Kit一套是板端原生的RK3588-Native-Qt6.8一套是 PC 上的交叉编译 Kit。交叉编译 Kit 的 qmake 路径指向/opt/Qt/6.8.0/gcc_arm64/bin/qmake编译器指向aarch64-linux-gnu-gsysroot 指向板子的根文件系统。这样你在 PC 上写代码编译完 scp 到板子上跑开发效率比直接在板子上编译高很多。串口调试的日常用法minicom 保持连接Qt 程序里的qDebug输出重定向到串口或者终端。如果要在程序里同时读串口数据和打日志用QSerialPort加qInstallMessageHandler把日志写到文件避免和串口数据混在一起。最后给一个实用技巧Qt6.8 在 RK3588 上跑 EGLFS 的时候如果屏幕分辨率不对可以在/etc/environment里加一行QT_QPA_EGLFS_WIDTH1920和QT_QPA_EGLFS_HEIGHT1080强制指定分辨率。这个在接不同显示器的时候很有用省得每次改代码。