RK3568开发笔记：Qt程序报错Failed to move cursor on screen的配置排查与修复

1. RK3568 上 Qt 启动报 Failed to move cursor on screen 是什么如果你在 RK3568 这类嵌入式板卡上跑 Qt 程序终端里突然刷出Failed to move cursor on screen UNKNOWN1: -14紧接着Could not set cursor on screen UNKNOWN1: -6最后进程直接Segmentation fault那基本可以确定Qt 在启动阶段没能正确绑定到显示服务光标操作落到了一个不存在的 screen 对象上。这个报错本身不是 Qt 崩溃的根因而是「平台插件选错或没选」暴露出来的症状。RK3568 常见的系统镜像Buildroot、Debian、Ubuntu Base默认跑的是 Weston 合成器底层走 Wayland 协议。但 Qt 程序如果没被告知用哪个平台插件它会按编译期默认值去猜猜成xcbX11或者eglfs于是 Wayland 合成器里根本没有对应的 screen光标移动请求返回-14EFAULT 类错误后续-6ENXIO表示设备/对象不存在再往下就是空指针解引用导致的段错误。这篇笔记面向正在 RK3568 上做 Qt 应用移植、调试显示问题的嵌入式开发者。我会从环境变量、Qt 平台插件、光标主题三个角度把根因拆开给出可直接复制的config.toml与settings.json骨架配合 TaoToken 统一 Key/API 通道做接入示例最后用终端命令逐项复现报错、验证修复。整套流程我在 RK3568 Weston Qt 5.15 的组合上实测过踩过的坑会标出来。2. 先确认你的显示栈Weston、Wayland 与 Qt 平台插件在动手改配置之前得先搞清楚板子上到底跑的是什么显示服务。很多人一上来就export QT_QPA_PLATFORMwayland结果发现程序还是崩因为环境变量加错了地方或者 Weston 根本没起来。2.1 判断当前显示服务类型登录 RK3568 串口或 SSH执行ps aux | grep -E weston|Xorg|wayland echo $XDG_RUNTIME_DIR ls -l /var/run预期输出里应该能看到weston进程XDG_RUNTIME_DIR指向/var/run或/run/user/0。如果XDG_RUNTIME_DIR为空Wayland 客户端连 socket 都找不到Qt 必然报错。注意/var/run通常是指向/run的符号链接Qt 会打印runtime directory /var/run is not a directory, but a symbolic link这条是警告不是致命错误可以忽略。2.2 Qt 平台插件的选择逻辑Qt 启动时按以下优先级决定平台插件命令行-platform参数 QT_QPA_PLATFORM环境变量 编译期默认值。RK3568 的 Qt 通常编译时带了wayland、eglfs、linuxfb几个插件但默认值可能是xcb。你可以用这条命令看板子上装了哪些插件ls /usr/lib/qt/plugins/platforms/ # 或 find / -name libqwayland*.so 2/dev/null如果看到libqwayland-egl.so、libqwayland-generic.so说明 Wayland 插件可用。没有的话就得重新编译 Qt 或安装对应包。2.3 光标主题与 screen 对象的绑定关系Failed to move cursor on screen里的UNKNOWN1是 Qt 给 screen 起的占位名。当平台插件初始化失败Qt 仍然会创建一个「假」screen 对象光标主题管理器尝试在这个假对象上设置光标就会连续报-14和-6。所以修复的核心不是去改光标主题而是让平台插件正确初始化让 screen 对象真实存在。光标主题配置XCURSOR_THEME、XCURSOR_SIZE是次要的但配错了也会让光标显示异常。3. TaoToken 前置统一 Key 与 API 通道准备调试嵌入式 Qt 程序时我习惯把日志分析、报错解释这类需要模型能力的环节接到统一通道上避免在板子和电脑之间来回拷文件。TaoToken 提供统一的 Key 和 API 入口兼容 OpenAI 风格的接口板子上的脚本或上位机都能直接调。3.1 获取 Key 与配置通道先到控制台创建 API Key地址是https://taotoken.net/console。创建后复制 Key形如sk-xxxx。API 基址用https://taotoken.net/api注意这个地址不带任何查询参数直接作为base_url使用。如果你只是想让模型帮你解释一段报错日志用模型对话页面就够了https://taotoken.net/model-chat。如果是要在 CI 或脚本里长期跑编码辅助、Agent 任务建议开 Coding Planhttps://taotoken.net/coding-plan。接入文档在https://taotoken.net/docAPI Key 管理页在https://taotoken.net/api-keys。3.2 config.toml 骨架下面这份config.toml可以直接放到项目根目录或~/.config/下用于统一管理通道参数。字段含义我在注释里标了# TaoToken 统一通道配置骨架 [provider] name taotoken base_url https://taotoken.net/api api_key sk-替换成你的Key timeout_seconds 60 [model] default gpt-4o-mini max_tokens 4096 temperature 0.3 [logging] level info # 板子上空间紧张时关掉请求体日志 log_request_body false3.3 settings.json 骨架有些工具链或 IDE 插件读的是 JSON 配置对应骨架如下{ provider: { name: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-替换成你的Key, timeout: 60000 }, model: { default: gpt-4o-mini, maxTokens: 4096, temperature: 0.3 }, logging: { level: info, logRequestBody: false } }把 Key 写进配置文件后记得chmod 600别让板子上其他用户读到。生产环境更推荐用环境变量TAOTOKEN_API_KEY注入配置文件里留空。4. 可复制配置环境变量、Weston 启动脚本与 Qt 参数这一节是修复的核心。报错Failed to move cursor on screen的直接解法就是让 Qt 用对平台插件同时保证 Weston 的环境变量在 Qt 启动前已经生效。4.1 临时验证命令行直接指定先在当前 shell 里临时导出验证方向对不对export XDG_RUNTIME_DIR/var/run export QT_QPA_PLATFORMwayland export QT_QPA_PLATFORM_PLUGIN_PATH/usr/lib/qt/plugins/platforms ./CMPlayDemo如果这样跑起来不报光标错误了说明根因确认接下来做持久化。注意XDG_RUNTIME_DIR的权限必须是0700否则 Wayland 会拒绝连接chmod 700 /var/run4.2 持久化写入 Weston 启动脚本RK3568 的 Buildroot 镜像通常把环境变量放在/etc/profile.d/weston.sh。编辑这个文件加入 Qt 相关变量# /etc/profile.d/weston.sh export XDG_RUNTIME_DIR/var/run export WESTON_DRM_MIRROR1 export WESTON_DRM_KEEP_RATIO1 export WESTON_DISABLE_ATOMIC1 export WESTON_DRM_DISABLE_MODIFIER1 # 关键告诉 Qt 用 Wayland 平台插件 export QT_QPA_PLATFORMwayland # 光标主题避免默认主题缺失导致光标不显示 export XCURSOR_THEMEAdwaita export XCURSOR_SIZE24改完执行source /etc/profile.d/weston.sh或重启板子。重启后用env | grep QT_QPA确认变量已生效。4.3 自启动服务里的环境变量如果你的 Qt 程序是通过 init 脚本或 systemd 自启动的光改/etc/profile.d/不够因为非登录 shell 不读这个目录。以 systemd 为例在 service 文件里显式声明[Unit] DescriptionQt Demo App Afterweston.service [Service] EnvironmentXDG_RUNTIME_DIR/var/run EnvironmentQT_QPA_PLATFORMwayland EnvironmentXCURSOR_THEMEAdwaita ExecStart/home/user/bin/CMPlayDemo Restarton-failure [Install] WantedBymulti-user.target如果是 BusyBox init就在/etc/init.d/S99qtapp脚本开头export这几个变量再启动程序。4.4 光标主题缺失的兜底有些精简镜像里没有Adwaita主题Qt 会回退到内置光标但 Wayland 合成器可能不认。检查主题目录ls /usr/share/icons/如果没有可用主题装一个最小的opkg update opkg install adwaita-icon-theme # 或 Debian 系 apt install adwaita-icon-theme实在装不了就设XCURSOR_THEME为空让 Qt 用默认箭头至少不崩。5. 验证请求与成功结果逐项复现与修复确认配置改完不能只看「不报错了」要逐项验证每个环节都对了。5.1 复现原始报错在没设环境变量的干净 shell 里跑一次确认能复现env -i /home/user/bin/CMPlayDemo预期输出包含Failed to move cursor on screen UNKNOWN1: -14 Could not set cursor on screen UNKNOWN1: -6 Segmentation fault这一步是为了确认你的程序确实受这个变量影响而不是别的问题。5.2 验证环境变量生效source /etc/profile.d/weston.sh echo $QT_QPA_PLATFORM # 预期输出wayland echo $XDG_RUNTIME_DIR # 预期输出/var/run5.3 验证 Qt 实际使用的平台插件Qt 有个环境变量可以打印插件加载详情export QT_DEBUG_PLUGINS1 ./CMPlayDemo 21 | grep -i platform预期能看到loaded library /usr/lib/qt/plugins/platforms/libqwayland-egl.so之类的行。如果加载的是libqxcb.so说明环境变量没生效回去检查 shell 和 service 文件。5.4 验证程序正常运行./CMPlayDemo预期输出里不再有Failed to move cursor程序进入主循环屏幕上有画面。如果程序是 GUI 且带光标光标应该正常显示。用CtrlC能正常退出不再段错误。5.5 用 TaoToken 通道辅助分析日志把上面复现的日志贴给模型让它帮你确认根因。用 curl 直接调curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: user, content: Qt 报 Failed to move cursor on screen UNKNOWN1: -14随后 Segmentation fault可能原因} ] }预期返回一段 JSONchoices[0].message.content里是分析结果。这一步不是必须的但在你遇到非典型报错时能省不少查资料时间。6. 本篇常见错排查6.1 改了 profile.d 但自启动程序仍报错原因非登录 shell 不读/etc/profile.d/。解决在 service 文件或 init 脚本里显式export别依赖 profile。6.2 XDG_RUNTIME_DIR 权限不对报错可能变成error: XDG_RUNTIME_DIR not set in the environment或连接被拒。执行chmod 700 /var/run并确认属主是当前用户。注意/var/run是符号链接时要改的是它指向的/run。6.3 设了 wayland 但插件没编译进去QT_DEBUG_PLUGINS1显示找不到libqwayland*.so。解决重新编译 Qt 时加-qt-libpng -qt-zlib -wayland或安装qtwayland包。Buildroot 里勾选BR2_PACKAGE_QT5WAYLAND。6.4 光标主题报错但程序能跑如果只是Could not set cursor但没段错误多半是主题缺失。设XCURSOR_THEMEAdwaita或装主题包即可不影响功能。6.5 多屏场景下 screen 名不匹配UNKNOWN1说明 Qt 没拿到真实 screen 名。Wayland 下多屏由合成器管理Qt 通过wl_output获取。确认 Weston 的weston.ini里 output 配置正确别把WESTON_DRM_MIRROR和实际屏幕数搞混。6.6 段错误发生在 SHM_Init 之后日志里SHM_Init 0后崩溃说明共享内存初始化失败通常是XDG_RUNTIME_DIR不可写。检查/var/run是否可写磁盘是否满。7. 继续接入API Key、文档与 Coding Plan修复完显示问题后如果你想把日志分析、报错解释、代码补全这些环节固化到开发流程里可以走 TaoToken 的长期通道。API Key 在https://taotoken.net/api-keys管理接入细节看https://taotoken.net/doc。日常调试用模型对话页面https://taotoken.net/model-chat就够长期跑编码任务或 Agent 建议开 Coding Planhttps://taotoken.net/coding-plan。Claude Code 相关的接入说明在https://taotoken.net/claude-code。板子上的脚本调用时把 Key 放环境变量别硬编码进config.toml提交到仓库。我一般在上位机跑分析脚本板子只负责采集日志这样 Key 不会落到设备上也省得在嵌入式环境里折腾依赖。