文档版本：v1.0
编写日期：2026/06/25
适用环境：Windows 10 / 11 + npm 全局安装的 Claude Code
适用版本：2.1.183 → 2.1.191（通用，可推广到后续小版本升级）

---

目录

1. 背景
2. 升级前的诊断
3. 标准升级流程（三步法）
4. Hardlink 修复方案（推荐）
5. 升级/修复标准操作清单（SOP）
6. 常见问题（FAQ）
7. 附录 A：本次升级关键证据
8. 附录 B：关键文件路径速查
9. 附录 C：应急一行命令

---

1. 背景

在 Windows 上使用 npm 全局安装的 Claude Code (@anthropic-ai/claude-code) 时，升级后常出现以下两类问题：

1. 旧版本残留：PATH 中存在多个 claude 入口（npm bin、.local\bin），升级时未清理导致版本错乱。

2. 二进制丢失告警：升级后执行 claude 时提示：

   ⚠ claude command at C:\Users\lgzhu\.local\bin\claude.exe missing or broken
          · run claude install to repair
   

   原因：.local\bin\claude.exe 并非 npm 实际安装的产物，而是一个 npm 在安装早期生成的浅拷贝/硬链接；升级时该链接断裂。

本文档记录标准化的"清理 → 重装 → 修复"三步流程，并给出 Hardlink 修复告警的脚本化方案。

---

2. 升级前的诊断

在执行升级前，先用以下命令摸清现状：

# 1) 查看当前版本
claude --version

# 2) 查看 PATH 中所有 claude 入口
where.exe claude

# 3) 查看 .local\bin 下文件是否存在、大小
Get-Item C:\Users\lgzhu\.local\bin\claude.exe

# 4) 查看 npm 全局安装路径下真实的可执行文件
Get-Item C:\Users\lgzhu\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe

典型输出（升级前）：

PS D:\myprog\X-ray.inspection> claude --version
2.1.183 (Claude Code)

PS C:\Users\lgzhu> where.exe claude
C:\Users\lgzhu\.local\bin\claude.exe
C:\Users\lgzhu\AppData\Roaming\npm\claude
C:\Users\lgzhu\AppData\Roaming\npm\claude.cmd

关键观察点：

• C:\Users\lgzhu\AppData\Roaming\npm\ 是 npm 全局 bin 目录，claude / claude.cmd 是真品。
• C:\Users\lgzhu\.local\bin\claude.exe 是可疑的第三方副本，升级时它不会随 npm 包自动更新，迟早会出现版本漂移。

---

3. 标准升级流程（三步法）

Step 1 — 清理旧入口

目的：把所有非 npm 全局 bin 目录下的 claude.exe / claude / claude.cmd 全部删除，避免版本错乱。

# 1.1 列出所有 claude 入口
where.exe claude

# 1.2 逐个删除 PATH 中非 npm 全局 bin 的副本
Remove-Item C:\Users\lgzhu\.local\bin\claude.exe -Force -ErrorAction SilentlyContinue
# 若有其他位置残留（如 scoop、chocolatey 安装的），同样删除
# Remove-Item <other-path>\claude.exe -Force

# 1.3 验证
where.exe claude
# 此时应只剩 npm 全局 bin 下的两个条目

说明

• C:\Users\lgzhu\AppData\Roaming\npm\claude 和 claude.cmd 不能删，那是 npm 的 shim。
• .local\bin\claude.exe 是可删的，后面会用 Hardlink 重新指回真品。

Step 2 — 重新安装最新版本

# 2.1 全局安装最新版（npm 会自动选择 latest tag）
npm install -g @anthropic-ai/claude-code

# 2.2 验证版本
claude --version

典型输出：

PS C:\Users\lgzhu> npm install -g @anthropic-ai/claude-code
changed 2 packages in 6s
npm warn allow-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn allow-scripts   @anthropic-ai/claude-code@2.1.191 (postinstall: node install.cjs)

PS C:\Users\lgzhu> claude --version
2.1.191 (Claude Code)

⚠ 告警说明：allow-scripts 警告是 npm 8+ 的安全机制，不影响安装。
如果希望消除该告警，可执行 npm approve-scripts @anthropic-ai/claude-code，
授予 postinstall 脚本权限。

Step 3 — 验证并处理启动告警

升级成功后执行：

claude

可能出现的告警：

 ▐▛███▜▌   Claude Code v2.1.191
▝▜█████▛▘  minimax-m3 · API Usage Billing
  ▘▘ ▝▝    D:\myprog\X-ray.inspection
 ⚠ claude command at C:\Users\lgzhu\.local\bin\claude.exe missing or broken
        · run claude install to repair

告警解读：

• Claude Code 启动时检测到 C:\Users\lgzhu\.local\bin\claude.exe 这个外部路径，但它已不可用。

• 真实的可执行文件在 npm 包内：

  C:\Users\lgzhu\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe
  

• 约 220 MB 的 Node.js 打包二进制。

---

4. Hardlink 修复方案（推荐）

4.1 设计思路

与其复制（220 MB 磁盘开销），不如用 NTFS Hardlink 把 .local\bin\claude.exe 指向 npm 包内的真实文件：

方案	磁盘开销	升级同步	推荐度
复制 (Copy-Item)	220 MB / 每次升级	❌ 不会自动同步	⭐
符号链接 (Symlink)	0 字节	✅	⭐⭐⭐
硬链接 (Hardlink)	0 字节	✅	⭐⭐⭐⭐⭐

硬链接 vs 软链接：两者都不占额外空间，但 Hardlink 对 npm 重新安装（inode 重建）更鲁棒——
New-Item -ItemType HardLink -Force 在目标已存在时会被强制覆盖，而软链接需要先 Remove-Item。

4.2 修复命令（一行）

New-Item -ItemType HardLink -Path C:\Users\lgzhu\.local\bin\claude.exe -Target C:\Users\lgzhu\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe -Force

参数说明：

• -ItemType HardLink：创建 NTFS 硬链接（要求源与目标在同一卷上，本例都在 C:，符合）。
• -Path：链接的虚拟路径（PATH 中希望暴露的位置）。
• -Target：真实文件的绝对路径。
• -Force：若链接已存在则覆盖。

4.3 验证修复

# 1) 直接执行 .local\bin 下的二进制
& "C:\Users\lgzhu\.local\bin\claude.exe" --version
# 期望输出：2.1.191 (Claude Code)

# 2) 再次启动 claude，确认告警消失
claude

期望输出（无告警）：

 ▐▛███▜▌   Claude Code v2.1.191
▝▜█████▛▘  minimax-m3 · API Usage Billing
  ▘▘ ▝▝    D:\myprog\X-ray.inspection

4.4 自动化脚本（可选）

将以下内容保存为 D:\scripts\fix-claude-hardlink.ps1，双击或计划任务触发：

<#
.SYNOPSIS
  重建 .local\bin\claude.exe → npm 全局安装包的 Hardlink
.DESCRIPTION
  当 Claude Code 启动报 "claude command at ...\claude.exe missing or broken"
  时运行本脚本。
#>

$Source = "C:\Users\lgzhu\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe"
$Link   = "C:\Users\lgzhu\.local\bin\claude.exe"

if (-not (Test-Path $Source)) {
    Write-Error "Source not found: $Source`n请先执行：npm install -g @anthropic-ai/claude-code"
    exit 1
}

# 确保目标目录存在
$linkDir = Split-Path $Link -Parent
if (-not (Test-Path $linkDir)) { New-Item -ItemType Directory -Path $linkDir | Out-Null }

# 创建/重建 Hardlink
New-Item -ItemType HardLink -Path $Link -Target $Source -Force | Out-Null

# 验证
$version = & $Link --version
Write-Host "✅ Hardlink 已修复：$Link -> $Source" -ForegroundColor Green
Write-Host "✅ 当前版本：$version" -ForegroundColor Green

用法：

.\fix-claude-hardlink.ps1

---

5. 升级/修复标准操作清单（SOP）

复制以下清单到 notes 或工单系统，每次升级逐项打勾：

[ ] 1. claude --version                            记录当前版本
[ ] 2. where.exe claude                            记录所有入口
[ ] 3. Remove-Item .local\bin\claude.exe           清理可疑副本
[ ] 4. npm install -g @anthropic-ai/claude-code    升级
[ ] 5. claude --version                            确认升级成功
[ ] 6. claude                                      启动看告警
[ ] 7. 若告警含 .local\bin\claude.exe missing → 跑 Hardlink 修复命令
[ ] 8. & ".local\bin\claude.exe" --version         验证 Hardlink 生效
[ ] 9. claude                                      二次启动确认无告警

---

6. 常见问题（FAQ）

Q1：为什么不直接 npm install -g 升级，要先删 .local\bin\claude.exe？

因为 where.exe claude 输出的顺序就是 PATH 命中顺序。如果 .local\bin 在 AppData\Roaming\npm 之前（常见于先装 Node.js 后装 Claude 的情况），你 claude --version 看到的版本可能一直是 .local\bin 那个陈旧副本。删除可疑副本可避免版本错乱。

Q2：Hardlink 在不同卷上能工作吗？

不能。NTFS Hardlink 要求源与目标位于同一卷。本例两者都在 C:，满足。
如果跨卷，请改用 cmd /c mklink 创建符号链接（SymbolicLink），或直接 Copy-Item 接受 220 MB 占用。

Q3：升级后立刻又出现告警，是什么原因？

npm 在升级时会重新生成 node_modules\@anthropic-ai\claude-code\bin\claude.exe，导致 Hardlink 的源 inode 变化。不要复制——直接重跑修复命令即可，Hardlink 重建是幂等的。

Q4：allow-scripts 警告需要处理吗？

不影响功能，但每次升级都会刷一次警告。若想消除：

npm approve-scripts @anthropic-ai/claude-code

或在 ~/.npmrc 添加：

allow-scripts[@anthropic-ai/claude-code]=true

Q5：如何确认 .local\bin\claude.exe 是 Hardlink 而非独立文件？

fsutil hardlink list C:\Users\lgzhu\.local\bin\claude.exe

会输出至少两个路径（链接本身 + 源文件），证明是 Hardlink。

---

7. 附录 A：本次升级关键证据

时间	事件	关键输出
升级前	当前版本	2.1.183 (Claude Code)
升级前	PATH 入口	.local\bin\claude.exe、AppData\Roaming\npm\claude、.cmd
升级中	npm install	changed 2 packages in 6s
升级中	allow-scripts 警告	@anthropic-ai/claude-code@2.1.191 (postinstall: node install.cjs)
升级后	新版本	2.1.191 (Claude Code)
升级后	启动告警	⚠ claude command at C:\Users\lgzhu\.local\bin\claude.exe missing or broken
修复后	Hardlink 验证	& "C:\Users\lgzhu\.local\bin\claude.exe" --version → 2.1.191 (Claude Code)

---

8. 附录 B：关键文件路径速查

用途	绝对路径
真实可执行文件（npm 包内）	C:\Users\lgzhu\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe
npm 全局 shim（cmd）	C:\Users\lgzhu\AppData\Roaming\npm\claude.cmd
npm 全局 shim（posix）	C:\Users\lgzhu\AppData\Roaming\npm\claude
第三方/历史副本（应删除或 Hardlink）	C:\Users\lgzhu\.local\bin\claude.exe
npm 全局根目录	C:\Users\lgzhu\AppData\Roaming\npm\
npm 全局 node_modules	C:\Users\lgzhu\AppData\Roaming\npm\node_modules\

---

9. 附录 C：下一次撞到同样告警时的应急

一行命令（记住即可）：

New-Item -ItemType HardLink -Path C:\Users\lgzhu\.local\bin\claude.exe -Target C:\Users\lgzhu\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe -Force

原理：npm 重新安装时重写了源 inode，Hardlink 失效。-Force 覆盖重建即可，0 字节磁盘开销。

---