Joplin 版笔记同步助手安装与使用教程（实验室）
Joplin 版笔记同步助手安装与使用教程（实验室）
🧪 实验室功能：Joplin 版插件为实验版本，通过「从文件安装」方式安装（暂未上架 Joplin 插件市场）。功能与稳定性会持续打磨，欢迎试用反馈。
装上它之后，你在微信里发给「笔记同步助手」的链接、公众号文章、剪藏内容，会自动整理好 同步成 Joplin 笔记，落在你指定的笔记本里——和 Obsidian 版共用同一个云空间、同一把密钥， 在哪端收藏都一样。
一、开始之前
- Joplin 桌面版 3.6 及以上（本插件在 3.6.15 上开发与验证）。
- 准备好你的密钥：关注《笔记同步助手》公众号即可获取，和 Obsidian / 思源版插件里填的是 同一把。
Joplin 和 Obsidian 有个根本区别：Joplin 的笔记存在它自己的数据库里，没有”一篇笔记对应一个 文件”的概念。所以在这个插件里，Obsidian 版的「文章文件夹」对应 Joplin 的笔记本， 「文件名」对应笔记标题。下面会分别说。
二、安装插件（3 步）
-
下载插件文件：点此下载 com.bijitongbu.note-sync-helper.jpl。 下载下来是一个
.jpl文件，不用解压。 -
打开插件页面：Joplin 菜单 工具 → 选项 → 插件（macOS 是 Joplin → 偏好设置 → 插件）， 点下方的 「显示高级选项」，会看到 「从文件安装」。
-
选中刚下载的
.jpl文件安装。装好后「笔记同步助手」会出现在插件列表里并已启用。 按提示 重启 Joplin 一次即可生效。
三、填写密钥
重启后回到 选项，左侧栏最下方的「插件」分组里会多出 「笔记同步助手」，点进去。
- 密钥 — 粘贴你的专属密钥。
- 同步服务地址 — 保持默认即可。连接失败时插件会自动尝试备用地址；只有你自己填了地址， 才会只用你填的那个。
🔒 密钥只保存在你自己的电脑上，不会写进笔记，也不会出现在日志里。
四、设置保存位置（重点）
- 文章笔记本路径模板 — 文章保存到哪个笔记本。用
/分隔多级笔记本，不存在时会自动创建。 默认笔记同步助手/{{{date}}}；想按年月归档就写笔记同步助手/{{{yearSaved}}}/{{{monthSaved}}}。 ⚠️ 这里填的是 Joplin 里的笔记本，不是电脑上的文件夹。 - 笔记标题模板 — 同步后每条笔记的标题，默认
{{{title}}}；想带日期就写{{{dateSaved}}}-{{{title}}}。 - 文章笔记本日期格式 / 笔记标题日期格式 — 上面两处日期变量各自的显示方式，默认
yyyy-MM-dd。
可用变量（{{{title}}}、{{{dateSaved}}}、{{{yearSaved}}}、{{{monthSaved}}}、
{{{daySaved}}} 等）与 Obsidian 版一致，完整清单见
模板变量指南。
五、元数据与模板
设置页里有两项决定”信息怎么存”：
- 前置元数据模式 — 作者、来源、标签、时间这些信息保存在哪里：
- 保存为 Joplin 自带信息（推荐） — 写进 Joplin 原生的来源网址、时间、标签等字段， 正文保持干净。
- 写进正文的前置元数据 — 这些信息会显示在笔记开头。
- 保存为 Joplin 自带信息并写进正文 — 两者都要。
- 已有笔记处理策略 — 再次同步同一篇文章时，如何对待你已经改过的正文： 保留你的修改（默认） / 用最新内容替换正文 / 不处理已有笔记。
想改每篇笔记具体写什么，走 工具 → 笔记同步助手：编辑模板，会打开模板设置窗口：
- 文章内容模板 — 正文长什么样，
{{{content}}}是整理好的文章内容，你可以在前后加固定内容 （默认模板就在正文上方放了作者、来源、标签的信息块）。 - 前置元数据模板 — 前置元数据的字段。
- 窗口底部有变量速查，列出了可用变量和文字/日期转换函数；保存时会自动检查模板写得对不对。
六、图片与附件
图片处理可以选 「保留原始链接（默认）」、「下载并保存到本地」 或 「不加载图片」。 选下载后，图片会存成 Joplin 的本地附件，断网也能看。
打开 「附件处理」 还能把正文里的 PDF、文档、压缩包、音视频一并下载保存到本地。
如果某张图片确实已经失效，插件会在有限次数内重试，然后保留它的网络链接继续往下走—— 不会因为一张坏图卡住整篇笔记，更不会卡住后面的笔记。
七、开始同步
在插件设置页把密钥和位置填好后点 「确认」 保存。之后在 工具 菜单里能看到这几条命令：
- 笔记同步助手：拉取文章 — 立即同步一次。
- 笔记同步助手：查看最后同步 — 回看上次的同步结果。
- 笔记同步助手：继续下载图片与附件 — 上次没下完的接着下。
- 笔记同步助手：编辑模板 — 打开上面那个模板设置窗口。
想让它自动跑，回设置页设置：
- 频率（本设备） — 自动同步间隔（秒）。
0表示只手动同步；最低 60 秒。 - 启动时同步（本设备） — 每次启动 Joplin 自动同步一次。
这两项只对当前设备生效，换台电脑要各设一次。
同步完成后会弹出中文摘要，告诉你这次处理了多少条、新增多少、更新多少、跳过多少：
同步过来的文章会按你设置的路径自动建好多级笔记本：
打开任意一篇，正文、标签、来源链接都在：
重复同步不会产生重复笔记——插件按同步编号识别每篇文章，第二次同步只会更新，不会再新建一份：
常见问题
Q：找不到「从文件安装」？ A：它藏在插件页面下方的 「显示高级选项」 里，点开才会出现。
Q：装完设置里没有「笔记同步助手」？ A：重启一次 Joplin。Joplin 的插件需要重启后才完全加载。
Q：为什么这里叫「笔记本」不叫「文件夹」？ A：Joplin 的笔记存在自己的数据库里，没有”一篇笔记 = 一个文件”的对应关系。所以路径模板 控制的是 Joplin 里的笔记本层级（会自动创建），而不是你硬盘上的目录。
Q：会不会覆盖我自己改过的笔记？ A：默认策略是「保留你的修改」，插件不会覆盖你编辑过的正文。你也可以在设置里改成始终覆盖 或跳过。
Q：重复同步会不会出现两份？ A：不会。插件按同步编号去重，第二次只更新不新建。
Q：和 Obsidian 版是同一个云空间吗？ A：是。同一把密钥、同一批内容，两边都装就两边都有。
Q：密钥会上传到哪里？ A：只保存在你自己的电脑上，随请求发送用于身份验证，不会写进笔记，也不会出现在日志里。
实验室版本欢迎试用反馈，有问题可以在服务号里联系人工客服。