问题排查

自动同步问题

自动同步不工作？

可能的原因及解决方案：

• 未启用自动同步：确保在插件设置的通用设置中启用了自动同步功能
• frontmatter 中没有 NotionID：验证文档的 frontmatter 中有 NotionID 字段（如 NotionID-blog: abc123）。自动同步仅适用于至少手动同步过一次的文档
• 数据库配置无效：检查数据库配置是否有效，API 凭证是否正确
• 控制台错误：查看开发者控制台（Ctrl+Shift+I / Cmd+Option+I）中的错误信息

同步太频繁？

如果在编辑时自动同步触发太频繁：

• 增加延迟时间：前往插件设置，增加"自动同步延迟时间"的值（默认为 5 秒）
• 理解延迟机制：每次编辑都会重置延迟计时器，只有在停止编辑达到配置的时长后才会触发同步

看不到通知？

如果没有看到同步通知：

• 通知显示时长：通知会显示 3-6 秒然后自动消失
• 查看控制台日志：打开开发者控制台（Ctrl+Shift+I / Cmd+Option+I）查看详细的同步信息
• 多数据库同步：同步到多个数据库时，你会看到一个多数据库同步通知以及各个数据库的结果通知

新文档跳过自动同步

如果看到消息"⚠️ 自动同步跳过：此文档未同步到 Notion，请先手动上传"：

• 需要首次同步：这是预期行为。自动同步仅适用于已有 NotionID 的文档
• 解决方案：使用命令面板（Ctrl/Cmd + P）选择"Share to NotionNext"执行首次手动同步
• 手动同步后：一旦文档的 frontmatter 中有了 NotionID，自动同步就会自动工作

常规同步问题

同步失败并显示错误消息

如果在同步时看到错误消息：

1. 检查 API 凭证：验证 Notion API 令牌和数据库 ID 是否正确
2. 检查权限：确保集成有权限访问目标数据库
3. 网络问题：检查网络连接
4. 速率限制：Notion 有 API 速率限制，等待片刻后重试
5. 查看控制台：打开开发者工具查看详细的错误信息

多数据库同步问题

同步到多个数据库时：

• 部分失败：如果一个数据库失败，其他数据库仍会继续同步
• 独立通知：每个数据库同步都会显示自己的结果通知
• 检查 frontmatter：验证所有 NotionID 字段都存在且正确（如 NotionID-blog、NotionID-portfolio）

获取帮助

如果问题依然存在，你可以在 GitHub 上提交一个 Issue，并附上详细的错误信息和你的操作步骤，我会尽快帮助你。

你也可以通过 Ctrl+Shift+I (Windows/Linux) 或 Cmd+Option+I (Mac) 打开 Obsidian 的开发者工具，在控制台（Console）中查看是否有与 NotionNext 插件相关的错误日志，这对于定位问题非常有帮助。

提交 Bug 报告时应包含的信息

1. 错误消息：复制通知或控制台中的确切错误消息
2. 控制台日志：包含开发者控制台中的相关日志（查找 [AutoSync]、[Settings] 或 [Plugin] 前缀）
3. 重现步骤：描述问题发生时你正在做什么
4. 配置信息：说明你使用的数据库格式（NotionNext、普通或自定义）
5. 设置信息：注明是否启用了自动同步以及配置的延迟时间