文档版本v1.0编写日期2026/06/25适用环境Windows 10 / 11 npm 全局安装的 Claude Code适用版本2.1.183 → 2.1.191通用可推广到后续小版本升级目录背景升级前的诊断标准升级流程三步法Hardlink 修复方案推荐升级/修复标准操作清单SOP常见问题FAQ附录 A本次升级关键证据附录 B关键文件路径速查附录 C应急一行命令1. 背景在 Windows 上使用 npm 全局安装的 Claude Code (anthropic-ai/claude-code) 时升级后常出现以下两类问题旧版本残留PATH 中存在多个claude入口npm bin、.local\bin升级时未清理导致版本错乱。二进制丢失告警升级后执行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-ItemC:\Users\lgzhu\.local\bin\claude.exe# 4) 查看 npm 全局安装路径下真实的可执行文件Get-ItemC:\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-ItemC:\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 tagnpm 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-code2.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.inspection4.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 时运行本脚本。 #$SourceC:\Users\lgzhu\AppData\Roaming\npm\node_modules\anthropic-ai\claude-code\bin\claude.exe$LinkC:\Users\lgzhu\.local\bin\claude.exeif(-not(Test-Path$Source)){Write-ErrorSource not found:$Sourcen请先执行npm install -g anthropic-ai/claude-codeexit1}# 确保目标目录存在$linkDirSplit-Path$Link-Parentif(-not(Test-Path$linkDir)){New-Item-ItemType Directory-Path$linkDir|Out-Null}# 创建/重建 HardlinkNew-Item-ItemType HardLink-Path$Link-Target$Source-Force|Out-Null# 验证$version $Link--versionWrite-Host✅ Hardlink 已修复$Link-$Source-ForegroundColor GreenWrite-Host✅ 当前版本$version-ForegroundColor Green用法.\fix-claude-hardlink.ps15. 升级/修复标准操作清单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. 常见问题FAQQ1为什么不直接npm install -g升级要先删.local\bin\claude.exe因为where.exe claude输出的顺序就是 PATH 命中顺序。如果.local\bin在AppData\Roaming\npm之前常见于先装 Node.js 后装 Claude 的情况你claude --version看到的版本可能一直是.local\bin那个陈旧副本。删除可疑副本可避免版本错乱。Q2Hardlink 在不同卷上能工作吗不能。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 重建是幂等的。Q4allow-scripts警告需要处理吗不影响功能但每次升级都会刷一次警告。若想消除npmapprove-scriptsanthropic-ai/claude-code或在~/.npmrc添加allow-scripts[anthropic-ai/claude-code]trueQ5如何确认.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 installchanged 2 packages in 6s升级中allow-scripts 警告anthropic-ai/claude-code2.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.exenpm 全局 shimcmdC:\Users\lgzhu\AppData\Roaming\npm\claude.cmdnpm 全局 shimposixC:\Users\lgzhu\AppData\Roaming\npm\claude第三方/历史副本应删除或 HardlinkC:\Users\lgzhu\.local\bin\claude.exenpm 全局根目录C:\Users\lgzhu\AppData\Roaming\npm\npm 全局 node_modulesC:\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 重新安装时重写了源 inodeHardlink 失效。-Force覆盖重建即可0 字节磁盘开销。