npm install 报错排查检查清单

遇到 npm install 报错时，新手很容易直接搜索最后一行错误，然后复制一串命令。更稳的做法是先检查目录、版本、包管理器、网络、权限和授权，再判断下一步。下面这份清单可以配合 Codex 使用，但每一项都要人工确认。

如果你需要完整流程，先读 用 Codex 排查 npm install 报错。如果已经越修越乱，可以看 常见错误和修复顺序。

适合谁

适合正在安装前端项目依赖的新手。你可能遇到 ERESOLVE、EACCES、ENOENT、网络超时、原生模块编译失败、私有包拉取失败等问题，不知道该先看哪里。

也适合准备给客户做小范围诊断的人。清单能帮助你把“安装失败”拆成可验证项，而不是一上来承诺完整修复。

不适合谁

不适合不看日志、不看 package.json、不保留记录的人。npm 报错往往和项目上下文有关，只看一句错误很容易误判。

也不适合处理客户私有 registry、token、公司网络和生产项目时贸然执行大范围修改。遇到这些情况，先确认授权。

风险提醒

清单不能保证安装成功。它只能帮你降低误操作概率。npm 依赖链复杂，老项目尤其可能需要固定 Node 版本、旧依赖、特定系统工具或团队内部说明。

不要把真实 token、私有包地址、客户仓库路径和内部日志公开。需要给 Codex 或其他工具分析时，先脱敏。

具体步骤

1. 目录和文件

• 当前终端是否在项目根目录。
• 当前目录是否有 package.json。
• 是否有 package-lock.json。
• 是否有 pnpm-lock.yaml 或 yarn.lock。
• 是否有 README、.nvmrc、.npmrc 或 engines 字段。

目录不对时，后面的排查都不可靠。

2. 版本信息

• node -v 是否可用。
• npm -v 是否可用。
• Node 版本是否符合项目要求。
• npm 版本是否明显过旧。
• VS Code 终端和系统终端输出是否一致。

如果版本不一致，先记录，不要急着重装。

3. 错误类型

• 是否是依赖冲突，例如 ERESOLVE。
• 是否是权限错误，例如 EACCES 或 access denied。
• 是否是文件缺失，例如 ENOENT。
• 是否是网络错误，例如 timeout、registry、certificate。
• 是否是私有包授权错误，例如 401、403 或 scoped package。

把错误类型分清，才能决定下一步。

4. 低风险验证

• 重新确认命令是否来自项目 README。
• 只运行版本查看命令，不修改文件。
• 先询问 Codex 解释日志，不要求它直接改依赖。
• 只做一次重试，观察错误是否稳定。
• 保存完整输出。

这一步的目标是确认问题，不是立刻修完。

5. 高风险动作

• 删除 package-lock.json。
• 大版本升级 Node。
• 全局清理 npm 缓存。
• 切换 registry 或代理。
• 修改 .npmrc。
• 升级大量依赖。

这些动作不是绝对不能做，但要有理由、有记录，客户项目要先确认。

6. 项目记录

• 客户原始问题是否保存。
• 你检查了哪些文件。
• 运行了哪些命令。
• 错误类型是什么。
• 下一步是否需要客户授权、账号或网络信息。

准备回复客户时，可以用 Proposal 生成器整理问题，但要人工删除不确定承诺。

审核结论怎么写

建议把结论分成四类：环境问题、项目依赖问题、权限授权问题、暂无法判断。环境问题通常是 Node、npm、系统工具；项目依赖问题通常是版本冲突或旧依赖；权限授权问题通常涉及私有包、仓库或网络；暂无法判断表示日志不足或材料缺失。

这个分类适合写进交付记录，也适合用 报价计算器估算下一轮排查时间。

客户任务额外核对

如果这是客户项目，还要多核对几项：客户是否允许你查看完整仓库，是否允许你在本地安装依赖，是否有私有包，是否需要 VPN，是否有指定 Node 版本，是否有部署环境要求。缺少这些信息时，不要把任务写成完整修复。

你可以先交付诊断报告：当前错误类型、需要客户补充的信息、建议下一步。这样即使暂时不能修复，也是在推进问题，而不是原地猜测。

记录模板

可以使用下面的简短格式：

项目目录：
运行命令：
Node/npm 版本：
lockfile 类型：
错误类型：
已尝试动作：
低风险下一步：
需要客户确认：

这份记录也能帮你做复盘。以后遇到类似错误，你会更快判断是环境问题、依赖问题还是授权问题。

CTA：下一步

把最近一次 npm install 失败日志按这份清单标注。先不要执行高风险动作，只整理“已知信息、错误类型、需要确认事项”。需要表格时，从 模板库 里拿排查记录模板。

免责声明

本文是学习用检查清单，不构成法律、财务、安全或职业承诺。具体排查和修改需要结合项目代码、依赖版本、客户授权、平台规则和本地环境人工判断。