实话讲在用上 npm 的头一两年里我几乎没有认真看过本地包目录长什么样。直到某天发现 D 盘只剩 2 个 G打开资源管理器一层层翻下去才看到真相全局工具装完一次就再没用过缓存目录里堆着几个 G 的历史压缩包十几个项目的 node_modules 里同一个版本的 lodash 被复制了十几份。这种乱象让我决定手写一套极简的本地 NPM 包目录管理方案——不引入数据库、不搞服务端一个几百行的 Node 脚本加一个 JSON 索引文件就能把全局包、缓存包、项目依赖这三块地盘统一管起来。方案我实际跑了快一个季度稳定、够用、对新手也友好。如果你平时用 npm 安装全局工具、在多个项目里反复执行 npm install并且开始被磁盘占用和依赖混乱困扰这篇可以直接当作参考模板。1. 动手之前先看清本地包的三块地盘很多人一提到NPM 包目录第一反应是node_modules其实这只是三块地盘之一。npm 在你的机器上实际维护着三个互不相通的位置全局包目录、缓存目录、项目级依赖目录。每一块的产生机制不同、清理方式不同、风险等级也不同。不先把这三块分清楚后面任何管理方案都是空中楼阁。1.1 全局包目录最乱也最容易被忽略全局包目录就是npm root -g返回的路径。它具体在哪取决于你安装 Node.js 时选的路径以及 npm 的全局前缀配置。我用npm prefix -g查过自己的机器Node 装在D:\nodejs所以全局包集中在一个D:\nodejs\node_modules或者用户级前缀下的node_modules里如果你当初用的是默认安装路径大概率落在C:\Program Files\nodejs\node_modules或C:\Users\用户名\AppData\Roaming\npm\node_modules。为什么说它最乱因为全局安装的包是我们手动选择的但几乎没人记录自己装过哪些。npm 本身也没有类似最近使用时间的清单接口你唯一能拿到的时间信息就是包目录的修改时间。更麻烦的是很多重量级 CLI 工具自带一大串依赖装一个表面上很小的包实际能把几百 MB 带进来。我机器上就出现过vue/cli占掉 405MB 的情况。还有一点容易被忽略全局包对应的可执行文件bin在 Windows 上会生成.cmd和.ps1文件放在全局根目录下而不是放在包目录里。这意味着你光看node_modules下的包目录未必能对应上命令行里敲的那个命令到底属于谁。这也是 PATH 环境变量配置里经常出问题的地方——很多人报npm不是内部或外部命令其实不是 npm 坏了而是 PATH 里没有包含全局 bin 目录。1.2 npm 缓存目录大块头都藏在这里npm config get cache会告诉你缓存目录在哪。Windows 上默认是C:\Users\用户名\AppData\Local\npm-cacheLinux 和 macOS 上常见的是~/.npm。这块地盘的实际体积往往比全局包目录还大因为它保存的是 npm 安装依赖时下载过的所有压缩包和元数据。npm 的缓存用的是内容寻址Content-Addressable Storage方式同一版本号的包理论上只存一份不会重复但不同版本、不同时间的安装记录都会保留下来。你的项目越多、换版本越频繁缓存就越膨胀。我见过一台普通开发机缓存常年 3~5GB。缓存目录最让人头疼的一点它里面的文件按哈希命名从文件名完全看不出是哪个包。哪怕你用npm cache verify去检查也只能看到一些统计信息无法知道某个具体包占了多少空间。所以很多人的应对方式就是一刀切直接在磁盘告急时跑npm cache clean --force。这可行但时机很重要。如果这时候你正准备离线安装依赖缓存一清后续npm install就得全部重新下载。特别是配了国内镜像源的场景清缓存后再安装网速快还好网速慢就是一场煎熬。1.3 项目级 node_modules重复占用的大户第三块地盘是每个项目自己的node_modules。这是增量最夸张的目录同一个版本的 webpack、react、lodash在十个项目里就有十份物理副本。很多人以为 npm 会做全局去重实际上 npm 的依赖提升hoisting只在单个项目内生效它不会跨项目共享依赖。npm dedupe也只能优化某个项目内部的重复版本对于跨项目的重复是无能为力的。管理项目级node_modules的正确姿势也不是发现了就删而是先量化。你需要知道三件事每个项目的依赖整体多大、顶层直接依赖有多少个、node_modules里有没有不在package.json声明中的孤儿依赖。孤儿依赖通常是被依赖提升带上来的传递依赖直接删可能让某个间接引用断裂必须谨慎处理。搞清楚这些你才有资格谈清理。这三块地盘的分析结论很简单全局包目录杂乱无主缓存目录大而无当项目依赖重复冗余。它们各自的清理策略完全不同所以我把它们纳入了同一个管理方案里统一看。2. 方案的骨架一份 JSON 索引 三个子命令这套方案我起了个名字叫nlpm全称是 npm local package manager。它不追求做成一个完整平台只围绕一个核心原则把看清楚和删得对分开。看清楚靠扫描删得对靠人工确认过的清理脚本。整体的骨架非常朴素配置目录默认在~/.nlpm/下里面放索引文件、历史报告和生成的清理脚本。2.1 为什么不直接拿现成工具将就动手之前我认真比较过现成方案。npkill确实能按目录挑着删 node_modules但它不看全局包也不管缓存depcheck和npm-check更关注项目依赖的版本更新和缺失情况和目录体积管理是两个方向。我想要的是同时覆盖全局、缓存、项目三块地盘、并且输出可执行清理建议的小工具现成选项里没有一个完全贴合。也考虑过用 PowerShell 脚本或 Python 来写最后都否了。原因很直接用这个方案的人大概率已经装好了 Node用它写脚本不需要额外运行时读取package.json、调用npm命令、处理跨平台路径都是 Node 的舒适区。何况这个方案本质上是给 npm 用户用的一个全局 npm 包反而更符合直觉。安全性上我给自己立了一条规矩方案本身绝对不做侵入式操作。不移动目录、不创建软链接、不修改任何包的文件最多只在~/.nlpm里写索引和脚本。因为 node_modules 一旦被动了结构全局 CLI 可能直接瘫痪这种风险不值得为省几个 G 去冒。2.2 目录约定~/.nlpm 下的东西各管什么整个方案的目录设计精简到五个文件~/.nlpm/ config.json # 三块目录的路径配置 index.json # scan 生成的索引主文件 reports/ # 每次报告的快照按日期归档 scripts/ clean-xxx.cmd # clean 生成的清理脚本 clean-xxx.shconfig.json里并不需要用户填一堆东西。全局路径和缓存路径都留空脚本会自动调用npm root -g与npm config get cache去解析唯一需要手动配置的是项目根目录列表。{ global: null, cache: null, projects: [~/code, D:/work] }index.json是核心产物。它长这样{ generatedAt: 2025-01-15T10:00:00.000Z, global: { location: D:\\nodejs\\node_modules, packages: [ { name: vue/cli, version: 5.0.8, sizeBytes: 405000000, modifiedAt: 2024-11-03T08:30:00.000Z } ] }, cache: { location: C:\\Users\\admin\\AppData\\Local\\npm-cache, sizeBytes: 3760000000, archives: 1245 }, projects: [ { name: blog, path: D:\\code\\blog, sizeBytes: 850000000, depCount: 1563 } ] }为什么用 JSON 而不是 SQLite因为数据规模撑死几千条记录JSON 完全够用而且任何编辑器都能打开检查、调试、手动修复。可读性对排查问题太重要了。2.3 scan / report / clean三命令各司其职命令设计的逻辑我总结成一句话scan 是照相report 是看相册clean 是开药方药方要不要执行由你决定。nlpm scan重新扫描三块地盘生成新索引同时把上一份索引归档到 reports。nlpm report --top 20按大小排序输出文本报表。加--json可以直接输出完整索引方便接入其他脚本。nlpm clean --dry-run基于最新索引按规则算出待清理列表。nlpm clean --confirm把待清理列表转成可执行的.cmd或.sh脚本打印路径不直接执行。这套分离设计看起来很绕但恰恰是我认为整个方案里最重要的一点。所有破坏性动作都经过一次人工确认风险被压到最低。3. 核心实现几百行 Node 脚本如何跑起来这部分我把关键代码和背后的考虑讲透。整个 CLI 没有用commander之类的参数库直接解析process.argv能少一个依赖就少一个依赖。3.1 拿到三块地盘的路径并搞定 scoped 包扫描第一步永远是通过 npm 自己获取路径而不是硬编码。这样无论你把 Node 装在 C 盘还是 D 盘脚本都能自适应。const { execSync } require(node:child_process); const path require(node:path); const fs require(node:fs); function getDirs() { const globalRoot execSync(npm root -g, { encoding: utf8 }).trim(); const cacheDir execSync(npm config get cache, { encoding: utf8 }).trim(); return { globalRoot, cacheDir }; }这里有一个隐藏前提execSync执行的是当前 PATH 里的 npm。如果你连npm命令都找不到那说明环境变量本身就没配好得先回到 PATH 配置这一步再谈目录管理。这和很多人遇到npm 不是内部或外部命令是同一个根因。拿到全局目录之后扫描包的时候要特别注意 scoped 包。以vue/cli为例它在磁盘上的结构是node_modules/vue/cli也就是说fs.readdirSync第一层看到的是vue这个目录而不是包名。如果直接把vue当成一个包来统计结果会完全对不上。正确的做法是遇到以开头的目录时多下钻一层处理子目录。function listTopPackages(globalRoot) { const result []; for (const name of fs.readdirSync(globalRoot)) { if (name.startsWith(.)) continue; const full path.join(globalRoot, name); if (name.startsWith() fs.statSync(full).isDirectory()) { for (const sub of fs.readdirSync(full)) { const scopedPath path.join(full, sub); if (fs.existsSync(path.join(scopedPath, package.json))) { result.push(scopedPath); } } } else if (fs.existsSync(path.join(full, package.json))) { result.push(full); } } return result; }读取每个包的信息很简单package.json里已经有name、version、bin字段。真正费劲的是统计体积。3.2 目录大小统计要防符号链接循环算目录大小最直接的想法是递归遍历累加文件字节数。这个思路没问题但实际跑的时候必须处理两个坑符号链接循环和.bin快捷方式。现代包管理器npm 7 的 arborist会在node_modules里创建符号链接来优化重复依赖。如果递归时不加保护遇到node_modules/pkg/node_modules/pkg指回上层的情况轻则重复计费重则栈溢出。我的处理方案是维护一个已访问真实路径的 Set用fs.realpathSync去重。function getDirSize(root, seen new Set()) { const real fs.realpathSync(root); if (seen.has(real)) return 0; seen.add(real); let total 0; for (const entry of fs.readdirSync(root, { withFileTypes: true })) { const full path.join(root, entry.name); if (entry.isSymbolicLink()) continue; if (entry.isDirectory()) { total getDirSize(full, seen); } else if (entry.isFile()) { total fs.statSync(full).size; } } return total; }跳过符号链接会丢一部分真实占用这是有意为之符号链接指向的内容通常已经在别的目录里统计过重复加进去只会让数字虚高。.bin目录里的快捷方式同理它只是入口不是包本体。缓存目录的统计方法又不一样。缓存目录里的文件数量可能上万而且全是哈希名继续逐文件递归也不是不行但可以用 Node 20 的fs.readdirSync(..., { recursive: true })一次拿到全量列表再累加文件大小。我在跑的时候发现统计一个 3GB 的缓存目录通常只需要十几秒属于可接受范围。3.3 识别孤儿依赖候选并生成清理脚本项目级 node_modules 的清理风险最高所以方案里对项目的处理逻辑不是扫完就删而是先找出孤儿依赖候选。所谓孤儿依赖就是存在于node_modules顶层、但不在项目package.json的dependencies、devDependencies、optionalDependencies、peerDependencies声明中的包。function findOrphans(nmDir, pkgMeta) { const declared new Set([ ...Object.keys(pkgMeta.dependencies || {}), ...Object.keys(pkgMeta.devDependencies || {}), ...Object.keys(pkgMeta.optionalDependencies || {}), ...Object.keys(pkgMeta.peerDependencies || {}), ]); const orphans []; for (const entry of fs.readdirSync(nmDir, { withFileTypes: true })) { if (entry.name.startsWith(.) || entry.name .bin) continue; if (entry.name.startsWith()) { for (const sub of fs.readdirSync(path.join(nmDir, entry.name))) { if (!declared.has(${entry.name}/${sub})) orphans.push(${entry.name}/${sub}); } } else if (!declared.has(entry.name)) { orphans.push(entry.name); } } return orphans; }需要注意的是孤儿候选不等于该删。它可能是被 npm 合法提升上来的传递依赖直接删除会让某些深层 import 瞬间失效。我的方案只把它们列出来最终的清理动作交给npm prune或者开发者手动判断。clean --confirm生成的脚本同样不是用来直接执行的它只是一张已被确认的动作清单。Windows 上我生成.cmd而不是.ps1原因后面细说。脚本内容大致是这个风格echo off REM generated by nlpm on 2025-01-15 call npm uninstall -g vue/cli call npm cache clean --forcenpm cache clean --force来自缓存超阈值后的建议而全局卸载命令来自全局包分析。用户看到脚本内容后可以整段执行也可以删掉不想执行的某一行。这种药方模式让清理过程全程可控实测反馈非常有效。4. 实测一个季度数据、清理动作和踩坑记录方案写完只是第一步真正让它可信的是在真实环境里的长期运行。我拿自己的开发机当试验田跑了完整一个季度前后数据有明显对比也踩了不少坑。4.1 前后数据对照清理不是归零是可控第一次扫描时我的开发机状态是这样的项目第一次 scan全局包76 个共 2.84 GB缓存目录3.2 GB项目 node_modules11 个项目共 18.4 GB看起来挺吓人但实际上真正值得立刻动的没那么多。我按报告做了三轮清理全局包卸载了vue/cli等 5 个超过半年没更新且确认不再依赖的 CLI 工具释放约 900MB。缓存当时缓存超过我自己设定的 2GB 阈值执行了一次npm cache clean --force直接降到约 300MB 的基础量。项目依赖对 3 个老项目跑了npm prune清掉约 1.1GB 的孤儿依赖。一个季度后再扫描数据变成了这样项目一个季度后全局包24 个共 680 MB缓存目录稳定在 1.6 GB 左右项目 node_modules13 个项目共 21.2 GB新增了两个项目缓存没有继续膨胀回 3GB是因为阈值触发后脚本会自动提醒新增项目也让我清楚看到了又多了 3GB 依赖的增量来源。管理后的状态不是归零而是每块盘地的体积和内容随时可查且行动点明确。4.2 五个真实踩坑从 PATH 到 PowerShell 执行策略第一坑全局包目录在C:\Program Files下时卸载需要管理员权限。最初我在普通权限终端里跑卸载直接报 EPERM。解决的路径不是每次都用管理员终端而是把 npm 全局前缀改到用户目录例如npm config set prefix %APPDATA%\npm然后把新 bin 目录加入 PATH。这个操作要小心改完前缀之后原来装在 Program Files 下的全局包不会自动迁移需要重新安装需要的 CLI。第二坑PATH 漏配会导致明明装了全局包却提示不是内部或外部命令。在 Windows 上Node 装在D:\nodejs时PATH 里至少要包含D:\nodejs和全局 bin 目录。我建议扫描前先用npm prefix -g拿到准确路径拿到的路径如果不在当前 PATH报告第一行就应该提醒而不是等用户敲命令时才发现。第三坑PowerShell 执行策略。很多人在 Windows 上直接敲npm会看到这样的报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这不是 npm 坏了而是 PowerShell 默认的 Restricted 策略不允许执行.ps1脚本。解决办法是给当前用户放开执行权限Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser或者干脆一直调用npm.cmd而不是npm。正因为这个原因我生成的清理脚本在 Windows 上坚持用.cmd后缀绕开执行策略再去多解释一堆为什么。第四坑符号链接导致统计爆栈。这是我第一版脚本踩过的坑。某个 monorepo 项目里存在多层符号链接递归统计时直接把栈打爆。加了realpathSync去重之后问题彻底解决这个经验在前面代码里已经体现。第五坑scoped 包的统计口径。我第一版把vue当成了一个普通包报告里出现一个占 500MB 的 vue后来细看目录才发现下面有vue/cli和vue/babel-plugin等一串子包。把每个 scoped 子包拆开统计之后报告的可读性和准确度才真正可以用于决策。5. 扩展思路镜像源统计与定时任务基础方案跑顺之后我又加了两个扩展点都属于可选增强不影响核心的 scan/report/clean 逻辑。5.1 用 package-lock.json 统计依赖来源很多开发者会把 npm 的 registry 配成国内镜像源来加速安装常见的有淘宝源、腾讯源、华为源等。这个现象其实可以利用起来每个项目的package-lock.json里每个依赖项的resolved字段都会包含真实下载来源的 URL从中可以统计出当前项目的依赖来源分布。const lock JSON.parse(fs.readFileSync(./package-lock.json, utf8)); const hosts new Map(); for (const key of Object.keys(lock.packages || {})) { const pkg lock.packages[key]; if (pkg.resolved) { const host new URL(pkg.resolved).hostname; hosts.set(host, (hosts.get(host) || 0) 1); } } console.log(hosts);跑完就能看到有多少依赖来自默认官方源、有多少来自镜像源是否混用了多个源。混源在一些公司内网环境里会导致锁文件不一致这个统计能尽早发现问题。5.2 定时扫描与半自动清理的平衡第二个扩展是自动化扫描。核心命令只有一行nlpm scan nlpm report --top 10 ~/.nlpm/report.txt在 Windows 上可以用任务计划程序在 Linux 和 macOS 上可以用 cron。我自己的节奏是每周一早上跑一次报告自动生成不用刻意打开来看感觉磁盘不对的时候再翻一眼。定时扫描的意义不仅仅是养成习惯更是让索引文件保持新鲜这样当你突然需要判断该不该清理时数据立刻可用。但在自动化这件事上我有一个强烈倾向不要全自动清理。全局包和项目依赖的删减都应该保留人工确认这一步。唯一可以考虑自动执行的只有缓存清理因为它的误伤风险最低且重新下载依赖的成本通常可以接受。我见过为了省事把自动清理全开了的人一个月后根本不记得报告里那些包是干什么用的最后反而更焦虑。整套方案最让我满意的不是扫出了多少垃圾而是把安全边界设计得很清晰扫描只读清理生成脚本执行交回给用户。如果你也天天被 npm 目录体积困扰我建议先跑一次 scan 看看真实数据再决定动哪一块。你可以完全照抄这里的代码也可以只借这个思路——反正脚本就几百行跑上一周你对本地包目录的把握感会完全不一样。最后提醒一句改全局目录之前先备份 PATH 和 npmrc 配置这一点比任何清理操作都重要。