排障指南

1. 版本入口不显示 / 面板空白

检查项：

• collaboration.enabled 必须为 true
• versions.enabled 不能为 false
• 协作连接必须成功（WebSocket 可连通、token 有效）

相关配置参考：

• 多人协作编辑
• 配置项

2. 保存版本提示“内容没有变化，无法创建新版本”

这是为了避免“无效快照”占用存储。

默认策略：当当前内容与最近一次保存的版本一致时，会拒绝创建新版本。

处理建议：

• 先对文档做一次修改再保存
• 或者在产品层允许创建“标记型版本”（只记录里程碑，不强制要求正文变化）

3. 预览版本失败 / 显示“版本内容不存在”

可能原因：

• 该版本未成功保存完成（只写入了版本记录，但预览数据未落盘/未可读）
• 服务端存储被清理或迁移不完整，导致旧版本的预览数据缺失
• 文档标识不一致，导致读取不到对应版本的预览数据

定位建议：

• 确认该版本在版本列表中存在（能看到版本号与版本名）
• 在网络/WebSocket 面板里确认 action: 'version.preview' 是否有对应的 event: 'version.preview' 回包

4. “重要”标签不显示 / 切换后不生效

检查项：

• 确认已在版本条目的“更多”菜单中执行“标为重要 / 取消重要”
• 确认协作连接处于已连接状态（断线时操作不会同步）
• 如果你是自绘版本列表：确认使用的版本列表数据中包含 important 字段