npm install 失败是前端开发中最高频的阻塞点之一。盲目地尝试“重试”或“删除 node_modules”往往收效甚微。准确的分类排查才是解决问题的正道。
错误分类与排查方向
1. 网络连接类
表现为 timeout, connection reset, DNS error 或 fetch failed。
- 排查点：网络稳定性、国内镜像源配置、公司内网代理限制。
2. 运行环境类
表现为 engine 不兼容、Node 版本过高或过低。
- 排查点：项目要求的 Node 版本与本机实际版本的匹配度。
3. 脚本执行类
表现为包已下载但 postinstall、prepare 或原生模块编译阶段报错。
- 排查点：本地编译环境（如 Python, C++ Build Tools）是否完备。
4. 依赖冲突类
表现为 dependency conflict, peer dependency 冲突或 lockfile mismatch。
- 排查点：
package-lock.json与package.json的一致性，以及 npm 版本的兼容性。
5. 文件权限类
表现为 EPERM, permission denied 或 cannot write。
- 排查点：目录读写权限、杀毒软件拦截或同步盘占用。
推荐排障步骤
- 只读分析报错：要求 Codex 重点查看报错中间段的详细信息，而非仅看最后的
npm ERR!。 - 网络问题：切换镜像源或调整代理。
- 版本问题：使用
nvm切换至项目要求的 Node 版本。 - 权限问题：检查目录权限。
- 不要一上来就删目录：如果根因是网络或版本，删除目录后重试依然会失败。
- 保持环境纯净：避免在一次排查中乱试各种镜像源或全局配置。
- 利用 Codex 只读能力：先让 Codex 归类错误原因，再给出最小化执行步骤。
2. 定位具体层级：明确是下载失败、脚本失败还是冲突失败。
3. 针对性修复：
4. 谨慎清理：仅在确定依赖树损坏且上述方法无效时，再考虑删除 node_modules 和锁文件。