如果在使用 MrDoc 觅思文档的过程中，出现了未知的异常和报错，但是找不到原因，可以通过如下方式进行故障排查，以避免无效沟通和节省大家的时间。

## 一、先判断问题类型（最关键一步）

先确认你遇到的是哪一类问题👇

| 问题类型    | 常见表现           | 优先排查             |
| ------- | -------------- | ---------------- |
| ❗ 页面报错  | 500 / 404 / 白屏 | ✅ 开启 Debug + 看日志 |
| ⚠️ 功能异常 | 按钮没反应 / 操作失败   | ✅ 浏览器控制台         |
| 🌐 请求失败 | 加载失败 / 接口报错    | ✅ 网络请求           |
| ❓ 不理解报错 | 英文错误看不懂        | ✅ 翻译 + 搜索        |

👉 **先分类，再动手，否则就是盲查。**

## 二、快速自查（很多问题在这里就结束了）

如果你看到**英文报错**：

建议直接复制错误信息，使用：

* 翻译工具（百度 / 有道）
* 搜索引擎（Google / Bing / 百度）
* AI（ChatGPT / DeepSeek / 豆包）

等工具进行搜索和询问

💡 例如：

```
IntegrityError UNIQUE constraint failed
```

👉 搜一下基本就知道是“数据库唯一约束冲突”

## 三、标准排查流程（按顺序来）

###  一、开启Debug调试

当出现：

* 500 错误
* 页面崩溃
* 后端异常

在配置文件中开启`debug`调试，会输出详细的错误信息。

配置文件详见：https://doc.mrdoc.pro/doc/3990/#h2-开启站点调试

### 二、浏览器调试控制台

#### 控制台报错输出

在出现异常的页面上，鼠标右键选择「检查」（或者直接按键盘的F12），会打开浏览器的调试控制台。

你可以在「控制台」选项卡中查看有无错误信息输出：

![](http://file.mrdoc.pro/mrdoc-oss/img/2023/04/20/2023-04-20_104458_2624190.9230515041405257.png)

#### 网络请求异常

也可以在「网络」选项卡中找到异常相关的请求，查看其请求状态和响应内容。

![](http://file.mrdoc.pro/mrdoc-oss/img/2023/04/20/2023-04-20_104643_6248900.054060900972025094.png)

## 四、查看日志

如果你是部署者，这是**最关键的一步**。

📖 日志说明：[https://doc.mrdoc.pro/doc/45444/](https://doc.mrdoc.pro/doc/45444/)

👉 日志可以告诉你：

* 报错发生在哪一行代码
* 哪个接口出问题
* 数据是否异常

## 五、排查优先级总结（记住这个顺序）

```
能搜索 → 先搜索
能看前端 → 看控制台
涉及接口 → 看 Network
涉及后端 → 开 Debug + 查日志
```

## 六、故障反馈模板

👉 **没有报错信息的提问 = 基本无法排查**

👉 **截图 + 日志 = 解决问题的关键**

如果你需要将故障进行反馈以寻求帮助，为了避免浪费大家的精力，节约大家的时间，请务必提供完整详细的信息，包括但不限于：
```
【基础信息】

1. 部署方式（Docker / 源码 / 宝塔等）
2. MrDoc 版本
3. 数据库类型（SQLite / MySQL / PostgreSQL）

【问题描述】

4. 出问题的页面路径
5. 操作步骤（怎么触发的）
6. 是否稳定复现（必现 / 偶发）

【影响范围】

7. 是单个用户还是所有用户
8. 是单个文档还是全部文档

【环境信息】

9. 操作系统
10. 浏览器及版本

【关键证据（非常重要）】

11. 报错截图（必须）
12. 浏览器控制台截图
13. Network 请求截图（如有）
14. 后端日志（如有）

【补充信息】

15. 文集配置（如果相关）
16. 文档内容（如果相关）
17. 用户权限配置（如果相关）
18. 存储配置（如果相关）
```