故障排查

手套连接、触觉与 EMF 数据异常等设备侧问题请参阅 Wuji Glove 故障排查。SDK 相关问题请参阅 Wuji SDK 故障排查。

无法启动 / 白屏或崩溃

确认操作系统版本满足要求（Ubuntu 22+）
更新 GPU 驱动到最新版本
安装 WebKitGTK：
```
sudo apt install libwebkit2gtk-4.1-0
```

删除应用数据目录后重试：

# 先备份
cp -r ~/.wuji/studio/data ~/.wuji/studio/data.backup.$(date +%Y%m%d%H%M%S)
rm -rf ~/.wuji/studio/data

仍无法启动时，检查系统代理。代理拦截 WebView 本地资源加载会导致白屏，临时清除代理环境变量后启动：

env -u http_proxy -u https_proxy -u all_proxy -u ftp_proxy -u no_proxy \
    -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY -u FTP_PROXY -u NO_PROXY \
    GSETTINGS_BACKEND=memory \
    wuji-studio

面板显示空白

确认已连接设备并进入可视化视图
检查面板是否订阅了正确的 Topic
尝试重置面板布局（右键点击预设标签 → Reset to Default）

恢复默认布局

当布局调整后，右键点击顶部预设栏的当前预设标签（下图中的 Tactile Monitor），选择 Reset to Default 即可恢复默认布局。更多预设操作见布局预设。

Reset to Default 菜单

触觉矩阵热力图显示全黑

确认已订阅正确的 Topic（tactile 或 tactile_zones）
检查 Matrix 面板的数据范围设置是否正确（默认 0.0~1.0）
轻按手套表面，观察是否有数据变化

触觉矩阵热力图错位或呈斜切状

检查 Matrix 面板设置中的 Columns 是否为 31：触觉矩阵为 24×31，列数与布局不一致时每行错开一格，热力图整体呈斜切状
在 Sidebar 的 Panel 设置中把 Columns 改回 31，或右键预设标签选择 Reset to Default 恢复默认布局

Columns 设为 32 导致触觉热力图斜切，红框处为 Columns 设置

Columns 为 32（斜切）与 31（正常）的渲染对比

固件升级失败

确认电源稳定，升级期间不要断电
确认网络连接稳定，使用有线连接
手套内置回退机制，升级失败会自动恢复上一版本
等待手套 LED 指示完成回退后重试

升级过程中遇到错误提示

错误类型	说明	建议
网络错误	无法连接到固件服务器	检查网络连接
服务器错误	固件服务器返回错误	稍后重试
配置错误	固件服务器地址未配置	联系管理员
设备离线	升级过程中设备断开连接	检查连接线缆和电源

使用本地固件升级

在第 2 步选择固件时，点击 Upload local file 按钮选择固件文件（.zip 格式）。上传后会自动解析并显示固件的版本号、发布日期和发布说明。

使用非官方固件可能导致设备损坏或性能异常，并可能影响保修。请仅使用可信来源的固件文件。

获取技术支持

请联系 support@wuji.tech，并附上以下信息：

设备序列号（SN）
固件版本
Wuji SDK / Wuji Studio 版本
操作系统和版本
问题复现步骤