前言#

Image Manager 是我自己写的 Obsidian 插件，专门打通”写笔记 → 图片上库 → 发布博客”这条链路。

它之前走的是 PicList 中转方案（Obsidian → 本地 PicList → 图床），但坑不少：批量传完一个笔记后切到下一个文件再执行命令，经常点了没反应；中间还多依赖一个常驻软件。后来我把插件重写成直连 CloudFlare-ImgBed 图床的 API，PicList 彻底退役。

这篇是我的查阅文档：功能、设置、操作、安全机制、排错都在这。插件每次有新功能或功能修改，我都会同步更新这篇。

功能一览#

一、设置项说明#

设置位置：Obsidian 设置 → 第三方插件 → Image Manager。

二、上传当前笔记的图片#

1. 打开一篇含本地图片（![](assets/xxx.webp) 或 ![[xxx.webp]]）的笔记
2. Ctrl + P → 执行 Image Manager: 上传图片到图床
3. 右上角出现”⬆️ 开始上传…”进度条，逐张直传
4. 完成后弹窗汇总：✅ 成功 N 张 / 🗑️ 已删除本地图片 N 张

笔记里的链接会被自动替换成图床真实地址，例如：

1
上传前：![](assets/p001_1.webp)
2
上传后：![](https://img.tsh520.cn/file/blog/article/p001_1.webp)

三、批量上传整个文件夹#

一篇一篇传太慢，批量功能一次处理一个文件夹：

• 方式 A：Ctrl + P → 批量上传文件夹图片到图床 → 在弹出的搜索框里输入文件夹名（如 MySQL-运维篇）回车
• 方式 B：左侧文件树右键任意文件夹 → “上传此文件夹的图片到图床”

批量行为：

• 递归处理该文件夹（含子文件夹）下所有 Markdown 笔记
• 全程共用一次登录（会话过期自动重登），右上角显示总进度：⬆️ 批量上传 (3/7)
• 没有本地图片的笔记自动跳过，不弹窗打扰
• 每篇完成自动替换链接 + 按设置删除本地图片
• 结束后统一汇总：✅ 上传 X 张（Y 篇笔记）/ 🗑️ 已删除 Z 张 / ❗ N 条错误
• 失败详情（哪篇哪张）在控制台（Ctrl + Shift + I → Console）里看，搜 [Image Manager]

四、上传成功后自动删除本地图片（安全机制）#

上传完成后，插件可以把对应的本地图片删掉（省得手动清 assets）。因为删除是危险操作，做了多道保险，宁可漏删、绝不误删：

1. 白名单登记：删除名单只在单张图片上传成功时登记（按文件对象记录，不按名字搜索）——上传失败、跳过、路径解析不到的图永远不会进名单
2. 先替换后删除：笔记里的链接必须已成功替换写回，才进入删除阶段
3. 文件校验：删除前确认文件还在库中、且就是当初上传的那个文件
4. 类型校验：只删图片扩展名，其他文件碰不到
5. 引用校验：重读替换后的笔记，若发现还有引用指向该文件（替换没生效），跳过不删
6. 跨笔记校验：如果其他笔记也引用了这张图，跳过不删（防止弄裂别的笔记）
7. 回收站兜底：删除走系统回收站（vault.trash），不是永久删除，随时可恢复

被跳过的图片会在汇总里提示 ⚠️ X 张未删除，具体原因在控制台搜 跳过删除。

五、重名图片怎么处理#

• 图床端：上传同名文件时自动重命名为 p094_2(1).webp、(2) 递增，不覆盖旧图、不报错
• 插件端：笔记里写进的是图床返回的真实地址（带 (1) 也一样），保证链接永远有效
• 本地文件：不会被重命名、不会被移动，保持原名原位置（反正上传成功后会被自动删掉）

六、下载网络图片到本地#

反向操作，用于把别人文章里的图存到自己库里：

1. 打开含网络图片（![](https://...)）的笔记
2. Ctrl + P → 下载网络图片到本地
3. 图片下载到笔记同目录的 assets/ 文件夹，链接替换为本地相对路径
4. 同名文件会被覆盖

七、上传文章封面图到图床（仅桌面端）#

批量把文章封面（frontmatter image 字段指向的本地图片）转 WebP 压缩后上传图床，并自动把 image 字段改写为图床 URL。

用法：Ctrl + P → 上传文章封面图到图床 → 选文件夹；或在文件树右键文件夹 → “上传此文件夹的文章封面到图床”。

处理流程（逐篇）：

1. 读取 frontmatter 的 image 字段，筛选出本地路径（/ 开头；已是图床 URL 的自动跳过）
2. 定位本地文件（默认 public/assets/images/posts/，目录可在设置里改）
3. 转成 WebP 并压缩（默认无损；设置里可切高质量有损 q90）
4. 上传到图床独立目录 blog/post-covers（与文章资源图 blog/article 分开，方便随机图、清理等场景区分）
5. 改写 frontmatter 的 image 字段为图床 URL（只动 frontmatter 区间，不重排 YAML、不碰正文示例）
6. 成功后删除本地封面文件（移入系统回收站；可在设置里关闭）

压缩效果参考（实测 1536×1024 的 AI 生成封面 PNG）：

删除的安全机制（与文章资源图同一套哲学）：

• 仅当”转码 + 上传 + frontmatter 写入”全部成功才删除，任一步失败都会保留本地文件
• 改写后会重新读取文件确认 image 字段已更新为图床 URL，校验不过就不删
• 批量开始时会扫描全库引用，若其他文章仍引用该封面则跳过删除
• 删除走系统回收站（shell.trashItem），失败则跳过并提示，绝不永久删除

八、在手机上使用（iOS / Android）#

v2.4.0 起插件可以在手机上加载运行了。手机上能用的：上传当前笔记的图片、下载网络图片到本地、批量上传文件夹。

九、常见问题排查#

十、给未来的自己：源码与更新#

• 源码工程：plug-in/Obsidian/obsidian-image-manager/（main.ts + esbuild）
• GitHub：https://github.com/tianshihao2003/obsidian-image-manager（公开仓库，release 上挂 main.js / manifest.json / styles.css，BRAT 与手动安装都从这里拿）
• 构建：在该目录跑 pnpm build（自动类型检查 + 打包 + 拷贝进 src/content 与 src 两个 Obsidian 库）
• 冒烟测试：pnpm smoke（模拟「无 Node 的移动端」和「桌面端」各跑一次 onload，防顶层 require 复发）
• 发版：gh release create vX.Y.Z main.js manifest.json styles.css --title "..." --notes "..."，同时把 manifest.json 与 package.json 的版本号一起升——BRAT 靠 manifest 的 version 判断有没有新版
• 生效：构建后在 Obsidian 里把插件关闭再开启（或 Ctrl+P 重载）
• 改了插件必须同步更新本文，在文末版本历史里加一行

版本历史#

• 2026-10-20 · v2.4.0：适配移动端（iOS / Android）——插件可在手机上加载，新增移动端左侧栏图标与笔记长按菜单；封面图命令与设置项在移动端隐藏；移动端不删除本地图片（无系统回收站）；进度提示与设置页文案适配窄屏。同时把插件的 WebP wasm 内嵌进 main.js（安装只需三个文件），并开源到 GitHub（tianshihao2003/obsidian-image-manager，可用 BRAT 一键安装与更新）
• 2026-09-24 · v2.3.2：修复封面图上传后”本地文件未删除”——Electron 14+ 渲染进程拿不到 shell 模块，改为回退到平台命令移入回收站（Windows 用 PowerShell 系统 API / macOS 用 Finder / Linux 用 gio trash）
• 2026-09-24 · v2.3.1：修复封面图上传必现的 Failed to construct 'URL': Invalid URL 报错——WebP 编码器的 WASM glue 在 CJS 打包后 import.meta.url 失效，改为注入 CJS 等价的文件 URL
• 2026-09-23 · v2.3.0：新增”上传文章封面图到图床”——批量把文章 frontmatter image 指向的本地封面转 WebP 压缩（默认无损，可切有损 q90）后上传到独立目录 blog/post-covers，自动改写 image 字段；成功后可选删除本地封面（多重校验 + 系统回收站）
• 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 常驻，已彻底移除