Claude Code 依赖安装失败怎么排查?

文章导读
依赖安装失败这个问题,在 Claude Code 这类通过 npm 分发的工具上,其实不算少见。你可能会看到很长的报错,比如某些包找不到、peerDependencies 冲突,也可能只是停在下载阶段。我的习惯是先不看最后的堆栈,而是把错误日志里的关键行找出来:ETIMEDOUT、EACCES、ERESOLVE,这三种关键词对应着不同的处理路线。
📋 目录
  1. A 先看 Node 版本和 npm 是不是对得上
  2. B 网络问题先从日志和 registry 入手
  3. C 权限报错要修目录所有者,不要硬上 sudo
  4. D 缓存和锁文件会导致重复出现旧版本
  5. E ERESOLVE 依赖冲突别急着加 --legacy-peer-deps
A A

依赖安装失败这个问题,在 Claude Code 这类通过 npm 分发的工具上,其实不算少见。你可能会看到很长的报错,比如某些包找不到、peerDependencies 冲突,也可能只是停在下载阶段。我的习惯是先不看最后的堆栈,而是把错误日志里的关键行找出来:ETIMEDOUT、EACCES、ERESOLVE,这三种关键词对应着不同的处理路线。

先看 Node 版本和 npm 是不是对得上

依赖安装失败时,最先排查的往往是Node.js环境是否匹配。运行node -v和npm -v查看当前版本,Claude Code通常需要Node 18或更高版本,但过新的Node版本也可能触发引擎检查失败。如果版本不满足,建议使用nvm切换,例如nvm install 18,然后nvm use 18。一个常见坑是终端会话未刷新导致版本还是旧的,切换后要确认which node指向正确。

这里需要做的验证不只是看 node -v 输出。比如你已经切到 18,但 npm 仍然用旧目录,运行 which node 看路径是否在 ~/.nvm/versions/node/v18.x.x/bin/node。npm config get prefix 也能帮你确认 npm 默认装到哪个目录。还要注意 Claude Code 如果是全局安装,那它用的 node 是当前 PATH 里的 node,不是某个项目里配置的 engines。如果项目里存在 .nvmrc,最好用 nvm use 读取它。风险在于,如果你为了用 Claude Code 把 node 升级到最新版,但项目本身的依赖还没适配新版 npm 引擎,可能会引发其他错误,所以建议锁定一个 Claude Code 官方维护的版本范围,比如 20 LTS。

网络问题先从日志和 registry 入手

npm安装时如果卡在fetch或报ETIMEDOUT,多半是网络问题。可以先看完整错误日志,找到对应的registry地址。若怀疑公司网络限制,尝试设置镜像或代理,例如npm config set registry https://registry.npmmirror.com,或为npm单独配置proxy。注意镜像只解决下载慢,如果包本身需要从GitHub拉取,可能还需要配置git代理。不要急于反复重试,先测试npm ping看能否连上registry。

Claude Code 依赖安装失败怎么排查?

实际排查时,我会先跑 npm config get registry 确认当前走的源。然后运行 npm ping --registry 具体地址来测连通性。如果 ping 通过但安装仍失败,就需要看 npm 的日志文件,默认在 npm config get cache 目录下,日志文件以 _debuglog 为后缀。Windows 下可能是管理员权限问题。注意有时候是本地 DNS 解析问题,可以用 nslookup registry.npmjs.org 对比。另外,镜像源往往不会同步 npm 上的所有包版本,如果安装的包不在镜像里,会报 404,这时需要切换回官方 registry。

权限报错要修目录所有者,不要硬上 sudo

权限问题在用户目录和系统目录混装时很常见。如果你用 sudo npm install -g 安装了 Claude Code,之后普通用户运行 npm install -g @anthropic-ai/claude-code 升级时可能提示 EACCES。先运行 npm config get prefix,如果 prefix 是 /usr/local,那建议改成当前用户目录;如果用的是 nvm,那么全局包会放在 nvm 的 node_modules 里,通常不会有权限问题。还有一个容易忽略的点:项目目录本身如果是 root 所有,普通用户也没有写权限,需要先确认 ls -l 你的项目目录。

不要抱着“可能再试一次就好了”的心态,因为 EACCES 不会自己消失。手动修复权限时,可以递归处理用户目录下的 .npm 目录,比如 chmod -R 777 是不建议的,正确做法是 chown -R 当前用户 ~/.npm。如果你在用 nvm,直接重新执行 nvm use 后重装 Node,npm 的全局目录会自动归到用户目录下,省去手动调权限的步骤。

缓存和锁文件会导致重复出现旧版本

有时候你明明改动了 package.json,但重新安装还是拿到旧的版本。这可能是 npm 缓存里存了损坏的 tarball。先运行 npm cache verify,它会检查缓存完整性。如果无效,再 npm cache clean --force。清缓存之后最好确认 package-lock.json 里的包版本是否和期望一致。如果清缓存后问题依旧,可以删除 node_modules 和 package-lock.json,然后重新 npm install。这个操作要小心,因为 package-lock.json 是锁定版本的依据,删掉后 npm 会重新解析依赖,可能引入和你本地不同的子依赖版本。在团队协作时建议保留 lock 文件,只删 node_modules。另外,如果你用的是 npm ci,它要求 package-lock.json 和 package.json 一致,缓存坏了也会导致失败,且 npm ci 不会自动更新 lock 文件。所以缓存问题要区分是不是 lock 文件本身写错了。

Claude Code 依赖安装失败怎么排查?

ERESOLVE 依赖冲突别急着加 --legacy-peer-deps

当错误信息中包含ERESOLVE或peer dep missing时,是依赖版本冲突。Claude Code自身依赖若干包,如果项目里已有不同版本的同名包,npm会拒绝安装。此时可以尝试npm install --legacy-peer-deps跳过自动校验,但这只是绕过问题,可能带来运行时行为差异。更推荐用npm ls检查冲突来源,然后调整项目依赖的版本范围,或使用overrides字段强制指定公共依赖的版本。注意不要随意对所有项目都加--legacy-peer-deps。

处理冲突前要明白 peerDependencies 的含义。例如某个包要求 react 18,但你的项目里 react 是 17,npm 会直接报错。可以用 npm ls react 来查看链上版本。如果看到多个版本,试着用 overrides 统一版本。注意 overrides 不能直接覆盖 peer dependencies,所以更稳妥的做法是升级或降级主依赖版本。当你最终用 --legacy-peer-deps 成功安装后,需要手测 Claude Code 的核心功能,确认没有因为 peer 依赖版本错配导致运行时错误。如果你正在 CI 里构建,要格外小心,因为 CI 环境干净,可能无法安装成功。

整体上,我建议按错误关键词来做分支判断。ETIMEDOUT 看网络,EACCES 看权限,ERESOLVE 看依赖树,如果都不是,再看 Node 版本和缓存。每一步操作后都要重新运行 npm install,观察错误是否变化。如果错误信息变了,说明你在接近问题根源。