WSL2 Ubuntu 中 Claude CLI “command not found” 故障排查与修复

WSL2 Ubuntu 中 Claude CLI "command not found" 故障排查与修复

环境：Windows 11 + WSL2 + Ubuntu 22.04 + Node.js (nvm) + Claude Code CLI

问题：长期使用的 claude 命令突然提示 command not found

1. 现象

在终端中输入：

claude --dangerously-skip-permissions

报错：

claude: command not found

检查 ~/.local/bin/claude 不存在，source ~/.bashrc 也无效。

2. 排查过程

2.1 检查是否真正安装过

find /home/lium -name "claude" -type f 2>/dev/null

输出：

/home/lium/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude
/home/lium/.vscode-server/extensions/anthropic.claude-code-2.1.220-linux-x64/resources/native-binary/claude

说明二进制文件确实存在，但未在 PATH 中暴露。

2.2 检查 PATH 是否包含 Node 的 bin 目录

echo $PATH | grep "v20.20.2/bin"

无输出，说明 nvm 管理的 Node.js 二进制目录不在 PATH 中（或被其他配置覆盖）。

2.3 检查 PATH 整体

$PATH 中包含大量 Windows 路径（如 C:\...）和一个错误片段 Unknown command: "bin"，严重干扰了 Linux 命令查找。

3. 根本原因

• Claude CLI 实际是通过 npm 全局安装的 @anthropic-ai/claude-code 包提供的，其可执行文件位于 node_modules 深层目录。
• 安装时本应自动创建软链接到 $HOME/.nvm/versions/node/v20.20.2/bin/ 下，但该链接丢失或从未创建（可能是 npm 全局链接损坏、手动清理或权限问题）。
• 同时，PATH 环境变量混乱，未包含该 bin 目录，导致即使文件存在也无法识别。

4. 解决方案

4.1 手动创建软链接（无需重新下载）

ln -sf /home/lium/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude ~/.nvm/versions/node/v20.20.2/bin/claude

4.2 将 Node 的 bin 目录添加到 PATH 并持久化

echo 'export PATH="$HOME/.nvm/versions/node/v20.20.2/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

4.3 验证

claude --dangerously-skip-permissions

成功启动 Claude Code 界面，问题解决。

5. 补充建议（国内用户）

由于网络环境，重新下载可能较慢。本方案利用已有二进制，无需下载。若需重新安装，建议先配置 npm 镜像：

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude

并确保 nvm 的 bin 目录在 PATH 中。

6. 预防措施

• 检查 PATH 是否包含 $HOME/.nvm/versions/node/$(nvm current)/bin。
• 避免将 Windows 路径直接放入 WSL 的 PATH（可在 ~/.bashrc 开头重置 PATH）。
• 定期检查全局 npm 包的链接是否完整。

---

一句话总结 ：command not found 不一定代表软件未安装，很多时候只是可执行文件没有被正确链接到 PATH 中，找到真实文件并恢复链接即可快速修复。