同步卡住或失败的排查步骤

现象判断

先说怎么确认是同步真的坏了还是只是慢：

• 打开 设置 → 云同步，看上次同步时间戳是不是停在很久以前。
• 手动点「立即同步一次」，观察是否有报错提示。
• 打开 GitHub 网页版找到你的 Gist，看那个 JSON 文件的内容有没有更新。

排查清单

① GitHub 授权过期

最常见原因。OAuth 授权不会永久有效，偶尔会失效。表现为手动同步时报「401 Unauthorized」。

解决：进入 设置 → 账号，先点「退出登录」，重新走一遍 GitHub 登录授权流程。

② 网络问题

Novella 访问 GitHub 的 API 端点在国内网络环境下可能不稳定。如果你的同步一直卡在 loading 转圈，大概率是这个原因。

解决：切到代理或 VPN 后重试同步；或者在设置里把同步频率改成手动，手动触发时确保在网络通畅的环境下操作。

③ Gist ID 填错了

如果你是手动创建 Gist 后把 ID 填进来的，检查一下 ID 是否复制完整——Gist ID 是一串哈希，漏一个字符就会定位到错误的 Gist 或根本找不到。

验证方法：在浏览器打开 https://gist.github.com/<你的用户名>/<Gist ID>，看能不能打开正确的那个片段。

④ Gist 被删除了

如果 Gist 被你自己或别人删掉了，Novella 会表现为「拉取失败」且创建新 Gist 的按钮会报错。

解决：重新在 GitHub 创建一个新的私有 Gist，把新 ID 填进 Novella，点「立即同步」让应用往新 Gist 里写初始数据。本地书架不会因此丢失。

⑤ 版本不兼容

极少见但确实存在——Novella 旧版本写入的 Gist 格式在新版本里可能有 breaking change。如果升级后同步突然不工作，大概率是这个原因。

解决：升级到最新版本，或者到 GitHub Issues 搜索「sync」关键词看是否有已知兼容性问题。