README file from
GithubStorage Cleanup 存储清理
像查看手机、电脑的「存储空间」一样,一眼看清 Obsidian 仓库里每个文件、每类文件占了多少空间。
所有文件按类目列出,包括笔记、附件、隐藏文件、插件目录里的文件和 .trash 回收站。点开类目即可查看具体文件;文件支持排序,可直接移入 .trash,也能从 .trash 中恢复。桌面端和手机端都能流畅使用。
目录
1. 安装
1.1 手动安装
从 Releases 下载 main.js、manifest.json、styles.css,放进仓库的 .obsidian/plugins/storage-cleanup/:
<仓库>/
└─ .obsidian/
└─ plugins/
└─ storage-cleanup/
├─ main.js
├─ manifest.json
└─ styles.css
没有这个文件夹就新建一个。放好后重启 Obsidian,到 设置 → 第三方插件 里找到 Storage Cleanup 并启用。
已经能在社区插件目录里搜到时,也可以走 设置 → 第三方插件 → 浏览 直接安装。
1.2 版本要求
- Obsidian 1.13.4 或更高。
- 桌面端与移动端都可安装。
2. 打开视图
三个入口,打开的是同一个页签:
| 入口 | 操作 |
|---|---|
| 左侧边栏 | 点硬盘图标 |
| 命令面板 | 执行「打开存储清理」 |
| 设置页 | 设置 → 第三方插件 → Storage Cleanup → 点「打开」 |
除总览外,左上角都有「返回」,点一下回上一级;页头中间那串层级也能点,点哪层回哪层。按 Esc 等同「返回」。
右上角「更多」菜单里有「重新扫描」和「复制扫描报告」。
3. 总览
顶部是五类合计的总大小和仓库名,下面一条比例条,再往下五类各占一行:
| 类目 | 内容 |
|---|---|
| 内容文件 | 笔记、附件等常规文件 |
| 插件数据 | 配置目录 plugins/ 下各插件的占用 |
| 配置与主题 | 主题、片段、图标、配置、缓存 |
| .trash | Obsidian 回收站 |
| 其他与隐藏 | 路径里带隐藏段的文件 |
每行右侧是大小和占比,点一行进入该类目。
有清理候选时,列表最后多一行「清理」,写明有几项待处理。扫描时有位置读不出来,列表下方会提示「有 N 个位置无法读取」。
4. 五个类目
4.1 内容文件
默认按类型分组:笔记、图片、音频、视频、PDF 与文档、压缩包、其他文件。点类型看该类的文件。
也可以切换成「按文件夹」,逐层点进去。两类视图里都能看到整个内容区最大的 5 个文件。
4.2 插件数据
每个插件占一行,显示名称、版本、文件数和占用。点进去看这个插件的文件和子文件夹,顶部可以「复制路径」。
这一类只统计占用,没有删除入口。
4.3 配置与主题
按主题、片段、图标、配置、缓存与临时、其他分组,点分组进去看文件。主题按主题文件夹分行。
同样只统计占用。
4.4 .trash 回收站
.trash 是仓库根目录下的 Obsidian 回收站,不是系统回收站。
可以进子文件夹查看。文件行展开后有「复制路径」和「恢复」。有文件时页面底部有「清空 .trash」,清空后里面的内容永久删除。
4.5 其他与隐藏
路径里任一段以 . 开头的文件归到这里,包括 Obsidian 文件列表不显示的隐藏目录。
这类文件只统计占用,不能打开,也不能清理。
5. 查看文件
点开一行展开详情,可以看到完整路径、大小、修改时间。内容文件可以「打开文件」,所有文件都可以「复制路径」。
工具栏右侧的排序按钮可以按大小、名称、修改时间排序。
6. 清理
6.1 进入清理
总览有候选时,最后一行是「清理」。点进去有三个方向,只显示有候选的:
| 方向 | 判定 |
|---|---|
| 大文件 | 10 MB 及以上 |
| 0 字节文件 | 文件大小为 0 |
| 空文件夹 | 里面没有任何文件 |
清理候选只来自内容文件。配置目录、隐藏路径和 .trash 里的文件不会出现在候选里。
6.2 怎么处理
单条:展开候选行,点「移入 .trash」或「永久删除」。
批量:点工具栏「多选」,勾选后点底部按钮。候选默认不勾选,可以「全选」。
6.3 三类候选的去向
| 候选 | 结果 | 能否找回 |
|---|---|---|
| 大文件 | 移入 .trash |
能,见第 7 节 |
| 0 字节文件 | 移入 .trash |
同上 |
| 空文件夹 | 永久删除 | 不能 |
点按钮会弹确认框,确认后执行。永久删除用的是危险样式按钮。
6.4 结果
全部成功时底部弹出提示,几秒后自动收起。有失败或跳过时底部留一张卡片,写明各有多少条,展开可以看到原因,失败的项可以「重试失败项」。
清理完成后成功的项会从列表消失,总览随之更新。
7. 从 .trash 恢复
Obsidian 把文件放进 .trash 时只保留文件名,原来的文件夹层级不保留,所以恢复时要你指定放回哪个文件夹。
在 .trash 列表里展开一行点「恢复」,或者点「多选」勾选多条后点底部的「恢复」。
接着进入「选择目标文件夹」页:从库根目录开始,点文件夹逐层进入,选好后点底部「恢复到这里」。
目标文件夹必须已经存在,插件不会新建。目标里已有同名文件时会自动改名成「原名 2」,不会覆盖原有文件。
清空 .trash 之后就无法恢复了。
8. 扫描与隐私
8.1 扫描范围
扫当前仓库的 Vault 内容、配置目录(默认 .obsidian)和 .trash。Vault 里路径带隐藏段的文件也会读到,单独归入「其他与隐藏」。
不扫描应用级缓存、Obsidian Sync 与 Publish、云盘、系统回收站和系统备份。
8.2 读取内容
只读文件大小、修改时间,以及每个插件的 manifest.json(名称、版本、作者)。不读笔记、附件或其他文件的正文。
8.3 隐私
插件不联网,不收集数据,没有遥测、广告和账号。设置页里的 GitHub、小红书按钮只在你点击时打开浏览器。
8.4 数字口径
按逻辑文件大小统计,所以可能低于磁盘实际占用。总占用是五类之和,同一份文件只算一次。
8.5 什么时候扫描
第一次打开视图时自动扫描。之后文件有增删,点「更多 → 重新扫描」更新。
9. 设置页
设置 → 第三方插件 → Storage Cleanup 下只有三块:打开存储清理的入口、关于(版本、作者、反馈方式)、使用须知(扫描范围、只读边界、清理语义、隐私、操作提示)。
没有开关项,10 MB 阈值和扫描范围都不可调。
界面跟随 Obsidian 的语言显示中文或英文。切换语言后重载插件生效。
10. 限制
- 没有搜索,只能按类目、类型、文件夹逐层查看。
- 插件数据、配置与主题只读,界面上没有删除入口。
.trash页只能整页清空,不能只删其中一个文件;恢复可以按单个或整个文件夹进行。- 移入
.trash后只保留文件名,原文件夹层级不保留,恢复时只能自己选目标文件夹。 - 恢复、删除空文件夹、清空
.trash都没有撤销。 - 仓库很大时(例如上万文件),扫描和滚动会变慢。
- 列表是上次扫描的结果,不随文件变化实时更新。
11. 常见问题
扫描出来的总大小和系统里看到的不一样。 插件统计的是文件逻辑大小,系统显示的是磁盘占用,两者会因区块对齐、压缩、云盘占位而不同。
刚删掉或刚加的文件没出现在列表里。 列表是上次扫描的结果,点「更多 → 重新扫描」更新。
为什么某个大文件不在清理候选里?
候选只从内容区非隐藏文件里选。文件在配置目录、.trash 或隐藏路径里时不会出现。
点清理时提示文件已变化。 扫描之后文件被改过、改名或替换过,插件跳过了这一项。重新扫描后再清理即可。
恢复后文件名多了个「 2」是怎么回事? 目标文件夹里已经有同名文件,插件按「原名 2」「原名 3」的顺序找了第一个没被占用的名字,原有文件保持不动。
清空 .trash 会把 .trash 文件夹删掉吗?
不会。文件夹本身留着,里面清空。
清理会自己开始吗? 不会。所有清理都要手动点按钮并确认,恢复也要手动选目标目录。插件没有自动清理、定时清理或自动恢复。
手机上能用吗? 能。桌面和手机共用同一套视图,按屏幕宽度调整布局。
12. 反馈与许可
Storage Cleanup 采用 MIT License 开源。
- 问题反馈、可复现的 Bug 和功能建议:GitHub Issues。也欢迎提交 PR。
- 使用交流与产品动态:小红书搜索 焦应行。
npm install
npm run dev # 监听源码并生成 main.js
npm run build # 类型检查并生成 main.js
npm test # 单元测试
npm run check # 完整检查