快速删除散落各处的 node 相关依赖

在前端开发中，项目依赖会占用大量磁盘空间。

特别是当同时维护多个项目时，每个项目都有独立的 node_modules 目录，单个目录动辄几百 MB，甚至上 GB。

如果某些项目长期不再使用，这些依赖就成了"隐形的空间杀手"——安全地删除它们可以释放可观的空间。

手动逐个查找和删除 node_modules 目录是一件繁琐的事情。

这时可以使用 npkill 这个 CLI 工具，它以低层、分布式方式扫描磁盘，充分利用磁盘和 CPU 资源，快速列出所有 node_modules 及其占用大小，并提供直观的交互式界面来选择性删除。

环境要求： Node 版本需大于 14.0.0。

一、用 find 列出所有 node_modules

在引入 npkill 之前，最通用的做法是用 Unix 的 find 命令递归查找所有 node_modules 目录，并配合 du 计算各自大小：

# 递归查找所有 node_modules，并显示各自占用空间
find . -name "node_modules" -type d -prune -exec du -sh {} \;

参数说明：

• -name "node_modules"：匹配名为 node_modules 的目录。
• -type d：限定只查目录。
• -prune：找到 node_modules 后不再向其内部递归，避免重复统计和性能浪费。
• -exec du -sh {} \;：对每个匹配结果执行 du -sh，以人类可读格式（如 1.3G）输出大小。

扫描整个用户主目录时，把 . 换成 ~，并屏蔽权限不足等无关报错：

find ~ -name "node_modules" -type d -prune -exec du -sh {} \; 2>/dev/null

二、批量删除

定位之后，可以把 find 的结果管道给删除命令，一次性清掉所有 node_modules：

find . -name "node_modules" -type d -prune -exec rm -rf {} +

用 + 而非 \; 结尾，会让 find 把多个匹配结果一次性传给 rm，效率更高。

但大多数时候这不是你想要的操作。 原因在于：

1. 误伤在用项目：有些项目仍在使用，VS Code 等编辑器正依赖这些 node_modules 提供代码补全、类型提示。全部删掉会让这些项目立刻"断供"。
2. 全局目录风险：如果在用户主目录根部执行，可能波及一些不该动的目录。

因此核弹级方案适合确认所有项目都不再需要、或刚做完备份的场景，日常清理更推荐下面的方式。

三、清理包管理器缓存

除了项目里的 node_modules，npm 和 Yarn 还会在全局维护一份缓存目录（cache），用于加速后续安装。这份缓存同样会随时间膨胀，定期清理能腾出空间，而且不会影响已有项目的 node_modules。

Yarn 缓存

# 清空 Yarn 全局缓存
yarn cache clean

# Yarn 2+（berry）：清空本地缓存
yarn cache clean
# 清空全局镜像缓存
yarn cache clean --mirror
# 同时清本地 + 全局
yarn cache clean --all

yarn cache clean 会删除 Yarn 为加速安装而缓存的包，下次安装时会重新下载。(yarnpkg.com)

npm 缓存

# 清空 npm 缓存（必须加 --force 才能彻底清除）
npm cache clean --force

npm 出于安全考虑，默认不允许轻易清空缓存，因此需要 --force 强制执行。清完后可验证：(Warp)

# 查看缓存目录位置
npm config get cache

# 校验缓存完整性（顺带清理无用数据）
npm cache verify

需要强调的是，清理缓存只会释放缓存目录的空间，并不会删除项目里的 node_modules。这两件事是独立的——缓存服务于"加速安装"，node_modules 是"项目运行所需的依赖实体"。

四、npkill：可视化、可选择地删除（推荐）

缓存清理解决不了旧项目 node_modules 堆积的问题，而核弹级 find + rm 又太粗暴。更干净的方案是使用 npkill——一个交互式 CLI 工具，它扫描磁盘上所有 node_modules，以可视列表展示每个目录的大小，并让你逐个勾选删除。

特性

npkill 的核心能力包括：

• 🔍 递归搜索所有子目录中的 node_modules
• 📊 显示每个 node_modules 目录的大小
• 🚀 支持多种包管理器（npm、pnpm、bun）
• 💻 交互式界面，操作简单直观
• ⚡️ 快速定位和删除不需要的依赖

基本用法

npkill 无需全局安装，支持通过多种包管理器直接运行：

# npm
npx npkill

# pnpm
pnpx npkill

# bun
bunx npkill

默认从执行命令的当前目录开始向下扫描。启动后会以低层、分布式方式扫描磁盘，速度较快，扫描完成后逐行显示每个 node_modules 的路径与占用大小。

交互操作

操作流程很直观：用方向键浏览列表，对不再需要的旧项目 node_modules 按 Space 选中，npkill 会实时累计你即将释放的空间。选完按 Enter 统一删除，或按 q 退出。

安全提示： 某些系统级应用依赖自身的 node_modules 才能正常工作，删除可能导致应用损坏。npkill 会对这类敏感目录显示 ⚠️ 警告标记，操作时需格外留意。(GitHub - voidcosmos/npkill)

常用 CLI 参数

npkill 默认从当前目录扫描，也可通过参数定制行为。通过 npx 传参时需加 -- 分隔：

# 指定扫描根目录
npx npkill -d ~/projects

# 指定要查找的目录名（默认 node_modules，也可换成 .next、.venv 等）
npx npkill -t .next

# 通过 npx 传参时需加 -- 分隔
npx npkill -- -d ~/projects -t node_modules

# 排除特定目录
npx npkill -E "ignore1, ignore2"

# 自动删除所有找到的 node_modules（建议配合 -x 使用，务必谨慎）
npx npkill -D

关键参数一览：

进阶能力

除了交互模式，npkill 还提供了面向自动化场景的能力：

• 按大小排序：npkill --sort=size，便于先清理最大占用。
• JSON 输出：--json 收集全部结果后一次性输出；--json-stream 逐行流式输出，适合接入监控或脚本：

  # 流式输出并统计所有 node_modules 总大小
  npx npkill --json-stream 2>/dev/null | jq -s 'map(.result.size) | add'
  

• 结果列：列表中会显示 last_mod 列，即该工作区最近一次修改文件的时间，帮你判断哪些是长期不动的"僵尸项目"，优先清理。(npmjs.com)

常见案例：一次完整的磁盘瘦身流程

下面把上述方法浓缩成一组可执行步骤，适用于"磁盘告急、想清理一批旧前端项目"的典型场景。

步骤 1：摸清家底

进入你存放项目的目录，先扫描看看有多少 node_modules、各占多大：

cd ~/projects
find . -name "node_modules" -type d -prune -exec du -sh {} \; 2>/dev/null

步骤 2：清理包管理器缓存（回收缓存空间）

# npm 用户
npm cache clean --force
npm cache verify

# Yarn 用户
yarn cache clean

这一步不影响任何现有项目的 node_modules，属于"无损瘦身"。

步骤 3：用 npkill 选择性删除旧项目依赖

npx npkill -d ~/projects --sort=size

按大小排序后，从最大的 node_modules 开始，用 ▲/▼ 浏览，对确定不再维护的项目按 Space 选中，观察底部累计释放的空间，选够后按 Enter 统一删除或按 q 退出。

步骤 4：确认在用项目未受影响

对仍需使用的活跃项目，确认其 node_modules 未被误删；若被删，重新安装即可恢复：

cd ~/projects/my-active-app
npm install   # 或 yarn / pnpm install / bun install

步骤 5（可选）：核弹级清理

仅当你确认目录下所有项目都不再需要依赖时，才使用：

find ~/projects -name "node_modules" -type d -prune -exec rm -rf {} +