你的 Mac 会悄悄堆满你从未主动要求的垃圾文件：数 GB 的 Xcode DerivedData、npm 缓存、Homebrew bottles、浏览器缓存、过期的 node_modules 以及没人会看的日志。cleanupper 能找出所有这些文件，标注哪些可以安全移除，并进行清理——始终先移入废纸篓，绝不静默删除。

无订阅。无推销。无遥测。只是一个快速、诚实的终端工具——为活在 shell 里的人提供的免费开源 CleanMyMac 替代品。

$ cleanupper scan

   ID                    类别                     安全性    大小       项目数
   ────────────────────  ───────────────────────────  ────────  ─────────  ─────
   user-caches           应用缓存           SAFE      4.2 GB     87
   xcode-deriveddata     Xcode DerivedData            REVIEW    18.6 GB    41
   npm-cache             npm 缓存                    SAFE      2.1 GB     3
   homebrew              Homebrew 缓存               SAFE      1.3 GB     12
   browser-cache         浏览器缓存           SAFE      2.9 GB     5

   可回收：31.4 GB

   运行 `cleanupper clean` 将这些移入废纸篓。以上内容均未被修改。

✨ 为什么选择 cleanupper？

• 🔒 设计上确保安全 —— 只针对一份固定的可重建目标目录清单（缓存、索引、下载内容）。个人文件永远不会被当作垃圾扫描，受保护路径黑名单让灾难性误删在结构上不可能发生。
• 🗑️ 废纸篓优先 —— 所有内容都移入 macOS 废纸篓，在你清空之前任何东西都可以恢复。永久删除需要显式使用 --permanent 标志。
• 👀 删除前先审查 —— scan 不会改动任何东西。clean 会显示每个类别的大小，并在动任何字节之前请求确认。
• ⚡ 快速 —— 并行异步扫描可在数秒内遍历 ~/Library 和你的开发目录。
• 🛠️ 为开发者打造 —— Xcode DerivedData 与 DeviceSupport、npm/Yarn/pnpm/pip/uv/CocoaPods/Gradle/Cargo/Go 缓存、Homebrew 清理，外加一个 purge 命令，可在你的项目中搜寻过期的 node_modules、target、.venv 等产物。
• 🤖 可脚本化 —— --json 输出和 --yes 标志使其对 CI 和 cron 友好。
• 🕵️ 零遥测 —— 完全在你的 Mac 上本地运行，不发出任何网络请求。

📦 安装

一行命令（如有需要会先安装 Apple 命令行工具，然后安装 cleanupper）：

xcode-select --install
mkdir -p 'diskclean' && cd 'diskclean' && npm install github:SewCabinSpout/cleanupper

然后运行：

npx cleanupper scan

系统要求： macOS 11+、Node.js 18+（如果没有，可用 brew install node 安装）。

全局安装（可选，以便直接使用 cleanupper 命令）：

npm install -g github:SewCabinSpout/cleanupper
cleanupper scan

🚀 用法

cleanupper scan                       扫描并报告——不做任何更改
cleanupper scan --json                输出机器可读报告，便于脚本处理
cleanupper clean                      扫描、审查、确认 → 移入废纸篓
cleanupper clean -c xcode-deriveddata 只清理某个类别
cleanupper clean -c "Dev Tools"       清理整个分组
cleanupper clean --yes                跳过确认提示
cleanupper clean --permanent          跳过废纸篓（谨慎使用）
cleanupper clean --include-trash      同时清空废纸篓本身
cleanupper purge                      在项目中查找过期的 node_modules/target/.venv
cleanupper purge ~/Code --older-than 30   只处理 30 天以上未动过的产物
cleanupper purge --scan-only          只报告不清理
cleanupper analyze ~/Downloads        查看文件夹内部是什么在占用空间？
cleanupper list                       列出所有类别、安全标签及其说明

一次典型的使用流程是三步——扫描 → 审查 → 确认：

cleanupper scan          # 1. 看看有什么可回收的，不做任何更改
cleanupper clean         # 2. 查看摘要
                         # 3. 确认；所有内容都会进入废纸篓

🎯 清理内容

✅ 安全 = 纯缓存，所属应用会静默重建。 ⚠️ 需审查 = 可重建，但重新下载会耗费你的时间（例如下次 Xcode 构建会变慢）。每个类别都附有通俗易懂的说明——运行 cleanupper list 查看全部。

🛡️ 安全模型

cleanupper 会删除文件，因此安全性就是产品本身：

1. 基于目录清单，而非启发式。 它只针对 src/categories.js 中明确列出、经人工审核的路径清单。它不认识的路径根本不会出现。
2. 受保护路径。 主目录、Documents、Desktop、Pictures、/System、/Library、ssh 密钥、浏览器配置文件等不可替代的位置在扫描器中被硬性屏蔽。
3. 只清内容。 缓存文件夹会被清空，但文件夹本身绝不会被删除，因此应用不会出问题。
4. 默认进废纸篓。 删除操作以防冲突命名将文件移入 ~/.Trash。当你清空废纸篓时空间才被完全释放——在此之前，一切皆可恢复。
5. 始终需要确认。 除非传入 --yes，否则没有交互式 y 确认就不会发生任何事。

🔒 隐私

cleanupper 100% 在本地运行。没有分析统计、没有遥测、没有崩溃报告、没有网络调用——每一行代码都可阅读、可验证。它从不读取文件内容，只读取路径和大小。

👩‍💻 面向开发者

为可修改性而设计——整个工具约 600 行代码，依赖极少，基于 ESM Node.js：

bin/cleanupper.js   入口
src/categories.js   ⭐ 清理目录清单：路径、安全标签、说明
src/scanner.js      异步遍历器：大小统计、产物检测、受保护路径
src/cleaner.js      废纸篓优先的删除引擎 + brew/pnpm/go 集成
src/cli.js          Commander 接线：scan / clean / purge / analyze / list
src/ui.js           表格、徽章、横幅
test/               node:test 单元测试

git clone https://github.com/SewCabinSpout/cleanupper.git
cd cleanupper && npm install
npm start -- scan     # 从源码运行
npm test              # 单元测试

最有价值的贡献是新增清理类别。 在 src/categories.js 中添加一个条目（仅限可重建目标——参见 CONTRIBUTING.md），添加测试，提交 PR。Bug 报告和安全性发现同样欢迎。

路线图设想：交互式复选框选择、忽略列表、定时扫描、磁盘用量 TUI 浏览器、Homebrew formula。

❓ 常见问题

它安全吗？会删除我的照片/文档/代码吗？ 不会。cleanupper 只针对固定目录清单中的可重建缓存和生成的产物。个人文件、源代码以及它不认识的任何东西都不会被碰——而且删除也会先进废纸篓。

清空这些缓存会破坏我的应用吗？ 不会。每个目标都是所属应用会自动重新生成的数据。最坏的情况：你的下一次 Xcode 构建或 npm install 会多花一点时间。

为什么 Xcode DerivedData 标记为"需审查"？ 它 100% 可重建，而且往往收益最大（10–50 GB），但你的下一次完整构建会更慢。由你决定。

支持 Linux/Windows 吗？ 目录清单是 macOS 专属的，因此它作为 macOS 工具发布。欢迎为其他平台贡献代码。

它与 CleanMyMac 有什么不同？ 它免费、开源、终端原生、可脚本化——而且从不向你推销。它专注于开发者的垃圾文件，那里才是数 GB 空间真正被吞掉的地方。

📄 许可证

MIT —— 随便用，随便 fork，随便发布。