Buck Blog · 博客正文

返回技术分享首页
Claude Code 自动升级失败后的手动重装指南

Claude Code 自动升级失败后的手动重装指南

> 一次 npm 半途夭折留下的临时目录，让终端里的 claude 直接罢工。
> 本文记录根因、临时目录的来历，以及一条能稳定复现的修复路径。

一、现象

某个早上打开终端，习惯性敲下 claude，等来的不是欢迎界面，而是一段报错：


module not found

或者更直接一点：


claude: command not found

但 which claude、npm ls -g 又都能看到它"装在那儿"。也就是说：包目录存在，但内容不完整——典型的"升级升到一半被打断"。

二、根因

Claude Code 通过 npm install -g @anthropic-ai/claude-code 安装，并且默认开启了自动更新。自动更新本质上就是在后台跑一次全局 npm install：

  • 把新版包下载到一个临时目录（形如 @anthropic-ai/.claude-code-XXXXXXXX，后缀是随机串）；
  • 解包、校验；
  • 用临时目录原子替换掉正式的 @anthropic-ai/claude-code。

问题出在第 3 步之前被打断——网络抖动、npm 缓存损坏、磁盘写满、进程被杀、终端被关。

此时磁盘上会残留两种"半成品"：

残留物 说明
@anthropic-ai/.claude-code-<随机串> 升级用的临时目录，是个"点开头"的隐藏目录
@anthropic-ai/claude-code 正式目录，可能已被清空或只写了一半

之后无论你是手动 npm install -g 还是等它自己再更新，npm 都会看到"目录已存在"而直接跳过或报错，于是一直卡在坏状态。不清掉这两个目录，任何重装都是白费。

三、手动重装步骤

以下命令按顺序执行即可。以 Node v22.22.3 + nvm 为例。

1. 清空 npm 缓存

缓存里可能存着上次下载失败的坏 tarball，先强制清掉：


npm cache clean --force

2. 删掉两个残留目录


rm -rf /home/huamingh/.nvm/versions/node/v22.22.3/lib/node_modules/@anthropic-ai/.claude-code-sIPnA3NY
rm -rf /home/huamingh/.nvm/versions/node/v22.22.3/lib/node_modules/@anthropic-ai/claude-code

> 注意：第一行的随机后缀（这里是 sIPnA3NY）每次都不一样，要用 ls -a 看一下自己机器上实际残留的名字：
>
> 



> ls -a /home/huamingh/.nvm/versions/node/v22.22.3/lib/node_modules/@anthropic-ai/

>

>
> 目录里所有 .claude-code-* 的点目录都可以放心删。

3. 确认 Node 环境


node -v
npm config get registry
node -v 用来核对上面的路径版本号对不对；npm config get registry 用来确认当前 registry——这一步很关键，下面会讲。

4. 走国内镜像重新安装


npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

5. 验证


claude --version

能打印出版本号，说明装好了；再敲一次 claude 进入交互界面确认。

四、为什么要显式指定 npmmirror

这是整篇里最容易被忽略的一点。

registry.npmjs.org 在国内网络下经常出现大包下载中断——而"下载中断"恰好就是本文第一节那个残留临时目录的最主要成因。显式加上： 

--registry=https://registry.npmmirror.com

走阿里云镜像，下载稳定得多，一次成功的概率大幅提高。

如果这台机器长期在国内用，建议直接固化下来，省得每次手敲：


npm config set registry https://registry.npmmirror.com

五、一页速查

发生"升级完 claude 跑不起来"时，直接按这段抄：


npm cache clean --force


ls -a /home/huamingh/.nvm/versions/node/v22.22.3/lib/node_modules/@anthropic-ai/

# 按实际输出删掉 .claude-code-<随机串> 和 claude-code

rm -rf /home/huamingh/.nvm/versions/node/v22.22.3/lib/node_modules/@anthropic-ai/.claude-code-*

rm -rf /home/huamingh/.nvm/versions/node/v22.22.3/lib/node_modules/@anthropic-ai/claude-code



node -v

npm config get registry

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

claude --version

六、小结

  • 症状：claude 命令存在但跑不起来，多半是包目录被写坏了。
  • 根因：自动升级是一次 npm install -g，中途被打断就会留下 .claude-code-<随机串> 临时目录和半个正式目录。
  • 关键：必须先删干净这两个目录，否则后续任何重装都会被 npm 跳过或拒绝。
  • 预防：把 registry 指到 registry.npmmirror.com，减少下载中断的概率。

顺便说一句，nvm 切换 Node 版本后，claude 也需要在新版本下重新装一次——路径里的 v22.22.3 就是版本隔离的直接体现。