npkill - 一个清理 npm 包的神器

[!info] 阅读导览
全文 8 节：核心功能（1.1）→ 安装方法（1.2）→ 基础使用步骤（1.3）→ 高级参数与场景（1.4）→ 技术原理（1.5）→ 关键注意事项（1.6）→ 替代方案与扩展（1.7）→ 总结（1.8）

flowchart LR
    A[扫描 node_modules<br>递归查找 + 大小统计] --> B[交互式选择<br>↑/↓ 或 j/k 移动]
    B --> C{按空格/Del 删除}
    C -->|确认| D[释放磁盘空间]
    C -->|q 退出| E[保留不动]

1. npkill：一个清理 npm 包的神器

1.1. 核心功能

npkill 是一款专为清理冗余 node_modules 设计的命令行工具，通过可视化交互界面和智能扫描算法，帮助开发者快速定位并删除无用依赖目录。其核心优势包括：

  • 智能扫描：基于 TypeScript 实现底层快速搜索，支持从任意目录或全局范围递归查找 node_modules。
  • 最近使用时间：显示每个 node_modules 目录的最后修改时间（last_mod 列），帮助判断哪些是久未使用的陈旧项目。
  • 轻量安全：解压后仅约 130 KB、几乎零依赖，删除前显示目录大小、路径及最后修改时间，避免误删关键文件。

1.2. 安装方法

  1. 全局安装

    npm install -g npkill  # 使用 npm
pnpm add -g npkill     # 使用 pnpm（更节省空间）

  2. 临时使用（无需安装）

    npx npkill  # 官方推荐，自动下载并运行最新版本

1.3. 基础使用步骤

  1. 启动扫描

    cd ~/projects  # 进入目标目录
npkill          # 从当前目录开始扫描
    • 指定起始目录：npkill -d ~/dev
    • 全局扫描：npkill --full（从用户主目录 home 开始）

  2. 交互式操作

    • 移动光标：↑/↓ 或 j/k 键选择目录。
    • 删除目录：按空格键或 Del 确认删除（不可逆操作）。
    • 退出程序：按 q 或 Ctrl+C。

1.4. 高级参数与场景

参数 功能说明 示例
-E, --exclude 排除指定目录（逗号分隔，需用双引号包裹） npkill -E "temp, backup"
-d, --directory 指定扫描起始目录（默认当前目录） npkill -d ~/dev
-t, --targets 指定要搜索的目录名（可逗号分隔多个，如 node_modules,.cache） npkill -t dist
-s, --sort 按大小、路径或最近使用时间排序 npkill -s size
--size-unit 设置大小显示单位（auto / mb / gb） npkill --size-unit gb
-D, --delete-all 自动删除所有扫描到的目录（建议配合 -x 使用） npkill -D

1.5. 技术原理

  1. 目录扫描与统计
    npkill 会递归遍历起始目录，定位所有名为 node_modules 的文件夹，统计各自占用的磁盘空间，并展示路径、大小与最后修改时间。
  2. 异步 I/O 优化
    利用 Node.js 非阻塞特性，并行扫描多个目录，提升效率。

1.6. 关键注意事项

  1. 系统目录保护
    若扫描到系统关键目录（如 /usr/lib/node_modules），界面会显示警告图标提示谨慎，切勿删除以免破坏环境。
  2. 权限问题
    删除某些目录可能需要管理员权限，建议在命令行工具中以管理员身份运行（Windows：右键选择"以管理员身份运行"）。
  3. 备份与恢复
    • 删除前可通过 npm ls 查看依赖树，确认是否误标。
    • 误删后可通过 npm install 或 pnpm install 重新安装依赖。
  4. 性能优化
    若项目过多导致卡顿，使用 -E 排除非目标目录（如测试环境 test）。

1.7. 替代方案与扩展

  1. pnpm
    使用硬链接全局复用依赖，从源头减少 node_modules 体积。

  2. 手动清理缓存

    npm cache clean --force  # 清理 npm 缓存（非 node_modules）

  3. rimraf
    快速删除单个目录（适合已知路径）：

    npx rimraf node_modules  # 强制删除当前目录的 node_modules

1.8. 总结

npkill 是 Node.js 开发者必备的"空间救星"，尤其适合以下场景：

  • 清理陈旧项目：快速释放数十 GB 磁盘空间。
  • 优化构建速度：减少 CI/CD 流程中冗余依赖的传输时间。
  • 依赖审计：辅助检查项目中是否存在无用或过时依赖。

通过灵活参数组合和交互式操作，既能精准清理，又能避免误操作。建议搭配 pnpm 使用，从依赖安装机制上实现长期优化。

[!success] 核心要点

  • 定位：可视化交互式清理 node_modules 的命令行工具，npx npkill 即用即走（官方推荐）
  • 核心优势（已按官方 README 核验）：TypeScript 底层快速扫描、last_mod 最近使用时间辅助判断、解压后仅约 130 KB 几乎零依赖
  • 操作流程：cd 目标目录 → npkill → ↑/↓ 或 j/k 移动 → 空格/Del 删除 → q 退出
  • 常用参数：-E 排除、-d 起始目录、-t/--targets 指定目录名、-s 排序、--size-unit 单位、-D 自动删除（均按官方 README 修正）
  • 注意事项：系统目录有警告图标勿删、删除不可逆、误删可 npm install 恢复
  • 替代方案：pnpm 硬链接复用、npm cache clean 清缓存、npx rimraf 删单目录