笔记同步助手 Obsidian 插件安装教程

欢迎！ 这个教程将一步步指导您安装笔记同步助手插件。

不用担心！ 即使您对电脑操作不太熟悉，只要按照步骤操作，就能成功安装。整个过程大约需要 10-15 分钟。

开始前的准备

请确保您已经：

• ✅ 在电脑上安装了 Obsidian 软件
• ✅ 创建了至少一个 Obsidian 笔记库（保管库）
• ✅ 关注了”笔记同步助手”微信公众号

基础概念说明

什么是插件？ 插件是为 Obsidian 添加新功能的小程序，就像手机应用一样，可以让软件做更多事情。

什么是 API 密钥？ API 密钥就像一把钥匙，让插件能够安全地连接到笔记同步助手的服务器获取您的数据。

什么是保管库（库）？ 保管库是您在 Obsidian 中存储所有笔记的文件夹，相当于您的”笔记本”。

安装步骤

第一步：获取插件文件

1. 打开微信，找到”笔记同步助手”公众号
2. 发送消息“Obsidian”
3. 您会收到下载链接和 API 密钥（请保存好 API 密钥，稍后需要用到）
4. 点击链接下载压缩包（文件名类似：obsidian-notehelper-2.1.0.zip）
5. 在电脑上找到下载的压缩包，右键选择”解压”或”提取”
6. 解压后会得到一个文件夹（如：2.1.0）

第二步：在 Obsidian 里打开插件文件夹

1. 打开 Obsidian
2. 点击左下角的设置图标（⚙️ 齿轮状）

3. 在左侧菜单里向下滚动，找到”第三方插件”，点击它
   • 💡 这个选项在”核心插件”下方
4. 找到”安全模式”开关，把它关掉
   • ✅ 关掉后会显示”安全模式已关闭”
   • 💡 关掉之后 Obsidian 才允许加载第三方插件
5. 继续往下滚，找到”已安装插件”这一行
6. 点这一行右侧的文件夹图标（鼠标悬停会显示”打开插件文件夹”）
7. 系统会自动弹出文件管理器，直接定位到您的插件文件夹 —— 不用自己找路径

⚠️ 如果您从来没装过任何插件，这个页面长得可能不是上面那张图，而是下面这张 —— 只看到”插件安装情况：你目前已经安装了 0 个插件”，右侧没有刷新和文件夹图标：

如果您看到的是上面这张「0 个插件」的样子，请展开下面的折叠内容，按兜底方案手动定位到 plugins 文件夹。

看不到文件夹图标？点这里展开兜底方案（手动找到 plugins 文件夹）

不用关掉 Obsidian。我们利用 Obsidian 自带的”在系统中显示”右键菜单，直接跳到笔记库所在的目录，再手动进 .obsidian/plugins。

1. 在 Obsidian 左侧文件列表里任选一篇笔记（哪一篇都行，新建一篇空笔记也可以），在它的名字上点右键
2. 在弹出的菜单里点 “在系统资源管理器中显示”（Windows）或 “在访达中显示”（Mac）
   • 💡 不同版本菜单文字略有差异，也可能写成”Show in system explorer”/“Reveal in Finder”，意思一样
3. 系统会弹出文件管理器，并高亮选中刚才那篇笔记的 .md 文件
4. 在文件管理器里回到上一级（也就是您的笔记库根目录），找一个名为 .obsidian 的文件夹
   • ❌ Windows 上看不到 .obsidian：在文件管理器顶部勾选”查看 → 隐藏的项目”（或按 Ctrl + H）
   • ❌ Mac 上看不到 .obsidian：按 Cmd + Shift + .（点号）切换显示隐藏文件
5. 双击进入 .obsidian，里面应该有一个 plugins 文件夹
   • ❌ 如果没有 plugins 文件夹：在空白处右键，新建一个文件夹并命名为 plugins
6. 双击进入 plugins —— 这就是您要找的”插件文件夹”，下一步把解压出的文件夹拖到这里

💡 之后只要装好任何一个插件，回到 Obsidian 设置页面，“已安装插件”右侧就会出现刷新和文件夹图标，往后再装新插件就可以走上面的一键方式了。

第三步：把插件文件放进去

1. 把第一步解压出来的文件夹整个拖（或复制）到刚才弹出的窗口里
   • 💡 文件夹叫什么名字都不重要，叫 2.1.0、obsidian-notehelper-2.1.0、my-plugin 都行 —— 关键是层级
2. 拖完后，结构应该是这样：

plugins/
└── 任意文件夹名/        ← 这层叫什么都行
    ├── main.js          ← 但这几个文件必须直接在这层下面
    ├── manifest.json    ← 不能再多套一层
    ├── styles.css
    └── 其他文件...

⚠️ 最常见的错误：解压时有些电脑会多套一层同名文件夹，变成 plugins/2.1.0/2.1.0/main.js 这种双层套娃。这时 Obsidian 找不到插件。 解决：进到最里面那一层（能直接看到 main.js 的那层），把这一层的文件夹拖出来到 plugins/ 下，再把外面的空壳文件夹删掉。

第四步：在 Obsidian 中启用插件

1. 回到 Obsidian 的第三方插件设置页面（如果关了就重新打开）
2. 在”已安装插件”这一行右侧的刷新图标（就在刚才那个文件夹图标旁边）点一下
3. 您应该能看到”笔记同步助手”插件，右侧有一个灰色的开关
   • ❌ 如果看不到：请返回上一步检查文件夹层级，或者直接重启 Obsidian

4. 点击这个灰色开关把它打开
   • ✅ 开关变成紫色就是启用成功

第五步：配置 API 密钥

1. 在左侧菜单”第三方插件”区域找到并点击”笔记同步助手”，进入插件设置页面

2. 找到”API Key”输入框
3. 将第一步获取的 API 密钥粘贴到这个框中
4. 点击”保存”或直接关闭设置页面（会自动保存）

第六步：添加微信“Obsidian”好友

第一步公众号回复给您的那条消息（含下载链接和 API 密钥）最下方还有一张图片——这张图片就是用来添加微信“Obsidian”好友的入口。

1. 回到微信「笔记同步助手」公众号的对话界面，找到第一步收到的那条消息
2. 点开消息底部的图片（图片下方有”点开这个图片 添加 Obsidian 好友”提示）
3. 在弹出的页面里按提示添加好友（备注通常是”笔记同步科技”）

💡 公众号只负责推送处理通知，真正接收您发送内容的是微信“Obsidian”好友。两个一起用，缺一不可。

成功确认

如果看到以下情况，说明插件安装到位：

• ✅ 插件在”已安装插件”列表中显示为”已启用”
• ✅ Obsidian 左侧工具栏出现笔记同步助手图标（“同”字图标）
• ✅ API 密钥已填写并保存

第一次同步：跑一遍完整流程

插件装好之后，建议立刻按下面 3 步走一遍——发送内容 → 看通知 → 在 Obsidian 点同步，确认整条链路通了。

1. 给微信“Obsidian”好友发送一条内容

打开微信，进入和微信“Obsidian”好友（您在前面流程里添加的、备注通常是”笔记同步科技”）的聊天窗口，把任意一条想保存的链接、文章或文字直接发到对话框里。

💡 内容发给微信“Obsidian”好友；处理通知则由「笔记同步助手」公众号推送。两个一起用，缺一不可。

2. 等待两条同步通知

发送后稍等几秒，「笔记同步助手」公众号会按顺序推送 2 条通知：

• 📬 工单已开始处理通知 —— 表示已经收到您的内容，开始处理
• ✅ 工单完成通知 —— 处理结果显示「笔记已同步」，就代表云端已就绪

💡 看到「笔记已同步」就说明云端已经把这条内容存好了，剩下的只是把它拉到本地 Obsidian。

3. 回到 Obsidian，点击左侧「同」图标

看到「工单完成通知」后，回到 Obsidian，点击左侧工具栏顶部的 「同」字图标 —— 这是笔记同步助手的同步按钮。

点击后，刚才发送的内容就会作为一篇笔记出现在您的 Obsidian 库里。之后凡是发给微信“Obsidian”好友的内容，都按这个流程走：发送 → 收到完成通知 → 回 Obsidian 点「同」拉到本地。

不想每次手动点同步？开启自动同步

如果觉得每次都要去点「同」字图标麻烦，可以在插件设置里让 Obsidian 自动同步：

1. 在 Obsidian 左下角 ⚙️ 设置 → 第三方插件 → 点击「笔记同步助手」进入插件设置页面
2. 找到「同步」分组，里面有两个常用选项：
   • 启动时同步（本设备） —— 勾选后，每次打开 Obsidian 自动跑一次同步，再不用手点
   • 频率（本设备） —— 填入秒数即可定时同步（0 表示关闭定时；最低 15 秒）。常用值：60（1 分钟）/ 300（5 分钟）/ 1800（30 分钟）

💡 这两个选项是按设备独立保存的 —— 每台电脑/手机可以设不同的策略。比如桌面端设 300 秒定时拉、手机端只勾”启动时同步”，互不打架。

最常见的搭配：“启动时同步”+“频率 = 300 秒”，开 Obsidian 立刻拉一次，之后每 5 分钟自动收新笔记，全程零手动。

让 AI 帮你改插件设置？先把这页发给 AI

如果你打算请 Claude / ChatGPT / Gemini / 豆包 / DeepSeek 等 AI 助手帮你改笔记同步助手的插件设置（例如改文件路径、模板、合并模式等），请务必先把下面这条 URL 复制粘贴给 AI，让它先读完里面的字段表和约束，再动手：

https://www.bijitongbu.site/tutorials/ai-settings-guide/

里面对每个可改字段、可选值、默认值、危险红线都做了完整说明，能避免 AI 凭”听起来合理”自创字段（实测过去出现过 AI 写出 after:{{{lastSyncTime}}} 这种插件不认识的查询，导致点同步看着成功但 0 篇文章落盘）。

💡 把这条 URL 当成”给 AI 的入门 Skill”。先发 URL，再说需求，比如：“请先读 https://www.bijitongbu.site/tutorials/ai-settings-guide/ ，然后帮我把笔记按年月分文件夹”。

遇到问题怎么办？

常见问题解决

Q: 找不到”打开插件文件夹”的图标 A: 必须先把”安全模式”关掉才会出现”已安装插件”这一行（以及右侧的文件夹/刷新图标）。如果还是看不到，关掉设置页面再重新打开一次。

Q: 插件没有出现在列表中 A: 99% 是文件层级放错了，和文件夹叫什么名字没关系。请按下面的顺序检查：

1. 回到刚才打开的插件文件夹（如果关掉了，重新走一遍第二步），里面必须有一个您拖进去的文件夹（名字随便）
2. 进到这个文件夹里，要能直接看到 main.js、manifest.json、styles.css 这几个文件
3. ❌ 如果点开后里面又是一个文件夹（双层套娃，比如 2.1.0/2.1.0/main.js），Obsidian 就找不到插件。把最里面那一层文件夹拖出来到外层，再把空壳删掉
4. 检查完层级，回 Obsidian 设置页面点”已安装插件”右侧的刷新图标（或重启 Obsidian）就能看到插件了

Q: 同步不成功 / 没反应 / 想全量重新拉一次 A: 同步类问题（网络、配置、清空 Sync At 重新拉历史等）请看 同步不成功排查教程，里面有完整的排查步骤。

---

接下来：进阶配置和功能

插件装好之后，下面这些教程会带您把它用得更顺手：

配置常用选项

• 路径配置教程 —— 改默认存储路径、按日期 / 分类拆文件夹
• 二级目录设置教程 —— 把不同来源（公众号、内容平台、日记…）放进不同子文件夹
• Frontmatter / 笔记属性模板配置 —— 自定义每篇笔记最上面的属性区
• 模板变量完全指南 —— 所有可用变量（title、author、date_saved…）一览
• 备注及标签功能 —— 给保存的内容加备注和标签
• 合并消息模式 —— 一天一个文件 vs 一篇一个文件

用得更高级

• 跳过 AI 整理功能 —— 哪些链接只存原始消息、不走 AI 整理
• 仅保存链接的网站配置 —— 长期把某些站点设为只存链接
• 邮件收藏功能 —— 用邮箱也能保存内容
• 日记链接功能 —— 自动把当天保存的内容链到日记里
• 图床接力功能 —— 让外链图片在 Obsidian 里也能稳定显示

遇到问题

• 同步不成功排查教程 —— 同步失败 / 没反应 / 想清空重拉
• 重置密钥教程 —— API Key 失效或想换一把
• 手机端 BRAT 安装教程 —— 在 iOS / Android 上装这个插件
• 常见使用问题汇总 —— 综合 FAQ

技术支持

如需技术支持，请：

1. 关注微信公众号”笔记同步助手”
2. 发送消息”客服”
3. 收到回复后发送”人工”转接人工客服
4. 向客服详细描述您遇到的问题

安全说明

笔记同步助手只处理你主动发送给助手的内容（图文 / 视频 / 链接 等），且整条链路单向——只把这些内容写入你本地的 Obsidian 库，不会主动抓取任何平台数据，也不会读取或上传你本地已有的笔记内容。数据流向如下：

你主动发送给助手的内容（图文 / 视频 / 链接 / …）
        │
        ▼
   笔记同步助手
        │
        ▼
   你的本地 Obsidian 库   ← 数据只在这一端落地

插件代码完全开源：github.com/notesynchelper/obsidian-notehelper。

如果你对数据安全还有顾虑，可以直接把 main.js 下载下来丢给任何 AI（Claude / ChatGPT / Gemini 等）做安全审查，让 AI 帮你检查有没有可疑的上传请求或读取本地文件的逻辑。事实上插件代码已经被无数用户、安全研究者和 AI 反复审查过——欢迎你自行验证。

---

感谢使用笔记同步助手！如果您觉得插件有用，欢迎推荐给更多朋友使用。