npm command not found 排查检查清单

这份清单用于排查 npm command not found。完整流程见 npm command not found 怎么解决。目标是先确认本机命令环境，再判断项目包管理器和客户权限边界。

不要一边猜一边改项目文件。先填清单，找出是 Node 没安装、终端没刷新、PATH 没配置，还是项目其实不该用 npm。

适合谁

适合运行 npm install、npm run dev、npm run build 时看到命令找不到的新手。你可以按顺序填，避免把环境问题误判成代码问题。

也适合项目前快速收集材料。客户截图不完整时，用这份清单向客户要信息。

不适合谁

不适合没有授权就远程改客户电脑、服务器或部署平台的人。环境配置可能影响其他项目，不能随便动。

也不适合直接删除锁文件、重装所有依赖或混用包管理器。先确认项目约定，再执行安装命令。

风险提醒

不要把未验证的猜测写成结论。比如“Node 没装”“npm 坏了”“项目坏了”都需要证据。

如果需要客户提供管理员权限、远程桌面、CI 设置、部署平台截图或公司电脑配置，先写成待确认事项。没有授权前，不要承诺能直接修。

具体步骤

按下面顺序检查：

1. 记录系统和终端
2. 检查 node -v
3. 检查 npm -v
4. 检查命令路径
5. 重新打开终端
6. 查看项目锁文件
7. 查看 package.json
8. 按项目约定选择包管理器
9. 记录仍需客户确认的事项

每一步只改变一个变量。不要同时重装 Node、删除依赖、换包管理器，否则很难判断问题来源。

系统和终端

• 操作系统：
• 终端类型：
• 是否刚安装 Node：
• 是否重启过终端：
• 是否使用 nvm、fnm、volta：
• 是否在客户设备上：

终端类型很重要。Windows PowerShell、CMD、Git Bash 可能表现不同；macOS Terminal 和其他 shell 也可能加载不同配置。

版本检查

运行：

node -v
npm -v

记录结果：

• node -v 输出：
• npm -v 输出：
• 完整报错：

如果两个命令都找不到，先处理 Node 安装或 PATH。只有 npm 找不到时，再看安装方式。

路径检查

Windows：

where.exe node
where.exe npm

macOS / Linux：

which node
which npm

路径检查能帮助判断系统到底有没有找到命令。输出为空时，不要继续跑项目命令。

项目检查

查看项目文件：

• 是否有 package-lock.json
• 是否有 pnpm-lock.yaml
• 是否有 yarn.lock
• package.json 是否写了 packageManager
• README 是否指定安装命令

如果项目要求 pnpm 或 yarn，就按项目要求处理。不要为了省事把所有项目都当 npm 项目。

客户待确认

常见待确认包括：

• 客户使用哪个系统
• 报错发生在本地还是 CI
• 客户是否允许安装 Node
• 客户是否能提供完整日志
• 客户是否能提供仓库权限
• 部署平台 Node 版本由谁确认

这些事项不要写成已完成。需要客户回复时，就写成明日待办。

验证记录

修复后记录：

node -v:
npm -v:
install command:
build or test command:
result:
remaining items:

如果只修复了本机命令，不代表项目一定能构建。交付时要区分“npm 命令可用”和“项目构建成功”。

交付说明检查

交付时建议写成三段：已确认、已处理、待确认。已确认写系统、终端、Node/npm 输出和项目包管理器；已处理写你实际做过的动作；待确认写客户权限、CI 日志、部署平台设置或管理员操作。

不要只写“npm 已修复”。更准确的写法是：“当前终端已能识别 npm；项目安装命令仍需按 README 使用 pnpm；部署平台 Node 设置待客户确认。”这类说明更长一点，但能减少误会。

复盘检查

排查结束后，把这次问题归档成一个小案例。记录触发命令、最初输出、最终判断、有效动作和无效动作。下次再遇到类似报错，就不用重新猜。

如果这次是在客户项目里排查，还要记录哪些事情没有做。例如没有修改服务器、没有改部署平台、没有删除锁文件、没有升级依赖。这能防止客户把未包含事项误认为已经处理。

不要继续的信号

遇到这些情况先停下来：客户要求你直接登录生产服务器、客户无法说明项目用哪个包管理器、CI 日志无法查看、公司电脑需要管理员权限、部署平台设置由另一个人负责、你看不懂 PATH 修改会影响什么。

暂停时可以把问题写成下一步确认，而不是硬做。比如“需要客户确认是否允许安装 Node”“需要客户提供 CI 日志”“需要项目负责人确认包管理器”。这比在不清楚权限时继续操作更安全。

CTA：下一步

把这份清单复制到排查记录里，先填系统、终端和版本输出。需要解释报错用 报错解释器，需要评估项目范围用 项目报价助手。

免责声明

本文只用于学习和排查记录，不构成安全、法律、职业或收入承诺。真实客户环境需要客户授权和人工复核。