学了个寂寞

Appearance

故障排查 ​

安装问题速查 ​

看到的错误解决方案
command not found: claude 或 'claude' is not recognized修复 PATH
syntax error near unexpected token '<'安装脚本返回 HTML
curl: (56) Failure writing output先下载脚本再运行
Killed（Linux 上安装时）添加 swap 空间
TLS/SSL 连接错误更新 CA 证书
irm is not recognized 或 && is not valid使用正确的 shell 命令
Claude Code on Windows requires git-bash安装或配置 Git Bash
Error loading shared library错误的二进制版本（musl/glibc）
OAuth error 或 403 Forbidden修复认证问题

排查安装问题 ​

检查网络连通性 ​

安装包从 storage.googleapis.com 下载。先验证能否访问：

bash
curl -sI https://storage.googleapis.com

如果失败，可能原因：

  • 企业防火墙或代理拦截了 Google Cloud Storage
  • 地区网络限制：尝试 VPN 或其他网络
  • TLS/SSL 问题：更新系统 CA 证书

如果在企业代理后面，安装前设置代理环境变量：

bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

验证 PATH 设置 ​

安装成功但运行 claude 报找不到命令，说明安装目录不在 PATH 中。

安装位置：

  • macOS/Linux：~/.local/bin/claude
  • Windows：%USERPROFILE%\.local\bin\claude.exe

macOS/Linux 修复：

bash
# Zsh（macOS 默认）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash（Linux 默认）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 修复：

powershell
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

重开终端后运行 claude --version 验证。

具体问题解决 ​

command not found 安装后找不到命令 ​

zsh: command not found: claude
bash: claude: command not found
'claude' is not recognized as an internal or external command

参见上面的 验证 PATH 设置。

安装脚本返回 HTML ​

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell 里表现为：Invoke-Expression: Missing argument in parameter list.

说明安装 URL 返回了 HTML 页面而不是脚本。如果页面显示"App unavailable in region"，说明你所在地区不支持 Claude Code。

解决方案：

bash
# macOS/Linux 用 Homebrew
brew install --cask claude-code

# Windows 用 WinGet
winget install Anthropic.ClaudeCode

或者等几分钟后重试。

curl: (56) 写入错误 ​

连接中断导致脚本下载失败。

解决方案：

  1. 测试网络连通性：curl -fsSL https://storage.googleapis.com -o /dev/null
  2. 使用 Homebrew 或 WinGet 替代安装方式

内存不足被强制终止 ​

bash: line 142: 34803 Killed    "$binary_path" install ...

Linux 系统内存不足，OOM killer 杀掉了进程。需要至少 4GB 可用内存。

添加 swap 空间：

bash
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 然后重新安装
curl -fsSL https://claude.ai/install.sh | bash

TLS 或 SSL 连接错误 ​

curl: (35) TLS connect error
SSL/TLS secure channel could not be established
unable to get local issuer certificate

解决方案：

bash
# Ubuntu/Debian 更新 CA 证书
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

企业代理 TLS 检查导致的问题，设置企业 CA 证书：

bash
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

Windows: irm 或 && 命令无法识别 ​

  • irm 无法识别：你在 CMD 里，不是 PowerShell。打开 PowerShell 或者用 CMD 安装命令：

    batch
    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

  • && 无效：你在 PowerShell 里却用了 CMD 命令。用 PowerShell 安装命令：

    powershell
    irm https://claude.ai/install.ps1 | iex

Windows: 需要 Git Bash ​

安装并运行 Git for Windows，安装时选择"Add to PATH"。

如果已安装但仍报错，在 settings.json 中指定路径：

json
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Linux: 库文件缺失 ​

Error loading shared library libstdc++.so.6: No such file or directory

可能安装了错误的二进制版本（musl vs glibc）。

检查系统类型：

bash
ldd /bin/ls | head -1

Alpine Linux 安装缺失的包：

bash
apk add libgcc libstdc++ ripgrep

认证问题 ​

反复提示权限确认 ​

运行 /permissions 将常用命令加入白名单，避免每次都要确认。详见权限配置。

认证失败或 OAuth 错误 ​

  1. 运行 /logout 完全退出
  2. 关闭 Claude Code
  3. 重新运行 claude 完成认证

如果浏览器没有自动打开，按 c 复制 OAuth URL，手动粘贴到浏览器。

OAuth error: Invalid code

登录码过期或被截断。按 Enter 重试，要在浏览器打开后快速完成操作。

403 Forbidden ​

  • Claude Pro/Max 用户：在 claude.ai/settings 确认订阅有效
  • Console 用户：确认账户有"Claude Code"或"Developer"角色
  • 企业代理：代理可能干扰 API 请求，参见网络配置

"This organization has been disabled" ​

环境变量 ANTHROPIC_API_KEY 覆盖了你的订阅认证。取消设置：

bash
unset ANTHROPIC_API_KEY
claude

同时检查 ~/.zshrc、~/.bashrc 或 ~/.profile 中的 export ANTHROPIC_API_KEY=... 行，删除它。

WSL 相关问题 ​

WSL2 中 JetBrains IDE 检测不到 ​

配置 Windows 防火墙（推荐）：

  1. 找到 WSL2 IP：wsl hostname -I
  2. 以管理员身份打开 PowerShell 创建防火墙规则：
    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
    根据实际 IP 调整范围。
  3. 重启 IDE 和 Claude Code

切换到镜像网络模式（可选）：

在 Windows 用户目录的 .wslconfig 中添加：

ini
[wsl2]
networkingMode=mirrored

然后运行 wsl --shutdown 重启。

WSL2 中 OAuth 登录失败 ​

浏览器无法在 WSL 中打开。设置浏览器路径：

bash
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

或者按 c 复制登录 URL，手动在 Windows 浏览器打开。

WSL 中搜索结果缓慢或不完整 ​

跨文件系统工作时会有磁盘读取性能损耗，导致搜索结果减少。

解决方案：

  1. 搜索更具体：指定目录或文件类型
  2. 移项目到 Linux 文件系统：/home/ 目录下而不是 /mnt/c/
  3. 用原生 Windows：性能更好

性能问题 ​

CPU 或内存占用高 ​

  1. 定期运行 /compact 减小上下文大小
  2. 任务之间关闭并重启 Claude Code
  3. 在 .gitignore 中添加大型构建目录

搜索和 @文件 不工作 ​

安装系统 ripgrep：

bash
# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

然后设置环境变量 USE_BUILTIN_RIPGREP=0。

配置文件位置 ​

文件用途
~/.claude/settings.json用户设置（权限、hooks、模型覆盖）
.claude/settings.json项目设置（提交到 git）
.claude/settings.local.json本地项目设置（不提交）
~/.claude.json全局状态（主题、OAuth、MCP 服务器）
.mcp.json项目 MCP 服务器（提交到 git）

重置配置（会删除所有设置和会话历史）：

bash
rm ~/.claude.json
rm -rf ~/.claude/
rm -rf .claude/
rm .mcp.json

获取更多帮助 ​

  1. 在 Claude Code 内：运行 /feedback 直接向 Anthropic 报告问题
  2. 运行诊断：/doctor 检查安装状态、配置文件、MCP 服务器、插件错误等
  3. GitHub Issues：在 github.com/anthropics/claude-code 查看已知问题
  4. 直接问 Claude：Claude 有访问自己文档的能力，可以回答关于功能和配置的问题

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策