---
title: 问题排查
category: advanced
order: 4
---

# 问题排查

遇到问题不要慌，本文介绍如何排查和解决常见问题。

## 调试面板

Opentu 提供了一个内置的调试面板，可以帮助定位问题。

### 打开调试面板

在浏览器地址栏输入对应环境的调试面板地址：

| 环境 | 调试面板地址 |
|------|-------------|
| 正式环境 | [https://opentu.ai/sw-debug.html](https://opentu.ai/sw-debug.html) |
| 体验环境 | [https://pr.opentu.ai/sw-debug.html](https://pr.opentu.ai/sw-debug.html) |

**规则**：在当前应用地址后面加 `/sw-debug.html`

### 调试面板功能

调试面板界面如下：

<Screenshot id="debug-panel" alt="调试面板" />

调试面板提供以下功能：

#### 1. Service Worker 状态

显示当前 Service Worker 的运行状态：
- **已连接**（绿色）- 正常工作
- **未连接**（红色）- 需要排查

#### 2. 导出诊断日志

点击 **导出日志** 按钮，会下载一个 JSON 文件，包含：
- 任务队列状态
- API 请求日志
- 错误信息

:::tip
遇到问题时，导出日志文件发给开发者，可以帮助快速定位问题。
:::

#### 3. 数据备份

在调试面板中也可以进行数据备份：
- 点击 **数据备份** 按钮
- 选择要备份的内容
- 下载 ZIP 文件

#### 4. 清除缓存

如果应用出现异常（如页面空白、功能失效），可以尝试清除缓存：
- 点击 **清除缓存** 按钮
- 刷新页面

:::note
清除缓存不会删除你的项目和素材，只会清除应用程序的缓存文件。
:::

## 常见问题

### AI 生成功能不可用

**症状**：点击发送后没有反应，或提示错误

**排查步骤**：

1. **检查网络连接**
   - 确保网络正常
   - 尝试刷新页面

2. **检查 API 配置**
   - 打开 **菜单 → 设置**
   - 确认 API Key 已正确填写
   - 确认 API 地址正确

3. **检查 API 额度**
   - 登录 API 服务商后台查看余额

4. **查看调试面板**
   - 打开 `sw-debug.html`
   - 查看是否有错误日志

### 页面加载缓慢或空白

**症状**：页面长时间白屏或加载很慢

**解决方法**：

1. **清除浏览器缓存**
   - 打开调试面板
   - 点击 **清除缓存**
   - 刷新页面

2. **硬刷新**
   - Windows: `Ctrl + Shift + R`
   - Mac: `Cmd + Shift + R`

3. **检查浏览器兼容性**
   - 推荐使用 Chrome、Edge、Safari 最新版
   - 不建议使用 IE 浏览器

### 素材库图片不显示

**症状**：素材库中的图片显示为空白或加载失败

**解决方法**：

1. **检查存储空间**
   - 浏览器本地存储可能已满
   - 删除不需要的素材释放空间

2. **清除并重新缓存**
   - 打开调试面板
   - 查看缓存状态
   - 尝试清除异常的缓存项

### 数据丢失

**症状**：项目或素材突然消失

**可能原因**：

1. **浏览器数据被清除**
   - 检查是否使用了"清理工具"
   - 检查浏览器隐私设置

2. **使用了无痕/隐私模式**
   - 无痕模式关闭后数据会丢失
   - 请使用正常模式

**预防措施**：

- 定期使用 **备份恢复** 功能导出数据
- 重要项目及时导出为 PNG 或 JSON 文件

### 视频生成一直等待

**症状**：视频任务长时间显示"处理中"

**说明**：

视频生成需要较长时间（1-5 分钟甚至更长），这是正常的。

**如果超过 10 分钟**：

1. 在任务队列中查看任务状态
2. 如果显示失败，点击 **重试**
3. 检查调试面板中的错误日志

### 快捷键不生效

**可能原因**：

1. **焦点在输入框中**
   - 点击画布空白区域，确保焦点在画布上

2. **与浏览器快捷键冲突**
   - 某些快捷键可能被浏览器占用
   - 尝试使用工具栏按钮代替

3. **输入法干扰**
   - 切换到英文输入法
   - 关闭输入法后重试

## 获取技术支持

如果以上方法无法解决问题：

### 1. 收集信息

- 打开调试面板，导出日志
- 截图问题界面
- 记录操作步骤

### 2. 联系方式

- **GitHub Issues**: [提交问题](https://github.com/ljquan/aitu/issues)
- **用户交流群**: 扫码加入

<img src="https://tuziai.oss-cn-shenzhen.aliyuncs.com/aitu/AiTu.png" alt="用户交流群二维码" style="max-width: 180px; border-radius: 8px;" />

### 3. 提交问题时请包含

- 问题描述
- 操作步骤
- 浏览器版本
- 导出的日志文件（如有）
- 截图（如有）
