npm 装依赖报错？从 registry、缓存到 lock 文件的排错指南

前端同学对 npm install 的红字并不陌生：ERESOLVE 依赖冲突、ECONNRESET 网络中断、ENOENT 文件丢失。npm 的错误种类繁多，但排查逻辑一致。本文按『网络 → 缓存 → 依赖树』顺序拆解。

一、registry 与网络问题

默认的 npm 官方源在国内常不稳定，先确认源地址：

1. npm config get registry 查看当前源，若为 https://registry.npmjs.org/ 可考虑切换。
2. 改用国内镜像：npm config set registry https://registry.npmmirror.com。
3. 网络抖动报 ECONNRESET 时，加 npm install --fetch-retries=5 --fetch-timeout=120000 提升容错。

二、缓存损坏的清理

中断的安装可能留下坏缓存，导致反复失败。标准动作：

1. npm cache verify 先校验缓存完整性。
2. 仍不行就 npm cache clean --force 强制清空，再重新安装。

三、ERESOLVE 依赖冲突

peerDependencies 不兼容是 npm 7+ 的常见坑。处理：

1. 先看完整冲突信息，找出哪个包要求了互斥版本。
2. 优先升级自身依赖到兼容版本，而非强行忽略。
3. 确实急需时可用 npm install 包名 --legacy-peer-deps 退回到旧解析策略，但属临时方案。

四、lock 文件与 node_modules 不一致

1. 团队协作出 ENOENT 或行为不一致，常因 package-lock.json 与本地不符。
2. 彻底重建：删除 node_modules 与 package-lock.json，再 npm install。
3. Windows 上长路径易触发 ENAMETOOLONG，可在 .npmrc 加 legacy-Dcom.sun.management.jmxremote 类似无效，正确做法是开启系统长路径支持，或用 npm install --no-audit --no-fund 减少干扰。

五、Node 版本不匹配

某些包要求 Node 18+，旧版本会编译失败。用 node -v 核对，必要时用 nvm 切换：nvm install 18 && nvm use 18。

技术小结：npm 安装失败遵循『查源与网络 → 清缓存 → 解依赖冲突 → 重建 lock』的递进思路。优先用镜像与重试解决网络，用升级依赖而非 –legacy-peer-deps 解决冲突，方能保证可复现构建。