如何在 Mac 上安全清除 npm 缓存
AskClean 团队 · 更新于 2026-08-05
先运行 npm config get cache 找到当前缓存，再测量该路径并执行 npm cache verify。只有确实需要磁盘空间、且接受以后重新下载依赖时，才运行 npm cache clean --force。它不会删除 node_modules、package.json 或锁文件；也不应和删除这些项目文件混成一次操作。
npm 缓存不是项目依赖树
npm 默认把跨项目复用的内容寻址下载缓存放在 ~/.npm，但配置可能改变位置。node_modules 是某个项目实际安装的依赖，package.json 和 package-lock.json 则定义依赖；它们都不是缓存。清缓存不会删除现有 node_modules，删除 node_modules 也不会清掉 npm 缓存。
先找到、测量并验证 npm 实际使用的缓存
不要因为 ~/.npm 存在就认定它正在使用。用 npm --version 和 npm config get cache 获取版本与真实路径，对输出的准确路径运行 du -sh，再执行 npm cache verify。verify 会检查索引和内容完整性、清理不需要的数据，同时保留有效下载；一般维护或安装故障都应从这里开始。
- 运行 npm --version 和 npm config get cache，确认输出是缓存目录而不是项目目录。
- 对输出的准确路径运行 du -sh，并记录 macOS 剩余空间；不要把猜测的路径交给 rm -rf。
- 停止正在执行 npm install、npm ci、npm exec 或发布的进程，然后运行 npm cache verify 并保存结果。
- 只有测量后仍值得清理、且后续网络与依赖源可用时，才运行 npm cache clean --force。
- 再次运行 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，并用一个代表性项目按原锁文件安装、构建；同一错误仍出现时应停止反复清缓存。
清理边界与恢复成本
找到并测量 npm 在 macOS 上实际使用的下载缓存，先验证、必要时再清除，同时保护 node_modules、package.json 和锁文件。
| 项目或操作 | 检查位置 | 删除后果 |
|---|---|---|
| npm 缓存不是项目依赖树 | npm config get cache | npm 默认把跨项目复用的内容寻址下载缓存放在 ~/.npm，但配置可能改变位置。node_modules 是某个项目实际安装的依赖，package.json 和 package-lock.json 则定义依赖；它们都不是缓存。清缓存不会删除现有 node_modules，删除 node_modules 也不会清掉 npm 缓存。 |
| 先找到、测量并验证 npm 实际使用的缓存 | npm cache verify | 不要因为 ~/.npm 存在就认定它正在使用。用 npm --version 和 npm config get cache 获取版本与真实路径，对输出的准确路径运行 du -sh，再执行 npm cache verify。verify 会检查索引和内容完整性、清理不需要的数据，同时保留有效下载；一般维护或安装故障都应从这里开始。 |
| 只在有理由时运行强制清理 | npm cache clean --force | npm cache clean --force 会清除配置所指的共享缓存，丢掉离线与 prefer-offline 可复用的下载；之后多个项目的首次安装会更慢，并依赖 registry、私有源、代理和网络可用。只在这条命令中使用 --force，不要把 force 设成持久配置。它不能修复 ERESOLVE、认证、引擎、原生编译或安装脚本错误。 |
| 保护锁文件、离线能力并验证结果 | install + offline/private-registry check | 清理期间保持源码、package.json、package-lock.json 与私有 registry 配置不变。npm v12 已不再读取 npm-shrinkwrap.json；旧项目需要把格式相同的文件重命名为 package-lock.json，不能把它当缓存删除。清理后重跑 npm config get cache、npm cache verify 和 du，并用一个代表性项目按原锁文件安装、构建；同一错误仍出现时应停止反复清缓存。 |
常见问题
应该用 npm cache verify 还是 npm cache clean？
先用 npm cache verify。只有为了已测量的空间回收，或 verify 无法解决的确定缓存故障，才使用 npm cache clean --force。
清除 npm 缓存会删除 node_modules 吗？
不会。前者是配置所指的共享下载存储，后者是项目内的已安装依赖，需要单独处理。
清缓存后安装为什么仍然失败？
问题可能来自认证、网络或代理、包版本不可用、Node.js 引擎、依赖解析、原生编译或生命周期脚本。保存第一条有效错误并诊断，不要反复删除有效下载。
参考来源