1. 鲁班猫5 RK3588 上跑 Qt6.8，先搞清楚这套环境到底难在哪

鲁班猫5 用的是 RK3588，这颗 SoC 是 4×Cortex-A76 + 4×Cortex-A55 的大小核架构，GPU 是 Mali-G610，NPU 算力 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/api，Key 粘贴进去，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.x
• Developer 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/qtcreator

qmake 路径要记牢，后面配 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，配置如下：

配好之后点 Apply。如果 Qt Creator 提示No valid kit，检查 gcc 和 g++ 是不是装了，which gcc能输出路径就行。

如果你要用 TaoToken 的 coding plan 来做长期开发，可以在 Qt Creator 的插件市场里装一个支持自定义 API 的 AI 插件，然后把 Base URL 填https://taotoken.net/api，Key 填控制台生成的。这样你在写 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_test

main.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.pro：

QT += 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 插件没装或者显示环境不对。试试指定 EGLFS：

export QT_QPA_PLATFORM=eglfs ./qt_test

EGLFS 是直接走 framebuffer 和 GPU 的，不依赖 X11，在嵌入式板子上更常用。如果 EGLFS 也报错，检查/opt/Qt/6.8.0/gcc_64/plugins/platforms/下面有没有libqeglfs.so，没有的话说明安装的时候没勾 EGLFS 相关组件，重新跑安装器补上。

串口调试这边，用 minicom 连上板子的调试串口：

sudo minicom -D /dev/ttyUSB0 -b 1500000

RK3588 的调试串口波特率一般是 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 的环境里跑，直接换 EGLFS：

export QT_QPA_PLATFORM=eglfs

报错三：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 URL：https://taotoken.net/api
• API 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-g++，sysroot 指向板子的根文件系统。这样你在 PC 上写代码，编译完 scp 到板子上跑，开发效率比直接在板子上编译高很多。

串口调试的日常用法：minicom 保持连接，Qt 程序里的qDebug输出重定向到串口或者终端。如果要在程序里同时读串口数据和打日志，用QSerialPort加qInstallMessageHandler把日志写到文件，避免和串口数据混在一起。

最后给一个实用技巧：Qt6.8 在 RK3588 上跑 EGLFS 的时候，如果屏幕分辨率不对，可以在/etc/environment里加一行QT_QPA_EGLFS_WIDTH=1920和QT_QPA_EGLFS_HEIGHT=1080，强制指定分辨率。这个在接不同显示器的时候很有用，省得每次改代码。