> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# 故障排查
手套连接、触觉与 EMF 数据异常等设备侧问题请参阅 [Wuji Glove 故障排查](/docs/wuji-glove/troubleshooting)。SDK 相关问题请参阅 [Wuji SDK 故障排查](/docs/wuji-sdk/troubleshooting)。
## 无法启动 / 白屏或崩溃
1. 确认操作系统版本满足要求（Ubuntu 22.04 LTS 及以上版本）
2. 更新 GPU 驱动到最新版本
3. 安装 WebKitGTK：
```bash theme={null}
sudo apt install libwebkit2gtk-4.1-0
```
4. 删除应用数据目录后重试：
```bash theme={null}
# 先备份
cp -r ~/.wuji/studio/data ~/.wuji/studio/data.backup.$(date +%Y%m%d%H%M%S)
rm -rf ~/.wuji/studio/data
```
5. 仍无法启动时，检查系统代理。代理拦截 WebView 本地资源加载会导致白屏，临时清除代理环境变量后启动：
```bash theme={null}
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** 即可恢复默认布局。更多预设操作见[布局预设](/docs/wuji-studio/visualization/layout-presets)。
## 触觉矩阵热力图显示全黑
* 确认已订阅正确的 Topic（tactile 或 tactile\_zones）
* 检查 Matrix 面板的数据范围设置是否正确（默认 0.0\~1.0）
* 轻按手套表面，观察是否有数据变化
## 触觉矩阵热力图错位或呈斜切状
* 检查 Matrix 面板设置中的 **Columns** 是否为 31：触觉矩阵为 24×31，列数与布局不一致时每行错开一格，热力图整体呈斜切状
* 在 Sidebar 的 **Panel** 设置中把 Columns 改回 31，或右键预设标签选择 **Reset to Default** 恢复默认布局
## 固件升级失败
1. 确认电源稳定，升级期间不要断电
2. 确认网络连接稳定，使用有线连接
3. 手套内置回退机制，升级失败会自动恢复上一版本
4. 等待手套 LED 指示完成回退后重试
## 升级过程中遇到错误提示
| 错误类型 | 说明 | 建议 |
| - | - | - |
| 网络错误 | 无法连接到固件服务器 | 检查网络连接 |
| 服务器错误 | 固件服务器返回错误 | 稍后重试 |
| 配置错误 | 固件服务器地址未配置 | 联系管理员 |
| 设备离线 | 升级过程中设备断开连接 | 检查连接线缆和电源 |
## 使用本地固件升级
在第 2 步选择固件时，点击 **Upload local file** 按钮选择固件文件（.zip 格式）。上传后会自动解析并显示固件的版本号、发布日期和发布说明。
使用非官方固件可能导致设备损坏或性能异常，并可能影响保修。请仅使用可信来源的固件文件。
## 获取技术支持
请联系 [support@wuji.tech](mailto:support@wuji.tech)，并附上以下信息：
* 设备序列号（SN）
* 固件版本
* Wuji SDK / Wuji Studio 版本
* 操作系统和版本
* 问题复现步骤
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.