ll90551829459 downloadsScan your vault for broken links, unreferenced resources and duplicate files, then safely organize related notes.
扫描 9 类 Vault 问题,安全清理,顺带压缩图片。
Scan nine kinds of vault health problems, clean them safely, and compress images along the way.

截图取自演示库
vault-doctor-demo,仅含示例内容。
版本 1.14.0 · 平台 桌面端(Windows / macOS / Linux) · 许可证 0-BSD · 社区市场 Vault Doctor
Vault Doctor is an Obsidian plugin that scans a vault for nine kinds of health problems, compresses images and organizes related notes — then helps you fix them safely, not just list them. It runs fully offline and only changes files after you confirm. Cleanup goes through Obsidian's trash, moves support undo, and image compression rewrites references with a per-image safety check.
In Obsidian, open Settings → Community plugins → Browse and search for Vault Doctor, then install and enable it. To install manually, download main.js, manifest.json and (if present) styles.css from the latest release, place them in <Vault>/.obsidian/plugins/vault-doctor/, and enable the plugin in Settings → Community plugins.
0-BSD.
中文说明见下方。
一个为 Obsidian 做的「Vault 体检 + 问题处理」插件:一次性扫描 9 类健康问题(失效链接、未引用资源、重复文件等),并提供图片压缩优化工具,安全地完成整理,而不是只列清单。
Vault Doctor 把三块能力放进同一个工作区面板:
img、frontmatter 与 Canvas 中的引用都会被安全改写,源图仅在校验通过后移入回收站。全部在本地完成:无网络请求、无遥测。扫描从不修改文件;删除需要两段式确认并走 Obsidian 回收站,链接改写依赖 Obsidian 编辑历史。每次清理后,因操作变空的文件夹(含嵌套空子目录)会被自动移入回收站,并自动做一次全关联重扫、刷新所有体检类别计数,无需二次手动扫描。
首次使用引导:第一次安装并加载插件时会自动弹出三步引导(它能做什么、安全说明、怎么开始,含界面截图),点「开始使用」可直接打开体检面板。之后可在命令面板搜索「打开使用引导」重看;设置里的「首次显示使用引导」关闭后不再自动弹出。
查看更新说明:安装或升级到新版本后,首次打开会自动弹出一次该版本的中文更新说明(按新功能、改进、修复分类,含「开始使用」按钮);同一版本不会重复弹出。之后可随时在命令面板搜索「查看更新说明」再次打开。
以下截图均取自演示库 vault-doctor-demo,仅含示例内容,不含任何真实项目信息。





点击左侧栏唯一的打开 vault 体检与清理图标,或运行同名命令打开体检工具。工具以工作区标签页打开。点击开始扫描后,体检首页与各分类标签页并列展示,可随时切回总览。扫描默认不勾选任何条目,确认无误后自行勾选并执行清理。
体检首页把所有检查项汇总成一张总览:顶部是当前待处理总数和扫描进度(9/9 分类已扫描),下方按优先处理(按问题数量排序)与已检查(未发现问题)分区。每个卡片都能直接重新扫描或查看明细。扫描期间标题栏会出现中止扫描,点它会在当前分类结束后停下,已完成的分类结果全部保留。
扫描结果缓存在插件设置中:重开面板直接显示上次结果并标注「上次扫描:日期 时间」;修改图片格式或忽略目录后,缓存中保存的设置快照与当前设置不一致时即被丢弃,需重新扫描。首页同时提供图片压缩卡片,它不属于 9 类扫描,开始扫描只更新 9 类结果;有可转换图片时计入顶部「当前待处理」总数,点卡片或查看进入图片压缩页签。
.obsidian、.trash、.git 等隐藏目录永远不会被扫描。![[图片.png]] 形式的嵌入,可转换为标准 Markdown 图片链接。尺寸标注、未解析目标、代码块与 frontmatter 一律跳过;按笔记分组执行,可用 Obsidian 编辑历史撤销。[[笔记]]、[[笔记|别名]]、[[笔记#标题]]、[[笔记^块id]] 等指向 Markdown 笔记的 Wiki 链接,可转换为 [显示文本](<路径.md>) 标准尖括号 Markdown 链接;别名保留,标题与块引用转为 #标题 / #^块id 锚点。图片等嵌入语法、外部 URL、非 Markdown 目标、无法解析的目标、代码块与 frontmatter 一律跳过;按笔记分组执行,可用 Obsidian 编辑历史撤销。未引用图片以缩略图卡片展示,可勾选、预览或删除;顶部可按按路径或按格式分组(也可不分组),底部显示已选数量,右侧为移入回收站。
失效笔记链接以表格展示源笔记、失效链接原文、未解析目标与链接类型;每行可定位或本次忽略,底部可创建选中笔记或移除选中链接。
空文件与空文件夹列表会标注文件大小,勾选后统一移入回收站。
重复文件按内容哈希分组,逐行列出每个副本被哪些笔记引用、位于哪个文件夹、当前状态(已引用 / 未发现引用),便于判断该保留哪一份。
安全执行、回收站、两段式确认、清理后连锁收尾的统一约定见下方安全设计。
.trash/ 或系统回收站,不直接删除文件;失效链接移除、原生图片链接与 Wiki 笔记链接转换直接编辑 Markdown,可用编辑历史撤销。.obsidian/.trash/.git)、设置里忽略的目录和根目录都不会被删除;被移入回收站的文件夹可恢复。清理完成提示中会追加「自动清理了 X 个空文件夹」。「图片压缩」是体检与清理面板标签条末尾的独立标签页,用于在保持图片可用的前提下缩小体积。它不属于 9 类体检问题,也不计入健康度或 6 阶段扫描;首页会单独显示一张图片压缩卡片,有可转换图片时计入顶部「当前待处理」总数。打开 体检与清理 后切换到 图片压缩,或直接点首页卡片即可使用。

首次进入页签时会先做一次轻量枚举:只按源格式、忽略目录与目标格式筛出候选,不读文件、不估算体积;切换源格式或目标格式会重新枚举。点扫描并估算后按源格式、目标格式与质量推算每张图的预估体积,同时显示「正在估算 x / y · 当前文件」与进度条;估算不读取图片内容,也不解码。完成后列表列出每张候选图的当前大小、转换后约多大与变化幅度;尺寸列在快速预估下显示 —,引用列按 Obsidian 引用索引统计「引用 N 处」。
工具栏提供全选可节省项、全部选择与取消选择:全选可节省项只选已估算且确实省体积的条目,全部选择选中所有未跳过项(包括体积可能变大的),取消选择清空当前选择。引用列可点击:1 篇来源笔记直接打开,多篇在列内弹出菜单选择,0 篇或笔记已移动时给出中文提示。选好条目后点开始转换(需连点两次确认)。

| 选项 | 可选值 | 默认 |
|---|---|---|
| 源格式 | PNG、JPG、WebP、BMP、AVIF(可多选) | 只勾选 PNG |
| 目标格式 | JPG、WebP、PNG | JPG |
| 质量 | 1–100(数字输入框) | 85 |
| 透明图处理 | 白底、跳过 | 白底 |
| 转换策略 | 能省空间才转换(默认)、总是转换(即使变大) | 能省空间才转换 |
质量旁的 ⓘ 图标在悬停或键盘聚焦时显示说明:100 为最高质量,JPG/WebP 仍会重新编码(有损),仅 PNG 无损;目标格式为 PNG 时质量输入框不可用。转换策略:默认「能省空间才转换」保持原行为,转换后体积不减反增就保留原图并跳过;「总是转换(即使变大)」则照常执行、仅换格式,原图仍移入回收站可恢复。像素上限按两级规则:默认档超过 1.2 亿像素强制跳过;「总是转换」档可放开 1.2 亿像素、超大像素图放行并仅提示,超过 4 亿像素绝对硬上限仍跳过以防内存崩溃。
设置页可预先配置目标格式、默认质量与透明图处理;在页面内调整这三项时会同步保存为下一次的默认值。源格式只在页面内勾选,默认勾选 PNG。只处理上述源格式;GIF(转换会丢失动画)、SVG、TIFF、HEIC/HEIF、ICO 不处理;.obsidian、隐藏目录和设置中的「忽略目录」会被排除。
估算阶段只会提前标出目标同名文件已存在与多张图片会转换为同一目标文件;其余风险在转换时逐张精确检查,跳过的条目会在结果里写明原因:
![[cover.png|120]],整张跳过。<picture><source>、srcset、CSS url()。候选列表显示候选数、当前体积、转换后约多少与预计节省。汇总条只累计可转换项,估算阶段已能确定的跳过项单独显示数量。
预估是经验值:按「源格式 → 目标格式」的经验压缩比乘以当前文件体积,再按质量线性缩放(PNG 为无损目标,质量不参与)。它只用于判断量级与挑选候选项,不会逐张解码或重编码,因此 5000+ 张也能在秒级完成;最终体积以转换时的真实编码结果为准。如果预估转换后反而更大,汇总显示预计增加,单行显示 +x%;这类图片可以不勾选。
resolvedLinks 索引圈出可疑来源笔记、检测这些笔记的 stat 是否变化。索引滞后或外部编辑导致 stat 变化时,再针对相关笔记真读盘复核;发现残留旧路径或源图被改动就回滚,不删原图。读取后与删除前都会复核源图;同步盘或其它程序改动源图时放弃删除并回滚。引用改写覆盖:
file 字段;Canvas 文本节点里的引用会跳过。转换会修改文件内容与文件本身,和首页「扫描只读」不同;预估为经验值,请确认量级后再执行,实际大小以转换结果为准。整个过程在本地完成,不引入依赖、不发起网络请求。
.trash/ 或系统回收站还原;引用仍指向新文件,完全回退需手动改回并删除新文件。从命令面板的「整理关联笔记」命令(会打开体检面板的关联笔记入口)、体检面板首页「相关功能」卡片,或 Markdown 文件右键菜单打开;支持多选笔记与整个文件夹批量处理。安装 Notebook Navigator 后可接入其多选与文件夹菜单。

Pages,也可手动输入完整路径,或使用快捷选项(当前目录、源笔记名目录、当前目录/Pages)。在 设置 → Vault Doctor 中配置:

| 设置项 | 含义 |
|---|---|
| 默认分组方式 | 打开关联笔记整理时列表的分组方式:不分组、按源笔记分组(默认)或按当前路径分组;面板内可临时切换 |
| 默认隐藏已在目标文件夹的笔记 | 已经位于最终目标文件夹的关联笔记默认不显示,减少干扰 |
| 可清理图片格式 | 参与未引用图片扫描的扩展名,默认 PNG、JPG/JPEG、GIF、WEBP、SVG、BMP、AVIF、ICO;可用逗号、空格或中文逗号分隔 |
| 忽略目录 | 这些目录及其子目录不参与未引用图片、未引用附件与空文件夹扫描;失效链接与原生图片链接检查不受影响 |
| 首次显示使用引导 | 开启时,首次加载插件自动弹出一次三步引导;关闭后不再自动弹出,仍可通过命令「打开使用引导」重看 |
| 图片压缩:目标格式 | 图片压缩页的默认输出格式:JPG(默认)、WebP 或 PNG;在页面内调整会同步保存为新的默认值 |
| 图片压缩:默认质量 | 默认 85,范围 1–100(数字输入框);越高体积越大、画质越好。目标为 PNG 时质量不生效且输入框禁用 |
| 图片压缩:透明图处理 | 含透明通道图片的默认处理方式:白底(默认)或跳过 |
早期版本的「关联数量属性」功能(
related-operations-in-links等三个 frontmatter 属性)已移除。插件不再读写这些属性;笔记中遗留的属性不受影响,相关功能均为按需实时计算。
.obsidian/plugins/vault-doctor/data.json,不含笔记正文。插件已上架 Obsidian 社区市场(市场页),推荐直接在 Obsidian 内安装。
方式 A:社区市场(推荐)
以下两种为手动安装方式。Obsidian 只认插件目录里的文件,所以需要把文件放进 <Vault>/.obsidian/plugins/vault-doctor/。
方式 B:下载 ZIP(省事)
vault-doctor-<版本号>.zip。<Vault>/.obsidian/plugins/vault-doctor/(ZIP 内文件就在根层,不要先解出一层文件夹再套一层)。方式 C:下载三件套(Obsidian 官方分发格式)
main.js、manifest.json、styles.css。<Vault>/.obsidian/plugins/vault-doctor/。两种手动方式的文件完全相同:ZIP 只是把三件套打成一个包,方便下载和搬运,不是 Windows 安装程序,也不会自动写系统路径。社区目录按 Obsidian 的三件套格式审核,所以 Releases 会同时保留三件套与 ZIP。
启用后在 设置 → 第三方插件 → 已安装插件 可以看到它;点右侧 ⋯ → 设置 打开配置页,⋯ → 在系统资源管理器中显示 可直接定位安装目录。

卸载:在 设置 → 第三方插件 禁用 Vault Doctor,然后删除 <Vault>/.obsidian/plugins/vault-doctor/ 文件夹。这会删除插件自身的 data.json 设置;不影响笔记内容,也不会恢复已进入回收站的文件。
npm install # 安装依赖(Node.js 22+)
npm run dev # 开发构建(watch)
npm run build # 生产构建(tsc 检查 + esbuild 打包)
npm run lint # ESLint 检查
npm test # Node 原生测试
npm run package # 打包安装包:dist/vault-doctor-<版本号>.zip
npm run package:check # 只校验打包输入,不写文件
npm run deploy # 构建并部署到当前打开的 Vault(见下)
测试使用 Node.js 22+ 的原生 TypeScript 类型擦除;插件产物本身以 ES2021 为目标。npm run build 只生成项目根目录的构建产物,不会修改 Vault。
npm run package 读 manifest.json 的版本号,把 main.js、manifest.json 和可选的 styles.css 打成 dist/vault-doctor-<版本号>.zip(ZIP 内文件位于根层),并在写出后重新解压校验条目、大小、CRC-32 与包内版本号。它不依赖第三方压缩库,也不会自动构建——main.js 不存在时直接报错,先跑 npm run build。
双击项目根目录的 deploy-and-restart.cmd,或运行 npm run deploy:脚本自动识别当前打开的唯一 Vault,构建并替换 vault-doctor 插件文件、校验哈希,然后重启 Obsidian 等待其稳定运行;旧版本会先备份到 .obsidian/plugin-backups/。没有唯一打开的 Vault、构建失败、校验失败或无法稳定重启时,脚本会停止且不继续部署。
npm run deploy:check 只构建并检查,不复制文件、不重启 Obsidian,用于部署前确认目标 Vault 与安装状态。
npm run deploy 依赖 Windows PowerShell、Obsidian CLI 与恰好一个打开的 Vault。| 操作 | 确认方式 | 去向 | 如何恢复 |
|---|---|---|---|
| 未引用图片 / 附件 / 空文件 / 空文件夹 / 重复文件 | 删除按钮两段式确认 | 按你的设置进入 .trash/ 或系统回收站 |
Obsidian 回收站或系统回收站 |
| 失效图片链接 / 失效笔记链接移除、原生图片链接与 Wiki 笔记链接转换 | 确认弹窗 | 直接改写 Markdown | Obsidian 编辑历史撤销(不经过回收站) |
| 关联笔记移动 | 确认弹窗 | 移动到目标文件夹 | 手动移回原文件夹,链接随 Obsidian 设置更新 |
扫描会修改我的笔记吗? 不会。扫描只读取文件与元数据;移入回收站、移除链接、转换链接、移动笔记等操作都需要你先勾选并确认。
清理后发现选错了,能恢复吗?
移入回收站的文件可在 Obsidian 回收站(.trash/)或系统回收站中恢复;失效链接移除与原生图片链接、Wiki 笔记链接转换直接改写 Markdown,可用 Obsidian 的编辑历史撤销。
插件会联网或上传我的笔记吗? 不会。插件没有任何网络请求,也不收集或上传 Vault 内容。
支持移动端吗?
不支持。插件为仅桌面端(isDesktopOnly: true),需要使用 window.require('electron') 在系统资源管理器中定位文件;npm run deploy 一键部署脚本仅适用于 Windows 桌面。
和 Notebook Navigator 是什么关系? Notebook Navigator 是可选集成:安装后可接入其多选与文件夹菜单,未安装时插件核心功能仍可正常使用。