npm install失败

一句话：运行 npm install 时依赖下载、版本冲突、权限、网络或锁文件导致安装失败。

它是什么

npm install失败是前端和Node.js项目最常见的问题之一。原因可能是Node版本不对、package-lock冲突、依赖版本不兼容、网络源不可用、权限不足，或某个原生依赖编译失败。

适合干什么

• 第一次运行前端项目的新手
• 接手别人GitHub项目的开发者
• 用Codex、Claude Code修复项目环境的人
• 部署前需要恢复依赖的团队

不适合干什么

• 完全不是Node.js项目的报错
• 生产环境严重安全漏洞的临时绕过
• 不知道自己运行目录的人
• 没有package.json的项目

普通人怎么用

• 确认当前目录有package.json
• 查看Node和npm版本
• 删除node_modules和package-lock.json后重新安装
• 切换稳定网络或npm镜像
• 把完整报错复制给AI分析

进阶用户怎么用

• 用nvm切换项目要求的Node版本
• 区分依赖冲突、构建失败和权限问题
• 使用npm ci保证锁文件一致
• 把安装步骤写进README或Dockerfile

常见误区

• 不看第一条真正报错，只复制最后一行
• 在错误目录运行npm install
• 随便加--force导致依赖更乱
• 本地能装但CI环境Node版本不同

和相似工具的区别

• npm install vs npm ci：npm install会更新依赖解析，npm ci严格按锁文件安装，更适合CI和部署环境。
• --force vs --legacy-peer-deps：--force更激进，可能忽略更多保护；--legacy-peer-deps主要绕过peer依赖冲突。

入门步骤

• 确认目录
• 检查Node版本
• 清理依赖
• 重新安装
• 查看首个错误
• 处理冲突
• 记录修复步骤

推荐工具（第三方）

Node.js、npm、nvm、pnpm、Yarn、Codex