笔记同步助手图床接力功能教程
同步完成后自动把 Obsidian 图片换成你自己图床的链接
用「本地图片」模式同步 Obsidian 后，图片会下载到 vault，笔记里会出现 ![[笔记同步助手/images/xxx.jpg]] 这样的本地链接。
图床接力做的事：把这些本地图片批量上传到你自己的对象存储桶或图床，笔记里的图片链接最后变成 。
两种模式，选一种就好
笔记同步助手提供两种互不影响的接力模式，按你愿意把图床密钥放在哪里来选：
| 模式 | 密钥保存在哪里 | 操作位置 | 适合谁 |
|---|---|---|---|
| 云端接力（推荐） | 由「笔记同步助手」托管（加密保存） | 助手的网页设置面板 | 想一次配好、所有设备都生效；不想在 Obsidian 里再装别的插件 |
| 本地接力 | 完全在你本机的第三方图床插件里 | Obsidian 客户端设置 | 已经在用 PicGo / 自建 HTTP 图床；不希望把密钥交给任何第三方服务 |
两种模式都只对配置之后新整理的笔记生效，存量笔记不会被改动。 两种模式不要同时开启——同一张图片会被上传两次到不同的桶，浪费配额还会让链接来源不一致。
另外，本地接力还有一个可选搭档——「接力前先改名」：同步后先把下载下来的图片从随机文件名改成笔记标题名，再走图床上传；不开图床、只想要整齐的文件名也可以单独开它。见模式二的「接力前先改名」一节。
模式一：云端接力（推荐）
把对象存储的密钥交给「笔记同步助手」托管，助手在云端整理笔记时就把图片直接上传到你的桶里，笔记同步到 Obsidian / 思源 / OneNote / Notion 的时候，图片链接已经是你自己图床的外链了。桌面端、手机端都生效，不依赖任何 Obsidian 插件。
1. 准备一个对象存储桶
目前支持三家：
- 腾讯云 COS
- 七牛云 Kodo
- 阿里云 OSS
到对应控制台开一个 Bucket，记下：
- 存储桶名（COS 含 appid，例如
mybucket-1300000000；OSS 就是 Bucket 名；七牛是「存储空间名称」） - 所属地域（region，例如
ap-guangzhou/cn-hangzhou/cn-east-1） - 一对只对该桶有写权限的子账号 / 子用户密钥（强烈建议，别用主账号密钥）
- 桶要么设为公共读，要么绑一个 CDN 域名——读者要能直接通过 HTTPS 访问图片
七牛云必须有一个绑好的公网访问域名（七牛默认就不提供匿名公网读域名）；腾讯云 / 阿里云不填的话会用默认域
https://<bucket>.cos.<region>.myqcloud.com/https://<bucket>.oss-<region>.aliyuncs.com。
2. 打开设置面板的「图床」标签页
浏览器打开 https://my.bijitongbu.site/settings，输入你的客服代码（在「笔记同步助手」服务号 → 底部菜单「客服」→「客服代码」获取）验证并登录后，顶部切到「图床」标签页：
3. 选「云服务商」并填字段
在「云服务商」下拉里选 腾讯云 COS / 七牛云 Kodo / 阿里云 OSS 之一，下方会按你选的家展开对应的字段：
| 字段 | 腾讯云 COS | 七牛云 Kodo | 阿里云 OSS |
|---|---|---|---|
| 存储桶 | 存储桶名称（含 appid） | 存储空间名称 | Bucket 名称 |
| 地域 region | 例如 ap-guangzhou | 例如 cn-east-1 | 例如 cn-hangzhou |
| 密钥 ID | SecretId | AccessKey | AccessKeyId |
| 密钥 | SecretKey | SecretKey | AccessKeySecret |
| 公网访问域名 | 可选（不填用默认域） | 必填 | 可选（不填用默认域） |
| 桶内路径前缀 | 可选，例如 obsidian-img/ |
填完点「保存」。助手会立刻试着往你的桶里写一张测试文件再读回来——成功才算保存通过，配置一次保存就一次校验，不会让你拿一份错的配置等到下次同步才发现。
校验通不过时会给一条人话提示，常见几种：
- AccessKey 不正确 — 检查密钥 ID 与密钥是否复制完整、是不是同一对
- 密钥没有该存储桶的写入权限 — 给子账号授权
PutObject/GetObject - 存储桶不存在 / region 与存储桶实际所在地域不一致 — 检查 bucket 名和 region
- 图片能上传但公网读不到 — 把桶/对象设成公共读，或填写 CDN 域名
- 「公网访问域名」打不开或内容不匹配 — 检查该域名能否匿名访问
4. 配好后会看到的那段绿色说明
保存成功后页面上会一直显示一段绿色提示：
✅ 图床已启用，配置校验通过（腾讯云 COS ·
<你的桶名>） · 今后新整理的笔记，图片会自动上传到你的存储桶 · 凭据已加密保存，出于安全不再回显 —— 上方密钥两栏显示为空是正常的，无需重填，只有更换密钥时才需要重新输入
这段话最常见的疑问就是「为啥保存完密钥栏空了？」——空的是正常的，不要再填一遍。再填一遍只会触发一次同样的「同时填密钥 ID 和密钥」的校验，等于强制更换密钥。
5. 关于密钥怎么存的（不放心的人请看）
把对象存储密钥交给任何第三方，都是要看托管方怎么放的。「笔记同步助手」是这么做的：
- 加密后落库：密钥写入数据库前用业内标准强加密算法加密一次，数据库里看到的全是密文。
- 加密用的主密钥隔离保管：主密钥独立保存在与业务数据库相互隔离的密钥保险柜里，不进数据库、不进任何日志，连「笔记同步助手」的工程师本人都拿不到明文密钥——拿到数据库快照也只是一堆密文。
- 页面不回显：保存成功后页面把密钥栏清空，只显示一个 4 位指纹（例如
凭据已配置（指纹 a7c3））方便你确认这次保存上的是哪一对，密钥本身不会再被任何接口返回。 - 建议用子账号密钥：哪怕极小概率出事，子账号密钥泄露最多影响这一个桶，且你随时能到云控制台撤销重发。
如果你对「密钥交给第三方」这件事仍然不放心，请用下面的本地接力模式——密钥从头到尾只在你的 Obsidian 客户端里。
6. 想换 / 想停 / 想换一家
- 换密钥：把新的密钥 ID + 密钥两栏都填上，点保存即可（留空 = 不修改）
- 换一家云服务商：「云服务商」下拉切到另一家，把对应字段填完保存
- 临时停用：「云服务商」下拉切回「不启用」，点保存
- 彻底清空：点保存按钮旁边的红色「清除配置」按钮，会二次确认
模式二：本地接力
调用你已经在 Obsidian 里装好的第三方图床插件，笔记同步助手只负责调度，不接触任何图床的配置和凭证。密钥从头到尾在你本机。
🔔 这个功能需要「满血版」插件。「笔记同步助手」在 Obsidian 里有两个发行版本，看第三方插件列表里的名字就能区分：显示中文名「笔记同步助手」的是满血版，功能齐全；从官方插件市场一键安装、显示拼音名「Bi Ji Tong Bu」的是商店版，少一些高级功能——本地图床接力与「接力前先改名」只有满血版提供（上面的云端接力在网页设置里配置，两个版本都能用）。 还没有满血版？照《安装教程》方法一：下载安装包手动安装或方法三：先装 China BRAT 再一键安装装一个即可。
适合谁用
- 已经在用 PicGo / PicList / 自建 HTTP 图床
- 完全不想把对象存储密钥交给任何第三方服务
- 有自己 CDN、希望所有图片走自家域名
支持哪些图床插件
三选一，装好哪个就在笔记同步助手里选哪个：
- Image auto upload (PicGo/PicList) — 本地装了 PicGo 或 PicList 桌面应用时用。社区插件市场搜「Image auto upload」。
- Image Upload Toolkit — 直连 AWS S3 / Cloudinary / 腾讯云 COS / GitHub 时用。社区插件市场搜「Image Upload Toolkit」。
- Obsidian Image Uploader (Creling) — 自定义 HTTP 图床接口时用。社区插件市场搜「Obsidian Image Uploader」。
开启步骤
1. 前置条件
- 桌面版 Obsidian。三个候选图床插件都不支持手机。
- 笔记同步助手「图片处理模式」设置为「本地图片」（LOCAL）。
2. 装好图床插件并配好
各图床插件的配置看各自 README，这里不展开。核心动作：先在图床插件里手动点一次「上传全部图片」，确认能正常传到你的图床，再回来做下一步。没跑通就往下配没有意义。
3. 打开笔记同步助手 → 设置 → 图片处理
往下翻会看到「图床接力」下拉框。选中你装好的那个插件：
下拉框下方会实时显示状态：
- ✅ 已就绪：
<插件名>— 可以用了 - ⚠️ 未启用「
<插件名>」插件 — 去 Obsidian 设置里启用，或先到社区市场装上 - ⚠️ 「
<插件名>」已启用但尚未加载完成 — 等几秒重新打开设置页 - ⚠️ 「
<插件名>」的命令<id>不存在，可能版本不兼容 — 图床插件升级后命令改名了，到笔记同步助手 GitHub 反馈 - ⚠️ 请到「
<插件名>」设置里打开 Replace original document，否则结果只会进剪贴板 — 见下一步
下拉框关闭时（默认）会显示「当前：已关闭（保留本地图片）」。
⚠️ 某些 Obsidian 自定义主题下，「图床接力」下拉框可能完全不显示——像下图这样，「图片处理」分组里只剩「图片处理模式」「PNG 转 JPEG」，中间应该出现的「图床接力」section 被主题样式吃掉了。临时切回默认主题（设置 → 外观 → 主题 → Default）就能看到，配完再切回你喜欢的主题即可（配置已经存进 vault，不受主题影响）。
4. Image Upload Toolkit 用户：务必打开 Replace original document
打开 Image Upload Toolkit 的设置，把「Replace original document」开关打开。不开的话，toolkit 只会把上传后的 URL 放进剪贴板，笔记原文不变，接力等于没做。
笔记同步助手会自动检测这个开关，没开会在状态行里直接提示你，但建议上手就先开好。
5. 所有图床插件：务必关闭「删除源文件」
在 PicGo 类插件里这个开关叫 「Delete Source File / 删除源文件」。
关闭它之后，图床插件上传完会保留本地图片。下次再同步，笔记同步助手看到同样的图还在，会跳过（已经本地化过），皆大欢喜。
要是开了删除源文件，下次同步笔记同步助手会发现本地文件被删了，于是重新下载再次接力上传，白白消耗你的图床配额。
接力前先改名：把图片文件名换成笔记标题（可选）
「下载到本地」存进你库里的图片，文件名默认是一串随机字符——那是插件给每张图算的「指纹」，用来防止重复下载。好处是绝不重名，坏处是打开图片文件夹全是无意义的名字，分不清哪张图属于哪篇笔记。
「接力前先改名」就是解决这个的：同步完成后，自动把本轮新下载图片的文件名改成所在笔记的标题。图片还是本地文件、还在原来的文件夹里，只是名字变整齐了。同一篇笔记有多张图时，插件会自动处理重名（默认加编号），不会互相覆盖。
它有两种用法，选哪种都行：
- 搭配图床上传：先改名、再上传，你图床里的文件名也是整齐的笔记标题；
- 单独使用：图床接力保持「关闭」，只改名、不上传，图片仍是本地链接。
需要「笔记同步助手」3.2.16 及以上版本，以及一个第三方插件（下一步）。
开启步骤
- 装好并启用「Paste image rename」社区插件：Obsidian 设置 → 第三方插件 → 浏览，搜「Paste image rename」安装并启用。它就是专门做图片批量改名的，笔记同步助手只负责在合适的时机调用它。
- 确认一个 Obsidian 自带开关是打开的：设置 →「文件与链接」→「自动更新内部链接」（默认就是开的）。图片改名后，笔记里的引用全靠它跟着更新；它若关着，改完名笔记里的图会全部裂开——所以这一项不开，改名不会开始（见下面状态行的提醒）。
- 打开笔记同步助手设置 →「图片处理」，在「图床接力」下拉框下方找到「接力前先改名（Paste image rename）」开关，打开。
开关下方和图床接力一样有实时状态行：
- ✅ 已就绪：Paste image rename — 可以用了
- ⚠️ 未启用「Paste image rename」插件 — 去社区插件市场装上、或在设置里启用
- ⚠️ 请打开 Obsidian 设置 →「文件与链接」→「自动更新内部链接」 — 照着打开，否则改名后会留下断链
三个如实提醒
- 改名作用于整篇笔记的所有图片：一篇笔记本轮有新下载的图、进入改名流程后，这篇笔记里的全部图片都会被改名——包括你自己手动插入的本地图片（只改文件名，不删除、不移动）。不希望自己的图被动到，就别开这个开关。
- 只在电脑端生效：和图床接力一样，「Paste image rename」不支持手机，手机端同步会自动跳过改名。
- 改名失败不用慌：文件名保持原样（还是那串随机字符），图片链接仍然有效、内容不受任何影响，下一轮同步会再试。手动同步时进度条上会多一个「图片改名」阶段。
同步时会发生什么
开启接力后，文章先保存，图片下载和图床接力继续在后台处理：
- 笔记同步助手把新文章保存到 vault。图片还在下载时，同步完成提示会注明「图片和附件后台处理中」，此时可以继续同步新文章。
- 下载阶段结束后，已落盘的图片进入接力；如果还开启了「接力前先改名」，会先把图片改成笔记标题名、再上传（只开改名不开上传也走这一步）。尚未下载成功的图片保留远程链接，等待后续重试。
- 笔记同步助手会临时新开一个标签页，逐个打开需要接力的笔记、触发图床插件的「上传全部图片」命令，等待链接更新。临时标签页可能获得焦点，原有标签页会保留；整组笔记处理后临时标签页自动关闭。
- 上传成功的图片链接从
![[...]]改成。新一轮同步可以先保存文章，接力任务会依次处理。
单篇笔记按每张图片 4 秒计算等待上限，至少等待 6 秒：一张图 6 秒、两张图 8 秒、三张图 12 秒。到点后继续处理下一篇；这不会取消第三方插件已经发出的上传请求。
接力失败怎么办
某篇笔记接力失败（超时、网络挂了、图床配额满了），笔记同步助手不会中断同步：
- 尚未上传成功的图片保留本地 wiki 链接；按上面的要求关闭「删除源文件」后，vault 里的原图也会保留
- 手动同步触发的接力失败时，Obsidian 会提示「图床接力部分失败，见控制台」（详细的失败原因 + 文件路径在开发者控制台 Console 里）
- 解决网络或配额问题后，打开相应笔记，手动运行所选图床插件的「上传全部图片」命令补上
如果整个接力阶段都没启动（比如插件被禁了 / 命令找不到），会弹一条「🚚 图床接力已跳过：<原因>」，本次同步其他部分不受影响。
常见问题
云端接力和本地接力能同时开吗？
不建议。同一张图会被上传两次到两个不同的图床/桶，浪费配额且让笔记里的图片来源不一致。选一个就好。
能不能在手机上用？
- 云端接力：可以，手机端笔记拉下来时图片链接已经是云端图床外链了，跟桌面端体验一样。
- 本地接力：不能。三个候选图床插件都只支持桌面端。笔记同步助手手机端会自动跳过接力阶段，不影响其它同步动作。
- 接力前先改名：同样不能，手机端自动跳过。
「接力前先改名」能单独开吗（不选图床插件）？
能。它和「图床接力」下拉是两个独立开关：上传选「关闭」+ 改名打开 = 只把图片文件名改成笔记标题，图片仍是本地文件。见上面「接力前先改名」一节。
为什么状态行让我打开「自动更新内部链接」？
那是改名能安全进行的前提。图片文件改名后，笔记里的引用要靠 Obsidian 自带的「自动更新内部链接」跟着更新；这个开关关着就强行改名，笔记里的图会全部裂开。所以笔记同步助手检测到它关着时会拦下改名并提醒你去打开（设置 →「文件与链接」）。这个开关默认是开的，一般只有特意关过的人才会遇到。
选「远端图片」模式能用接力吗？
不需要。远端模式下笔记里本来就是图片的公网 URL，没有要接力的东西。本地接力的下拉选项只在「本地图片」模式下才显示。
想换一个图床插件怎么办？
下拉切到新插件就行。已经上传过的旧图片保持原样（链接还是指向老图床），只有下次同步里新下载到的图片走新图床。
可以同时用多个本地接力图床插件吗？
不行，本地接力下拉只能选一个。确实要分平台走不同图床，建议分 vault。
接力失败会不会连累 AI 整理？
不会。本地接力在文章保存后执行，上传失败不会撤回已保存的笔记。尚未上传成功的图片仍保留本地链接，可以解决网络或配额问题后手动补传。
升级后这个功能默认开启吗？
默认全部关闭。云端接力需要你主动去网页设置面板配置一家云服务商；本地接力需要你主动去 Obsidian 设置里选一个图床插件；接力前先改名也需要你自己打开开关。存量用户升级后行为完全不变。