mirror of
https://github.com/jxpeng98/obsidian-to-NotionNext
synced 2026-07-29 08:08:34 +08:00
docs: enhance auto sync documentation with detailed setup, scenarios, and troubleshooting guidance
This commit is contained in:
Jiaxin Peng
@@ -7,6 +7,90 @@ description: 如何使用 NotionNext 插件将你的 Obsidian 笔记同步到 No
|
||||
|
||||
在插件设置中配置好你的 Notion 数据库后，你就可以开始将 Obsidian 笔记同步到 Notion 了。
|
||||
|
||||
要同步一篇笔记，只需打开你想要同步的笔记，然后从命令面板（`Ctrl/Cmd + P`）或笔记的右键菜单中选择 “Share to NotionNext” 命令。这会在你的 Notion 数据库中创建一个新页面，内容与你的 Obsidian 笔记完全一致。
|
||||
## 手动同步
|
||||
|
||||
你还可以为特定的笔记或文件夹设置自动同步。这样，你在 Obsidian 中对这些笔记所做的任何更改，都会自动反映到 Notion 中，非常方便。
|
||||
要同步一篇笔记，只需打开你想要同步的笔记，然后从命令面板（`Ctrl/Cmd + P`）或笔记的右键菜单中选择 "Share to NotionNext" 命令。这会在你的 Notion 数据库中创建一个新页面，内容与你的 Obsidian 笔记完全一致。
|
||||
|
||||
## 自动同步
|
||||
|
||||
插件支持自动同步功能，可以监控你的笔记变化并自动同步到 Notion。
|
||||
|
||||
### 启用自动同步
|
||||
|
||||
1. 打开插件设置
|
||||
2. 在通用设置下找到"自动同步"开关
|
||||
3. 开启该开关
|
||||
4. 配置"自动同步延迟时间"（默认：5秒，最小：2秒）
|
||||
|
||||
### 自动同步工作原理
|
||||
|
||||
当自动同步启用后：
|
||||
|
||||
- 插件会监控 Markdown 文件的变化
|
||||
- 在你停止编辑达到配置的延迟时间后，自动触发同步
|
||||
- 只有已经同步过的文件（frontmatter 中有 NotionID）才会被自动同步
|
||||
- 如果文件关联了多个数据库，会自动同步到所有数据库
|
||||
|
||||
### 自动同步场景示例
|
||||
|
||||
#### 场景 A：新文档（未同步）
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: 我的新文章
|
||||
tags: [博客, 技术]
|
||||
---
|
||||
```
|
||||
|
||||
**行为：**
|
||||
|
||||
- ✅ 检测到没有 NotionID
|
||||
- ✅ 显示提示："⚠️ 自动同步跳过：此文档未同步到 Notion，请先手动上传"
|
||||
- ✅ 不执行同步操作
|
||||
- 📝 **需要操作：** 先使用命令面板手动同步文档
|
||||
|
||||
#### 场景 B：已同步到一个数据库
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: 我的文章
|
||||
NotionID-blog: abc123
|
||||
---
|
||||
```
|
||||
|
||||
**行为：**
|
||||
|
||||
- ✅ 检测到 1 个 NotionID
|
||||
- ✅ 自动同步到 Blog 数据库
|
||||
- ✅ 显示上传命令返回的成功/失败通知
|
||||
- 📝 **无需操作：** 变更会自动同步
|
||||
|
||||
#### 场景 C：同步到多个数据库
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: 我的文章
|
||||
NotionID-blog: abc123
|
||||
NotionID-portfolio: def456
|
||||
NotionID-notes: ghi789
|
||||
---
|
||||
```
|
||||
|
||||
**行为：**
|
||||
|
||||
- ✅ 检测到 3 个 NotionID
|
||||
- ✅ 显示提示："🔄 自动同步：正在同步到 3 个数据库..."
|
||||
- ✅ 依次同步到所有 3 个数据库
|
||||
- ✅ 为每个数据库显示独立的结果通知
|
||||
- 📝 **无需操作：** 变更会自动同步到所有关联的数据库
|
||||
|
||||
### 自动同步最佳实践
|
||||
|
||||
1. **首次手动同步**：始终先手动执行第一次同步以建立 NotionID 链接
|
||||
2. **合理配置延迟**：如果你经常编辑，设置较长的延迟时间（5-10 秒）
|
||||
3. **监控同步状态**：注意查看通知以确保同步成功完成
|
||||
4. **查看日志**：打开开发者控制台（Ctrl+Shift+I / Cmd+Option+I）查看详细的同步日志
|
||||
|
||||
### 故障排除
|
||||
|
||||
遇到自动同步问题？请查看[问题排查指南](05-troubleshooting.md)获取常见问题的详细解决方案。
|
||||
|
||||
@@ -5,6 +5,70 @@ description: Obsidian to NotionNext 插件的常见问题与解决方案
|
||||
|
||||
# 问题排查
|
||||
|
||||
## 自动同步问题
|
||||
|
||||
### 自动同步不工作？
|
||||
|
||||
**可能的原因及解决方案：**
|
||||
|
||||
- **未启用自动同步**：确保在插件设置的通用设置中启用了自动同步功能
|
||||
- **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](https://github.com/jxpeng98/obsidian-to-NotionNext/issues)，并附上详细的错误信息和你的操作步骤，我会尽快帮助你。
|
||||
|
||||
你也可以通过 `Ctrl+Shift+I` (Windows/Linux) 或 `Cmd+Option+I` (Mac) 打开 Obsidian 的开发者工具，在控制台（Console）中查看是否有与 NotionNext 插件相关的错误日志，这对于定位问题非常有帮助。
|
||||
|
||||
### 提交 Bug 报告时应包含的信息
|
||||
|
||||
1. **错误消息**：复制通知或控制台中的确切错误消息
|
||||
2. **控制台日志**：包含开发者控制台中的相关日志（查找 `[AutoSync]`、`[Settings]` 或 `[Plugin]` 前缀）
|
||||
3. **重现步骤**：描述问题发生时你正在做什么
|
||||
4. **配置信息**：说明你使用的数据库格式（NotionNext、普通或自定义）
|
||||
5. **设置信息**：注明是否启用了自动同步以及配置的延迟时间
|
||||
|
||||
Reference in New Issue
Block a user