如何在 Mac 上安全清除 npm 缓存

npm 缓存不是项目的依赖树

npm 的缓存是跨项目复用的下载缓存，默认位于 ~/.npm，但配置可能把它放到别处。它按内容寻址存储软件包，内容写入和读出时都会校验完整性。node_modules 是某个项目实际安装的依赖，package.json 和 package-lock.json 则定义依赖；它们都不是缓存。清缓存不会删除现有的 node_modules，删除 node_modules 也不会清掉 npm 缓存。

先找到、测量并验证 npm 实际使用的缓存

不要因为 ~/.npm 存在，就认定它正是 npm 在用的缓存。用 npm --version 和 npm config get cache 查看版本和真实路径，对输出的准确路径运行 du -sh（路径含空格时要加引号），再执行 npm cache verify。verify 会检查索引和内容的完整性、清除不需要的数据，同时保留有效的下载内容；日常维护或排查安装故障，都应该从这一步开始。

1. 运行 npm --version 和 npm config get cache，确认输出的是缓存目录，而不是某个项目目录。
2. 对输出的准确路径运行 du -sh，并记下 macOS 的可用空间；不要把猜出来的路径交给 rm -rf。
3. 停止正在执行 npm install、npm ci、npm exec 或发布操作的进程，然后运行 npm cache verify 并保存结果。
4. 只有测量后仍然值得清理、而且之后网络和依赖源都可用时，才运行 npm cache clean --force。
5. 再次运行 npm cache verify，测量同一路径，并在不改动 package.json 和锁文件的情况下，安装并构建一个有代表性的项目。

不要一边清缓存、一边删除锁文件。缓存状态和依赖解析同时变化，你就失去了诊断原问题所需的对照；如果还要离线工作，也应保留可用的缓存。

只在确有理由时才强制清空

npm cache clean --force 会清空配置所指的共享缓存，丢掉离线安装和 prefer-offline 可以复用的下载内容；之后多个项目的首次安装都会变慢，并且要求 registry、私有源、代理和网络都可用。只在这条命令里使用 --force，不要把 force 写进持久配置。它修不好 ERESOLVE、认证、引擎版本、原生编译或安装脚本的错误。

保护锁文件和离线能力，并验证结果

清理期间，源代码、package.json、package-lock.json 和私有 registry 配置都保持不变。npm v12 已不再读取 npm-shrinkwrap.json；旧项目要把这个格式相同的文件重命名为 package-lock.json，而不是把它当缓存删掉。清理后重新运行 npm config get cache、npm cache verify 和 du，再用一个有代表性的项目按原锁文件安装和构建；如果出现的还是同一个错误，就别再反复清缓存了——问题在别处。

清理边界与恢复成本

在 Mac 上清除 npm 缓存前，先用 npm config get cache 找到实际位置并测量，再运行 npm cache verify；确有必要才用 npm cache clean --force，同时保护 node_modules、package.json 和锁文件。

常见问题