Obsidian 插件安装教程 · Obsidian 教程

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

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

开始前的准备

请确保您已经：

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

基础概念说明

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

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

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

安装步骤

第一步：获取插件文件

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

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

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

点 Obsidian 左下角齿轮 ⚙️ 进入 Obsidian 设置

在左侧菜单里向下滚动，找到”第三方插件”，点击它

- 💡 这个选项在”核心插件”下方

找到”安全模式”开关，把它关掉

- ✅ 关掉后会显示”安全模式已关闭” - 💡 关掉之后 Obsidian 才允许加载第三方插件

继续往下滚，找到”已安装插件”这一行
点这一行右侧的文件夹图标（鼠标悬停会显示”打开插件文件夹”）
系统会自动弹出文件管理器，直接定位到您的插件文件夹 —— 不用自己找路径

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

插件安装情况显示「你目前已经安装了 0 个插件」，右侧没有刷新和文件夹图标，这种情况下没法一键跳到插件文件夹，需要走下面的兜底方案

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

<details class="fallback-details"><summary>看不到文件夹图标？点这里展开兜底方案（手动找到 plugins 文件夹）</summary>不用关掉 Obsidian。我们利用 Obsidian 自带的”在系统中显示”右键菜单，直接跳到笔记库所在的目录，再手动进 <code>.obsidian/plugins</code>。<ol><li>在 Obsidian 左侧文件列表里任选一篇笔记（哪一篇都行，新建一篇空笔记也可以），在它的名字上点右键</li><li>在弹出的菜单里点 “在系统资源管理器中显示”（Windows）或 “在访达中显示”（Mac）<ul><li>💡 不同版本菜单文字略有差异，也可能写成”Show in system explorer”/“Reveal in Finder”，意思一样</li></ul></li><li>系统会弹出文件管理器，并高亮选中刚才那篇笔记的 <code>.md</code> 文件</li><li>在文件管理器里回到上一级（也就是您的笔记库根目录），找一个名为 <code>.obsidian</code> 的文件夹<ul><li>❌ Windows 上看不到 <code>.obsidian</code>：在文件管理器顶部勾选”查看 → 隐藏的项目”（或按 <code>Ctrl + H</code>）</li><li>❌ Mac 上看不到 <code>.obsidian</code>：按 <code>Cmd + Shift + .</code>（点号）切换显示隐藏文件</li></ul></li><li>双击进入 <code>.obsidian</code>，里面应该有一个 <code>plugins</code> 文件夹<ul><li>❌ 如果没有 <code>plugins</code> 文件夹：在空白处右键，新建一个文件夹并命名为 <code>plugins</code></li></ul></li><li>双击进入 <code>plugins</code> —— 这就是您要找的”插件文件夹”，下一步把解压出的文件夹拖到这里</li></ol><blockquote>💡 之后只要装好任何一个插件，回到 Obsidian 设置页面，“已安装插件”右侧就会出现刷新和文件夹图标，往后再装新插件就可以走上面的一键方式了。</blockquote></details>

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

把第一步解压出来的文件夹整个拖（或复制）到刚才弹出的窗口里

- 💡 文件夹叫什么名字都不重要，叫 2.1.0、obsidian-notehelper-2.1.0、my-plugin 都行 —— 关键是层级

拖完后，结构应该是这样：

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

⚠️ 常见错误 ①：零层（最常发生）—— 把三个文件直接放到了 plugins/ 下，没套文件夹

plugins/
├── main.js          ❌ 错：这三个文件不能直接放在 plugins 下
├── manifest.json    ❌ 错：Obsidian 不识别，看不到插件
└── styles.css       ❌ 错

解决：在 plugins/ 下新建一个文件夹（名字随便，比如 notehelper），把这三个文件剪切进去，结构变成 plugins/notehelper/main.js、plugins/notehelper/manifest.json、plugins/notehelper/styles.css，再回 Obsidian 点刷新就能看到了。

⚠️ 常见错误 ②：双层套娃 —— 解压时多套了一层

变成 plugins/2.1.0/2.1.0/main.js 这种结构，Obsidian 也找不到插件。解决：进到最里面那一层（能直接看到 main.js 的那层），把这一层的文件夹拖出来到 plugins/ 下，再把外面的空壳文件夹删掉。

💡 一句话记住：plugins/ 下必须正好一层文件夹，里面才是 main.js 等文件 —— 多一层（套娃）或少一层（直接放）都不行。

第四步：在 Obsidian 中启用插件

回到 Obsidian 的第三方插件设置页面（如果关了就重新打开）
在”已安装插件”这一行右侧的刷新图标（就在刚才那个文件夹图标旁边）点一下
您应该能看到”笔记同步助手”插件，右侧有一个灰色的开关

- ❌ 如果看不到：请返回上一步检查文件夹层级，或者直接重启 Obsidian

笔记同步助手出现在已安装插件列表里，右侧的开关默认是灰色（未启用）状态，箭头指向这个开关

点击这个灰色开关把它打开

- ✅ 开关变成紫色就是启用成功

点击后开关变成紫色，左侧出现一个 ⊕ 图标，表示插件已启用

第五步：配置 API 密钥

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

在「第三方插件」里找到「笔记同步助手」点开

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

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

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

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

「笔记同步助手」公众号回复的开通消息：含安装包下载链接、API 密钥、安装教程链接，最下方有一张图片，点开它即可添加微信「Obsidian」好友

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

成功确认

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

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

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

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

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

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

在微信"Obsidian"好友的聊天窗口发送一条内容（例如公众号文章链接，或一段文字）

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

2\. 等待两条同步通知

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

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

先收到「工单已开始处理通知」，几秒后再收到「工单完成通知」（处理结果：笔记已同步）

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

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

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

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

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

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

在 Obsidian 左下角 ⚙️ 设置 → 第三方插件 → 点击「笔记同步助手」进入插件设置页面
找到「同步」分组，里面有两个常用选项：

- 启动时同步（本设备） —— 勾选后，每次打开 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% 是文件层级放错了，和文件夹叫什么名字没关系。请按下面的顺序检查：

回到刚才打开的插件文件夹（如果关掉了，重新走一遍第二步），里面必须有一个您拖进去的文件夹（名字随便）
进到这个文件夹里，要能直接看到 main.js、manifest.json、styles.css 这几个文件
❌ 零层错误（最常见）：如果 plugins/ 下直接就是 main.js/manifest.json/styles.css，没有外层文件夹包着，Obsidian 也找不到插件。在 plugins/ 下新建一个文件夹（叫什么都行，例如 notehelper），把这三个文件剪切进去
❌ 双层套娃：如果点开后里面又是一个文件夹（比如 2.1.0/2.1.0/main.js），Obsidian 同样找不到。把最里面那一层文件夹拖出来到外层，再把空壳删掉
检查完层级，回 Obsidian 设置页面点”已安装插件”右侧的刷新图标（或重启 Obsidian）就能看到插件了

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

* * *

接下来：进阶配置和功能

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

配置常用选项

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

用得更高级

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

遇到问题

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

技术支持

如需技术支持，请：

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

安全说明

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

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

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

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