GitHub Gist 同步卡住或不触发

先确认问题范围

同步问题分两类：

• 完全同步不工作 —— 点手动同步按钮没反应或报错。
• 部分数据不同步 —— 书架同步了但进度没同步、或反过来。

按这两类分别排查。

第一类：完全同步不工作

报错 401 Unauthorized

GitHub OAuth 授权过期了。解决：

1. 设置 → 账号 → 退出登录。
2. 重新走一遍 GitHub 授权流程。
3. 授权成功后回到云同步设置，点「立即同步」验证。

一直转圈、没有报错也没有结果

大概率是网络访问 GitHub 受限。在中国大陆网络环境下，GitHub API 的可达性不稳定。验证方法：

1. 在手机浏览器打开 https://api.github.com，看能不能正常加载 JSON 响应。
2. 如果浏览器也打不开，需要在手机上开启科学上网或代理。
3. 代理开启后回到 Novella 重试同步——Novella 会自动使用系统网络设置。

手动同步按钮点了没反应

极少见，可能是 Novella 的 Gist 客户端内部状态混乱。解决：

1. 先点「退出登录」清理本地 GitHub 会话。
2. 强制停止 Novella（设置 → 应用 → Novella → 强制停止）。
3. 重新打开应用，重新登录 GitHub。
4. 进入云同步设置重新配置 Gist ID（如果用手动创建的 Gist）。

第二类：部分数据不同步

书架同步了但阅读进度没同步

可能是同步触发时机问题：

• 自动同步模式下，进度变更不一定立即推送——有延迟（根据你设置的同步频率）。
• 在设备 A 上读完一章后，等同步触发（或手动点一次），再去设备 B 拉取。
• 进度数据存在 Gist 的 JSON 里的 readingProgress 字段，如果书架数据里有这个字段但设备 B 不识别，可能是两个设备的 Novella 版本差异——确保两台设备都更新到同一个版本号。

进度同步了但书签没同步

书签也是 Gist 里存的，但它和进度是独立字段。如果进度同步正常但书签不：

1. 在设备 A 上手动点一次「立即同步」强制推一次完整数据。
2. 去 GitHub 网页版找到你的 Gist，打开那个 JSON 文件看有没有 bookmarks 字段。
3. 如果 JSON 里有书签数据但设备 B 看不到，说明设备 B 的 Novella 版本太旧——升级到最新版。

多设备同时写导致数据丢失

Gist 是单文件覆盖更新，两边同时写时后到的版本覆盖先到的。避免这个问题：

• 每次换设备阅读前先手动点「从云端拉取」拿最新版本。
• 读完后立刻手动点「立即同步」推上去。
• 不要在两台设备上同时阅读同一本书。

紧急恢复

如果 Gist 里的数据被意外覆盖或清空，用本地备份恢复：

1. 在还能正常用的那台设备上，立即导出手动备份（设置 → 存储 → 备份与恢复 → 导出备份）。
2. 把备份文件传到另一台设备。
3. 在出问题的设备上导入备份。

这也说明手动备份的重要性——Gist 可能因为各种原因丢失数据，手动备份是最后一道保险。