Obsidian插件系列-ImageManager图床上传管理指南
Obsidian插件系列-ImageManager图床上传管理指南
自制 Obsidian 插件 Image Manager 的完整使用文档——笔记图片一键直传 CloudFlare-ImgBed 图床、整个文件夹批量上传、链接自动替换、本地图片安全清理。插件每次更新，这篇文档同步更新。
前言
Image Manager 是我自己写的 Obsidian 插件，专门打通”写笔记 → 图片上库 → 发布博客”这条链路。
它之前走的是 PicList 中转方案（Obsidian → 本地 PicList → 图床），但坑不少：批量传完一个笔记后切到下一个文件再执行命令，经常点了没反应；中间还多依赖一个常驻软件。后来我把插件重写成直连 CloudFlare-ImgBed 图床的 API，PicList 彻底退役。
这篇是我的查阅文档：功能、设置、操作、安全机制、排错都在这。插件每次有新功能或功能修改，我都会同步更新这篇。
功能一览
| 功能 | 入口 | 说明 |
|---|---|---|
| 上传当前笔记的图片 | 命令面板：上传图片到图床 | 单篇笔记，图片直传图床，链接自动替换 |
| 批量上传文件夹 | 命令面板：批量上传文件夹图片到图床，或文件树右键文件夹 | 递归处理文件夹（含子文件夹）下所有笔记 |
| 下载网络图片到本地 | 命令面板：下载网络图片到本地 | 反向操作：网图下载到笔记同目录 assets/ |
| 上传后自动删除本地图 | 设置开关（默认开启） | 只删本次成功上传的，移入系统回收站 |
一、设置项说明
设置位置：Obsidian 设置 → 第三方插件 → Image Manager。
图床上传设置（CloudFlare-ImgBed 直连）
| 设置项 | 我的配置 | 说明 |
|---|---|---|
| 图床地址 | https://img.tsh520.cn | 图床站点地址，末尾带不带 / 都行（插件会自动处理） |
| 管理员账号 | （图床后台的用户名） | 用于调用图床登录接口换取会话 |
| 管理员密码 | （图床后台的密码） | 同上 |
| 上传目录 | blog/article | 图片在图床内存放的相对路径，和博客文章现有图片的目录保持一致 |
| 文件命名方式 | 保留原文件名 | 传上去还是 p001_1.webp 这种原名；重名时图床自动加 (1) 后缀 |
| 上传渠道 | 留空 | 留空使用图床后台配置的默认存储渠道；也可指定 telegram / cfr2 / s3 等 |
| 上传成功后删除本地图片 | 开启 | 详见第四节，有一整套防误删机制 |
下载设置
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 下载目录名 | assets | 网络图片下载到笔记同目录下的这个文件夹 |
| 下载超时时间（秒） | 30 | 单张图片下载的最大等待时间 |
通用设置
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 上传间隔（毫秒） | 200 | 连续上传两张图之间的间隔，避免图床限流 |
| 日志级别 | 仅错误 | 排查问题时可改成”详细”，日志输出到控制台（Ctrl + Shift + I） |
二、上传当前笔记的图片
- 打开一篇含本地图片（
或![[xxx.webp]]）的笔记 Ctrl + P→ 执行Image Manager: 上传图片到图床- 右上角出现”⬆️ 开始上传…”进度条，逐张直传
- 完成后弹窗汇总：
✅ 成功 N 张 / 🗑️ 已删除本地图片 N 张
笔记里的链接会被自动替换成图床真实地址，例如：
上传前：上传后：三、批量上传整个文件夹
一篇一篇传太慢，批量功能一次处理一个文件夹：
- 方式 A：
Ctrl + P→批量上传文件夹图片到图床→ 在弹出的搜索框里输入文件夹名（如MySQL-运维篇）回车 - 方式 B：左侧文件树右键任意文件夹 → “上传此文件夹的图片到图床”
批量行为：
- 递归处理该文件夹（含子文件夹）下所有 Markdown 笔记
- 全程共用一次登录（会话过期自动重登），右上角显示总进度：
⬆️ 批量上传 (3/7) - 没有本地图片的笔记自动跳过，不弹窗打扰
- 每篇完成自动替换链接 + 按设置删除本地图片
- 结束后统一汇总：
✅ 上传 X 张（Y 篇笔记）/ 🗑️ 已删除 Z 张 / ❗ N 条错误 - 失败详情（哪篇哪张）在控制台（
Ctrl + Shift + I→ Console）里看，搜[Image Manager]
四、上传成功后自动删除本地图片（安全机制）
上传完成后，插件可以把对应的本地图片删掉（省得手动清 assets）。因为删除是危险操作，做了多道保险，宁可漏删、绝不误删：
- 白名单登记：删除名单只在单张图片上传成功时登记（按文件对象记录，不按名字搜索）——上传失败、跳过、路径解析不到的图永远不会进名单
- 先替换后删除：笔记里的链接必须已成功替换写回，才进入删除阶段
- 文件校验：删除前确认文件还在库中、且就是当初上传的那个文件
- 类型校验：只删图片扩展名，其他文件碰不到
- 引用校验：重读替换后的笔记，若发现还有引用指向该文件（替换没生效），跳过不删
- 跨笔记校验：如果其他笔记也引用了这张图，跳过不删（防止弄裂别的笔记）
- 回收站兜底：删除走系统回收站（
vault.trash），不是永久删除，随时可恢复
被跳过的图片会在汇总里提示 ⚠️ X 张未删除，具体原因在控制台搜 跳过删除。
跨笔记共享的图怎么办？
同一张图被多篇笔记引用时（比如共用一个 assets 文件夹），把引用它的笔记全部上传一遍即可：最后一张图会在”最后一篇引用它的笔记”上传成功后被自动删掉。中途被跳过不用管，那是保护机制在工作。
五、重名图片怎么处理
- 图床端：上传同名文件时自动重命名为
p094_2(1).webp、(2)递增，不覆盖旧图、不报错 - 插件端：笔记里写进的是图床返回的真实地址（带
(1)也一样），保证链接永远有效 - 本地文件：不会被重命名、不会被移动，保持原名原位置（反正上传成功后会被自动删掉）
六、下载网络图片到本地
反向操作，用于把别人文章里的图存到自己库里：
- 打开含网络图片（
）的笔记 Ctrl + P→下载网络图片到本地- 图片下载到笔记同目录的
assets/文件夹，链接替换为本地相对路径 - 同名文件会被覆盖
七、常见问题排查
| 现象 | 原因与处理 |
|---|---|
弹 ❌ 图床登录失败 HTTP 401 | 图床地址/账号/密码和后台不一致，回设置里核对 |
弹 ❌ 请先打开一个 Markdown 笔记 | 当前活动标签页不是笔记，先打开一篇 md |
| 上传成功但某张图”未删除” | 安全机制生效（多半是其他笔记还在用它），把那篇也传了就好 |
| 图片点击放大预览不显示 | 已修复（早期上传的图 Content-Type 是 octet-stream，新上传的都正常） |
| 怎么看详细日志 | Ctrl + Shift + I 打开控制台 → Console → 过滤框输入 Image Manager |
八、给未来的自己：源码与更新
- 源码工程：
plug-in/Obsidian/obsidian-image-manager/（main.ts + esbuild） - 构建：在该目录跑
pnpm build（自动类型检查 + 打包 + 拷贝进src/.obsidian/plugins/obsidian-image-manager/） - 生效：构建后在 Obsidian 里把插件关闭再开启（或 Ctrl+P 重载）
- 改了插件必须同步更新本文，在文末版本历史里加一行
版本历史
- 2026-09-19 · v2.2.0：新增批量上传——命令面板选择文件夹或文件树右键，递归处理整个文件夹的所有笔记；单篇上传重构为支持批量安静模式（共享进度条、统一汇总）
- 2026-09-19 · v2.1.0：新增”上传成功后删除本地图片”（默认开启），七道保险防误删，移入系统回收站；上传文件按扩展名写入正确 MIME 类型（修复 image-toolkit 预览问题）
- 2026-09-19 · v2.0.0：抛弃 PicList 中转，直连 CloudFlare-ImgBed API（管理员账号密码登录 +
/upload上传）；命令从 checkCallback 改为 callback，根治”切换文件后执行命令无反应”；设置页全新（图床地址/账号/密码/目录/命名方式/渠道） - v1.x（已弃用）：PicList 中转版，依赖本地 PicList 常驻，已彻底移除
评论区
[ 标签 ]
[ 分类 ]
[ 公告 ]
如果你喜欢，那么欢迎来到我的世界！
了解更多[ 音乐 ]
音乐
暂未播放
0:000:00
找不到相关结果。
[ contents ]
[ 全部文章 ]
