Obsidian 同步故障排查

症状 → 可能的原因 → 可以尝试的做法。

登录失败

登录使用设备授权流程：插件会显示一个简短的用户码，在浏览器中打开后端的验证页面，并轮询直到你批准。不会通过 obsidian:// URL scheme 回传任何令牌。

• **验证页面一直没有打开。**复制登录对话框中显示的用户码，手动打开验证 URL，然后粘贴验证码。请检查插件设置中的 Engram URL（云端或自托管）是否正确。
• **在浏览器中已批准，但插件始终没有确认。**插件会在你批准后轮询令牌，请等几秒钟。如果仍未确认，请关闭对话框，并从插件的设置页重新开始登录。
• **登录后提示“Invalid token”。**你的会话可能已过期。请在插件的设置页退出登录，然后重新登录。

同步卡在“Pending push: N”

• 在 同步中心 → Recent activity 日志中查看最近的错误。
• 如果后端可访问但推送返回 409（版本冲突），很可能是真正的冲突，请打开冲突队列。
• 如果推送返回 413，说明该笔记超出了单条笔记的大小上限。请拆分它。
• 如果推送返回 429，说明你被限流了。请等待一分钟后重试，或检查你的订阅套餐。

网页应用显示的是旧内容

• 刷新一次页面。网页应用会订阅实时更新，但首次加载是有缓存的。
• 确认 Obsidian 中的插件所显示的_上次同步_时间晚于你最近一次编辑。

某条笔记无法同步

• 检查路径中是否有非法字符（尤其是在移动端，参见移动端）。
• 检查笔记大小。单条笔记有大小上限。
• 打开同步中心，在 Pending push 中找到该笔记，悬停查看错误原因。

更新后插件无法加载

• 打开 Obsidian 的开发者控制台（Ctrl/Cmd+Shift+I），查看是否有提到 engram-vault-sync 的错误。
• 尝试在设置 → 第三方插件中关闭再重新开启该插件。
• 如果某个发布版本有问题，请在 engram-app/Engram-obsidian 提交 bug，并暂时卸载该插件。一旦社区目录的更新安装完成，就无法在 Obsidian 内恢复到之前的版本。

在哪里提交 bug

engram-app/Engram-obsidian issues。请附上：

• Obsidian 版本、平台（桌面端/iOS/Android）和操作系统版本
• Engram 插件版本
• 同步中心 → Recent activity 日志的截图
• 复现步骤