AI排查npm/pnpm失败 | lockfile和Node版本

title: " AI排查npm/pnpm失败 | lockfile和Node版本" category: 人工智能 tags:

大模型API中转站
4SAPI
AI排错
npm
pnpm
Node.js
依赖安装 description: "npm install、npm ci、pnpm install 失败时，不要上来删除 node_modules。本文讲如何把 Node 版本、包管理器、lockfile、registry、peer dependency 和 CI 环境整理给 AI，并用 4SAPI 做模型分工。"

前端项目最容易卡人的报错之一：

npm install 失败。
pnpm install 失败。
npm ci 失败。

网上最常见建议：

删除 node_modules。
删除 lockfile。
清缓存。
重装。

有时能好。

但这不是排查。

这是碰运气。

用 AI 处理依赖安装失败，关键是让它先判断失败类型。

1. 依赖失败先看五件事

Node 版本。
包管理器。
lockfile。
registry。
错误第一行。

给 AI 的材料：

node -v
npm -v
pnpm -v

以及：

package.json。
lockfile 类型：package-lock.json / pnpm-lock.yaml / yarn.lock。
失败日志最后 100 行。
是否本地失败还是 CI 失败。

不要只贴最后一句：

ELIFECYCLE。

真正根因通常在它上面几十行。

2. 给 AI 的依赖排错包

【环境】
- OS：
- Node：
- npm：
- pnpm：
- 是否 CI：

【项目】
- package manager：
- package.json engines：
- lockfile：
- monorepo：是/否

【错误】
- 执行命令：
- 完整错误最后 100 行：
- 第一个 error：

【最近变更】
- 改了 package.json：
- 改了 lockfile：
- 升级了 Node：
- 换了 registry：
- 新增私有包：

【边界】
- 不建议第一步删除 lockfile
- 不建议随便 --force
- 不建议关闭 peer dependency 检查，除非说明风险

这份包可以让 AI 少猜很多。

3. 常见根因一：lockfile 不同步

CI 里常见：

npm ci can only install packages when package.json and package-lock.json are in sync

pnpm：

ERR_PNPM_OUTDATED_LOCKFILE

根因：

改了 package.json，但 lockfile 没更新或没提交。

修复不是删 lockfile。

通常是本地用正确包管理器重新安装，提交 lockfile。

AI Prompt：

请判断这个安装失败是否由 package.json 和 lockfile 不同步导致。
如果是，请给出不删除 lockfile 的修复步骤。

4. 常见根因二：Node 版本不匹配

错误：

The engine "node" is incompatible
Unsupported engine

或者构建工具要求 Node 20，你本地 Node 18。

AI 要看：

package.json engines。
.nvmrc。
CI setup-node。
Dockerfile node 镜像。
本地 node -v。

修复方向：

统一 Node 版本。
更新 .nvmrc。
更新 CI。
更新 Dockerfile。

不要让 AI 只改本地。

否则 CI 还会挂。

5. 常见根因三：peer dependency 冲突

npm 7+ 对 peer dependency 更严格。

常见错误：

ERESOLVE unable to resolve dependency tree

很多教程会建议：

npm install --legacy-peer-deps

这可以作为临时方案，但不是默认答案。

让 AI 判断：

冲突包是谁。
要求的版本范围是什么。
当前安装版本是什么。
是否有兼容版本。
是否只是旧库 peer 声明过窄。

Prompt：

请分析这个 peer dependency 冲突。
不要直接建议 --force。
请先给兼容版本方案，再说明 legacy-peer-deps 的风险。

6. 常见根因四：私有包或 registry

错误：

401 Unauthorized
404 Not Found
No matching version found

可能是：

npm token 缺失。
.npmrc 没配置。
私有包权限不足。
registry 指向错误。
包版本不存在。

不要把 npm token 给 AI。

只给：

registry 地址。
包名。
是否私有包。
CI 中 secret 是否存在。
错误状态码。

4SAPI 里这类排错应标记为：

risk_level: secret_related

避免模型输出敏感信息。

7. 常见根因五：postinstall 脚本失败

很多安装失败不是下载包失败。

而是 postinstall 失败：

node-gyp rebuild
sharp install
playwright install
prisma generate

这时要看：

系统依赖。
Python。
编译工具链。
平台架构。
网络下载。
二进制缓存。

AI 要从日志中找：

真正失败的子命令。

不要停在 npm 的包装错误。

8. 4SAPI 分工

阶段	模型
日志提取	低成本模型
依赖冲突判断	Fable 5 或中强模型
修复策略	Fable 5
PR/commit 说明	低成本模型

记录字段：

error_type: package_install_failed
package_manager
node_version
lockfile
model
final_fix

这样团队以后知道：

是 Node 版本经常错。
还是 lockfile 经常漏提交。
还是私有包 token 经常失效。

9. AI Prompt

你是 Node.js 依赖安装排查助手。

请根据 node/npm/pnpm 版本、package.json、lockfile 类型、失败日志和最近变更，判断安装失败原因。

重点检查：
1. lockfile 是否同步
2. Node 版本是否匹配
3. peer dependency 冲突
4. registry 或私有包权限
5. postinstall 脚本
6. CI 与本地环境差异

要求：
- 不要把删除 lockfile 作为第一建议。
- 不要直接建议 --force。
- 涉及 token 时不要要求我提供真实值。
- 给最小修复步骤和验证命令。

实战补充：CI 和本地包管理器不一致

一个很常见的坑：

本地用 pnpm。
CI 里用 npm ci。
仓库里同时有 package-lock.json 和 pnpm-lock.yaml。

这种项目非常容易出现：

本地能装，CI 装不上。
本地依赖版本和线上构建版本不同。

让 AI 排查时，可以要求：

请判断当前项目是否混用了多个包管理器。
如果是，请给出统一到一个包管理器的最小改法，并说明需要删除或保留哪些 lockfile。

注意，这里的“删除 lockfile”不是第一反应。

而是在确认包管理器混用之后，作为规范化动作。

落地清单：Node 项目依赖规范

仓库只保留一个 lockfile。
README 写清包管理器。
CI 使用同一个包管理器。
Dockerfile 使用同一个包管理器。
packageManager 字段写入 package.json。
Node 版本写入 .nvmrc 或 engines。

这几条做完，依赖安装失败会少很多。

10. 总结

npm/pnpm 失败不要靠玄学三连：

删 node_modules。
删 lockfile。
清缓存。

先让 AI 看：

Node 版本。
包管理器。
lockfile。
registry。
第一个真正错误。

通过 4SAPI：

低成本模型提取日志。
Fable 5 判断依赖关系。
复核模型检查修复是否会破坏 CI。

一句话：

依赖安装失败，先找第一个 error，不要先清空一切。