故障排除

常见安装问题

Windows 安装问题：WSL 中的错误

操作系统/平台检测问题：如果您在安装过程中收到错误，WSL 可能正在使用 Windows npm。请尝试：

• 在安装前运行 npm config set os linux
• 使用 npm install -g @anthropic-ai/claude-code --force --no-os-check 安装

找不到 Node 错误：如果在运行 claude 时看到 exec: node: not found，您的 WSL 环境可能正在使用 Windows 安装的 Node.js。使用 which npm 和 which node 确认，它们应该指向以 /usr/ 开头的 Linux 路径。

nvm 版本冲突：如果您在 WSL 和 Windows 中都安装了 nvm，可能会遇到版本冲突。

解决方案：确保 nvm 在您的 shell 中正确加载：

# 添加到 ~/.bashrc 或 ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Linux 和 Mac 安装问题

推荐解决方案：原生 Claude Code 安装

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

验证安装：

claude doctor

权限和身份验证

重复的权限提示

使用 /permissions 命令允许特定工具在没有批准的情况下运行。

身份验证问题

如果您遇到身份验证问题：

1. 运行 /logout 完全登出
2. 关闭 Claude Code
3. 使用 claude 重新启动并再次完成身份验证过程

如果问题仍然存在：

rm -rf ~/.config/claude-code/auth.json
claude

性能和稳定性

高 CPU 或内存使用率

• 定期使用 /compact 来减少上下文大小
• 在主要任务之间关闭并重新启动 Claude Code
• 考虑将大型构建目录添加到您的 .gitignore 文件中

命令挂起或冻结

• 按 Ctrl+C 尝试取消当前操作
• 如果无响应，关闭终端并重新启动

搜索和发现问题

如果搜索工具不起作用，请安装系统 ripgrep：

# macOS (Homebrew)
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

然后设置 USE_BUILTIN_RIPGREP=0。

IDE 集成问题

WSL2 上未检测到 JetBrains IDE

选项 1：配置 Windows 防火墙

# 以管理员身份打开 PowerShell
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

选项 2：切换到镜像网络

添加到 .wslconfig：

[wsl2]
networkingMode=mirrored

JetBrains 终端中 ESC 键不起作用

1. 转到 Settings → Tools → Terminal
2. 取消选中"使用 Escape 将焦点移动到编辑器"

Markdown 格式问题

代码块中缺少语言标签

解决方案：

• 要求 Claude 添加语言标签
• 使用后处理钩子自动格式化

获取更多帮助

• 使用 /bug 命令直接向 Anthropic 报告问题
• 运行 /doctor 检查 Claude Code 安装的健康状况
• 直接向 Claude 询问其功能和特性