古法编程

Appearance

Claude Code 安装失败或登录报错时，先按错误信息对照定位：常见问题包括 command not found: claude、安装脚本返回 HTML、TLS/SSL 连接错误、Windows shell 用错、权限不足和 OAuth/403。根据本页的检查步骤验证网络、PATH、目录权限和认证状态，必要时改用 Homebrew、WinGet 或重新登录。

Claude Code 安装和登录排查 ​

如果你在安装 Claude Code、运行 claude，或者登录时遇到报错，这页可以直接帮你定位原因。先按错误信息找对应修复；如果是 Claude Code 已经能正常启动后的运行问题，去看 Troubleshooting。如果是设置没生效、钩子没触发这类配置问题，去看 Debug your configuration。

查找你的错误 ​

把你看到的报错或现象对照下面的解决方案：

你看到的现象解决方案
command not found: claude 或 'claude' is not recognized修复 PATH
syntax error near unexpected token '<'安装脚本返回 HTML
curl: (22) The requested URL returned error: 403安装脚本返回 403
curl: (23) 或 curl: (56) Failure writing output to destination检查网络连通性或改用其他安装方式
Killed during install on Linux低内存 Linux 服务器添加 swap
TLS connect error 或 SSL/TLS secure channel更新 CA 证书
Failed to fetch version 或无法连接下载服务器检查网络和代理设置
irm is not recognized 或 && is not valid使用对应 shell 的安装命令
'bash' is not recognized as the name of a cmdlet使用 Windows 安装命令
Claude Code on Windows requires either Git for Windows (for bash) or PowerShell安装 shell
Claude Code does not support 32-bit Windows打开 64 位 Windows PowerShell，不要用 x86 入口
The process cannot access the file ... because it is being used by another process清空下载目录后重试
Error loading shared libraryLinux musl 或 glibc 二进制不匹配
Illegal instruction架构或 CPU 指令集不匹配
cannot execute binary file: Exec format error in WSLWSL1 原生二进制回归
PowerShell 安装完成但找不到 claude 或显示旧版本重启终端并检查 PATH
dyld: cannot load, dyld: Symbol not found, or Abort trap on macOS二进制兼容性问题
Invoke-Expression: Missing argument in parameter list安装脚本返回 HTML
App unavailable in regionClaude Code 在你的国家/地区不可用。查看 supported countries。
unable to get local issuer certificate配置企业 CA 证书
OAuth error 或 403 Forbidden修复登录认证
Could not load the default credentials 或 Could not load credentials from any providersBedrock、Vertex 或 Foundry 凭据未加载
ChainedTokenCredential authentication failed 或 CredentialUnavailableErrorBedrock、Vertex 或 Foundry 凭据未加载
API Error: 500, 529 Overloaded, 429, 或其他未列出的 4xx/5xx 错误看 Error reference

如果上面没找到你的情况，继续看下面的诊断步骤，先把问题范围缩小。

如果你想完全跳过终端，Claude Code Desktop app 可以用图形界面安装和使用 Claude Code。可下载 macOS 或 Windows 版本，不需要先配命令行。

运行诊断检查 ​

检查网络连通性 ​

安装器会从 downloads.claude.ai 下载文件。先确认你能访问它：

bash
curl -sI https://downloads.claude.ai/claude-code-releases/latest

如果返回 HTTP/2 200，说明服务器可达。若没有输出、出现 Could not resolve host，或者连接超时，通常是网络把连接拦住了。常见原因有：

  • 企业防火墙或代理阻止访问 downloads.claude.ai
  • 区域网络限制：尝试 VPN 或其他网络
  • TLS/SSL 问题：更新系统 CA 证书，或者检查是否配置了 HTTPS_PROXY

如果你在企业代理后面，在安装前先把 HTTPS_PROXY 和 HTTP_PROXY 设成代理地址。若不知道代理 URL，可以问 IT，或者查看浏览器代理设置。

下面的示例先设置代理变量，再通过代理运行安装器：

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
powershell
$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

验证 PATH 是否生效 ​

如果安装成功了，但运行 claude 时出现 command not found 或 not recognized，通常是安装目录没进 PATH。shell 只会在 PATH 里的目录中查找程序；安装器会把 claude 放到 macOS/Linux 的 ~/.local/bin/claude，或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。

先检查 PATH 里有没有安装目录：

bash
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

如果输出 /Users/you/.local/bin 或 /home/you/.local/bin，说明目录已经在 PATH 里，可以跳到 检查是否有冲突安装。如果没有输出，把它加到 shell 配置里。

Zsh，macOS 默认 shell：

bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bash，大多数 Linux 发行版默认 shell：

bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

也可以直接关闭并重新打开终端。

如果你用的是 fish、Nushell 等其他 shell，把 ~/.local/bin 按照该 shell 的语法加进 PATH，然后重启终端。

验证修复是否生效：

bash
claude --version
powershell
$env:PATH -split ';' | Select-String '\.local\\bin'

如果没有输出，把安装目录加入 User PATH：

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

重启终端后生效。

验证修复是否生效：

powershell
claude --version
batch
echo %PATH% | findstr /i "local\bin"

如果没有输出，打开系统设置里的环境变量，把 %USERPROFILE%\.local\bin 加到 User PATH。然后重启终端。

验证修复是否生效：

batch
claude --version

检查是否有冲突安装 ​

多个 Claude Code 安装会导致版本不一致或行为异常。先看看当前装了哪些：

bash
which -a claude

如果没有输出，说明 PATH 里还没有 claude，回到 验证 PATH 是否生效。

检查 claude 可能来自的三个位置。~/.local/bin/claude 是原生安装器，~/.claude/local/ 是旧版 Claude Code 创建的 legacy 本地 npm 安装，npm 全局列表会显示 -g 安装：

bash
ls -la ~/.local/bin/claude
bash
ls -la ~/.claude/local/
bash
npm -g ls @anthropic-ai/claude-code 2>/dev/null
powershell
where.exe claude

检查原生安装器是否放入了二进制：

powershell
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

如果发现多个安装，只保留一个。推荐保留 macOS/Linux 的 ~/.local/bin/claude，或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。其余删掉：

卸载 npm 全局安装：

bash
npm uninstall -g @anthropic-ai/claude-code

删除旧的本地 npm 安装：

bash
rm -rf ~/.claude/local

Windows 上用 PowerShell：

powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

删除 macOS 上的 Homebrew 安装。如果你装的是 claude-code@latest cask，就把名字换成那个：

bash
brew uninstall --cask claude-code

删除 Windows 上的 WinGet 安装：

powershell
winget uninstall Anthropic.ClaudeCode

检查目录权限 ​

安装器需要对 macOS 和 Linux 上的 ~/.local/bin/ 和 ~/.claude/ 有写权限。Windows 的安装位置在 %USERPROFILE% 下，默认就是当前用户可写，所以这部分通常不适用。

检查目录是否可写：

bash
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

如果其中任何一个目录不可写，先创建安装目录并把所有者改成当前用户：

bash
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

验证二进制能否运行 ​

如果 claude --version 能输出版本号，但 claude 启动就崩溃或卡住，按下面的检查继续缩小范围。若 claude --version 显示 command not found，先看 验证 PATH 是否生效；下面的命令默认 claude 已经在 PATH 里。

确认二进制存在且可执行：

bash
ls -la "$(command -v claude)"

Windows 上用 PowerShell：

powershell
Get-Command claude | Select-Object Source

Linux 上检查缺失的共享库。如果 ldd 显示缺库，可能需要安装系统包。Alpine Linux 和其他 musl 发行版见 Alpine Linux setup。

bash
ldd "$(command -v claude)" | grep "not found"

确认二进制可以执行：

bash
claude --version

常见安装问题 ​

这些是最常见的安装问题和对应修复。

安装脚本返回 HTML 而不是 shell 脚本 ​

运行安装命令时，你可能会看到这些错误之一：

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

在 PowerShell 里，同样的问题会显示为：

text
Invoke-Expression: Missing argument in parameter list.

根据请求路由方式不同，你也可能只看到一个没有 HTML 正文的 403：

text
curl: (22) The requested URL returned error: 403

这些都表示安装 URL 返回了 HTML 页面或错误状态，而不是安装脚本。如果 HTML 页面里写着 "App unavailable in region"，说明 Claude Code 在你的国家/地区不可用。查看 supported countries。

只有状态码的 403 往往也是同一个原因，但也可能是企业代理或防火墙拦截了下载。若你所在地区支持 Claude Code 但仍然看到 403，先按 检查网络连通性 排查，再试下面的替代安装器，因为它们访问的是同一批主机。

否则，这通常是网络问题、区域路由问题，或者临时服务异常。

解决办法：

  1. 改用其他安装方式：

    macOS 上用 Homebrew 安装：

    bash
    brew install --cask claude-code

    Windows 上用 WinGet 安装：

    powershell
    winget install Anthropic.ClaudeCode

  2. 等几分钟后重试：这类问题经常是暂时性的。等一会儿再运行原来的命令。

command not found: claude 安装后仍找不到 ​

安装完成了，但 claude 还是不能用。不同平台报错会略有差异：

平台错误信息
macOSzsh: command not found: claude
Linuxbash: claude: command not found
Windows CMD'claude' is not recognized as an internal or external command
PowerShellclaude : The term 'claude' is not recognized as the name of a cmdlet

这表示安装目录没有进 shell 的搜索路径。每个平台的修复方法见 验证 PATH 是否生效。

curl: (56) Failure writing output to destination ​

curl ... | bash 会先把脚本下载下来，再通过管道交给 Bash 执行。这个错误，以及相关的 curl: (23) Failure writing output to destination，都说明 Bash 没有收到完整脚本。56 表示下载本身中断了；23 表示 curl 收到了内容，但写到管道时失败，通常是 Bash 先退出了。

解决办法：

  1. 检查网络稳定性：Claude Code 二进制托管在 downloads.claude.ai。先测试能否访问：

    bash
    curl -sI https://downloads.claude.ai/claude-code-releases/latest

    如果出现 HTTP/2 200，说明服务器可达，原始失败更可能是偶发问题，重新执行安装命令即可。若看到 Could not resolve host 或连接超时，说明网络正在拦截下载。

  2. 改用其他安装方式：

    macOS：

    bash
    brew install --cask claude-code

    Windows：

    powershell
    winget install Anthropic.ClaudeCode

TLS 或 SSL 连接错误 ​

像 curl: (35) TLS connect error、schannel: next InitializeSecurityContext failed，或者 PowerShell 的 Could not establish trust relationship for the SSL/TLS secure channel，都表示 TLS 握手失败。

解决办法：

  1. 更新系统 CA 证书：

    Ubuntu/Debian：

    bash
    sudo apt-get update && sudo apt-get install ca-certificates

    macOS 上，系统 curl 使用 Keychain 信任库；更新 macOS 本身就会更新根证书。

  2. Windows 上在运行安装器前启用 TLS 1.2：

    powershell
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

  3. 检查代理或防火墙干扰：会做 TLS inspection 的企业代理可能导致这些错误，包括 unable to get local issuer certificate 和 SELF_SIGNED_CERT_IN_CHAIN。在安装步骤里，可以把 curl 指向企业 CA bundle，使用 --cacert：

    bash
    curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash

    Claude Code 安装完成后，如果还需要让它信任同一套证书，把 NODE_EXTRA_CA_CERTS 设进去，这样 API 请求也会信任这份证书：

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

    如果你没有证书文件，找 IT 索取。也可以直接连公网，确认是不是代理导致的。

  4. Windows 上如果看到 CRYPT_E_NO_REVOCATION_CHECK (0x80092012) 或 CRYPT_E_REVOCATION_OFFLINE (0x80092013)，可以绕过证书吊销检查。这说明 curl 已经连到服务器，但你的网络阻止了证书吊销查询，企业防火墙后面很常见。给安装命令加上 --ssl-revoke-best-effort：

    batch
    curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

    也可以直接用 winget install Anthropic.ClaudeCode，这样不用 curl。

Failed to fetch version from downloads.claude.ai ​

安装器无法连接下载服务器。这通常表示你的网络屏蔽了 downloads.claude.ai。

解决办法：

  1. 直接测试连通性：

    bash
    curl -sI https://downloads.claude.ai/claude-code-releases/latest

  2. 如果在代理后面，先设置 HTTPS_PROXY，让安装器通过代理访问。细节见 proxy configuration。

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

  3. 如果网络受限，换个网络或 VPN，或者改用其他安装方式：

    macOS：

    bash
    brew install --cask claude-code

    Windows：

    powershell
    winget install Anthropic.ClaudeCode

Windows 上安装命令用错 ​

如果你看到 'irm' is not recognized、The token '&&' is not valid，或者 'bash' is not recognized as the name of a cmdlet，说明你把别的操作系统或 shell 的安装命令复制过来了。

  • irm not recognized：你现在在 CMD，不是在 PowerShell。你有两种选择：

    打开开始菜单搜索 "PowerShell"，切到 PowerShell 后再运行原始安装命令：

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

    或者继续留在 CMD，改用 CMD 安装器：

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

  • && not valid：你在 PowerShell 里，却跑了 CMD 安装器命令。改用 PowerShell 安装命令：

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

  • bash not recognized：你在 Windows 上用了 macOS/Linux 安装命令。改用 PowerShell 安装命令：

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

Windows 安装时文件被占用 ​

如果 PowerShell 安装器报错 Failed to download binary: The process cannot access the file ... because it is being used by another process，说明安装器没法写入 %USERPROFILE%\.claude\downloads。通常是上一次安装还在跑，或者杀毒软件正在扫描这个目录里的半下载文件。

关闭所有正在运行安装器的 PowerShell 窗口，等杀毒软件把文件释放掉。然后删除下载目录，再重新运行安装器：

powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

低内存 Linux 服务器安装被 Killed ​

如果你在 VPS 或云主机上安装时看到：

text
Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}

说明 Linux 的 OOM killer 因为内存不够杀掉了进程。Claude Code 至少需要 4 GB 可用内存。

解决办法：

  1. 加 swap 空间：如果服务器内存很小，可以用磁盘当作溢出内存，安装就能继续完成。

    创建 2 GB swap 文件并启用：

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

    然后重试安装：

    bash
    curl -fsSL https://claude.ai/install.sh | bash

  2. 安装前关闭其他进程，先释放内存。

  3. 如果可以，换更大的实例。Claude Code 至少需要 4 GB RAM。

Docker 里安装卡住 ​

在 Docker 容器里安装 Claude Code 时，如果以 root 身份在 / 目录下安装，可能会卡住。

解决办法：

  1. 运行安装器前先设定工作目录。如果从 / 执行，安装器会扫描整个文件系统，内存占用会非常高。设置 WORKDIR 可以把扫描范围限制在一个小目录里：

    dockerfile
    WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash

  2. 如果你用的是 Docker Desktop，提高 Docker 内存限制：

    bash
    docker build --memory=4g .

Claude Desktop 会在 Windows 上抢占 claude 命令 ​

如果你安装过较旧版本的 Claude Desktop，它可能会在 WindowsApps 目录注册一个 Claude.exe，并且在 PATH 优先级上盖过 Claude Code CLI。结果就是你运行 claude 时，打开的是 Desktop app，而不是 CLI。

把 Claude Desktop 更新到最新版本即可修复。

Claude Code 在 Windows 上需要 Git for Windows 或 PowerShell ​

如果没有 Git Bash，Claude Code 会改用 PowerShell tool。出现这个错误说明这两种 shell 都没找到。

如果 PowerShell 没有在 PATH 里，它的默认路径是 C:\Windows\System32\WindowsPowerShell\v1.0\。把这个目录加进 PATH，或者安装 PowerShell 7，它会提供 pwsh。

如果你想安装 Git for Windows，去 git-scm.com/downloads/win 下载。安装时勾选 "Add to PATH"。装完后重启终端。这样会启用 Bash tool，适合处理基于 Bash 的脚本和工具链。

如果 Git 已经装了，但 Claude Code 还是找不到它，可以在 settings.json file 里设置路径：

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

如果 Git 装在别的位置，可以在 PowerShell 里运行 where.exe git 找到路径，再把该目录里的 bin\bash.exe 路径填进去。

Claude Code 不支持 32 位 Windows ​

Windows 开始菜单里通常有两个 PowerShell 入口：Windows PowerShell 和 Windows PowerShell (x86)。x86 入口会以 32 位进程运行，即使你机器本身是 64 位，也会触发这个错误。要确认自己在哪种情况下，在报错的那个窗口里运行：

powershell
[Environment]::Is64BitOperatingSystem

如果输出 True，说明系统本身没问题。关闭这个窗口，打开不带 x86 后缀的 Windows PowerShell，再重新运行安装命令。

如果输出 False，说明你用的是 32 位 Windows。Claude Code 需要 64 位操作系统。见 system requirements。

Linux musl 或 glibc 二进制不匹配 ​

如果安装后出现缺少共享库的报错，比如 libstdc++.so.6 或 libgcc_s.so.1：

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

安装器可能下载了不适合你系统的二进制版本。

这类情况会发生在基于 glibc 的系统上装了 musl 交叉编译包，导致安装器误判系统为 musl。

解决办法：

  1. 先确认系统用的是哪种 libc：

    bash
    ldd --version 2>&1 | head -1

    输出里有 GNU libc 或 GLIBC，说明是 glibc。输出里有 musl，说明是 musl。

  2. 如果你是 glibc，但拿到了 musl 二进制，先卸载再重装。你也可以用 https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json 里的 manifest 手动下载正确的二进制。需要上报时，把 ldd --version 和 ls /lib/libc.musl* 的输出一起发到 GitHub issue。

  3. 如果你本来就是 musl 环境，比如 Alpine Linux，就先装这些包：

    bash
    apk add libgcc libstdc++ ripgrep

Illegal instruction ​

如果运行 claude 或安装器时直接输出 Illegal instruction，说明原生二进制用了你的 CPU 不支持的指令。常见有两种原因。

架构不匹配。 安装器下载错了二进制，比如在 ARM 服务器上拿到了 x86 包。在 macOS 或 Linux 上用 uname -m 检查，在 PowerShell 里用 $env:PROCESSOR_ARCHITECTURE 检查。如果结果和你拿到的二进制不一致，把输出发到 GitHub issue。

缺少 AVX 指令集。 如果架构是对的，但还是报 Illegal instruction，说明 CPU 可能没有 AVX 或其他二进制要求的指令。这个问题大约影响 2013 年之前的 Intel/AMD 处理器，以及没有把 AVX 透传给虚拟机的宿主机环境。

在 VPS 或虚拟机里运行 grep -m1 -ow avx /proc/cpuinfo；如果输出为空，说明 guest 看不到 AVX。

这类问题没有原生二进制的绕过方案；状态跟踪见 issue #50384。上报时请附上 CPU 型号：Linux 用 grep -m1 "model name" /proc/cpuinfo，macOS 用 sysctl -n machdep.cpu.brand_string。

替代安装方式下载的是同一个原生二进制，所以也无法解决这两类问题。

macOS 上的 dyld: cannot load ​

如果安装时看到 dyld: cannot load、dyld: Symbol not found，或者 Abort trap: 6，说明二进制与你的 macOS 版本或硬件不兼容。

text
dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

如果 Symbol not found 提到 libicucore，也说明你的 macOS 版本比二进制支持的版本更旧：

text
dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

解决办法：

  1. 检查 macOS 版本：Claude Code 需要 macOS 13.0 或更高版本。打开 Apple 菜单，选择 About This Mac 查看版本。

  2. 升级 macOS，如果你现在的版本太旧。这个错误和系统库、加载命令有关，Homebrew 等替代安装方式也会下载同一个二进制，所以不会解决问题。

WSL1 上的 Exec format error ​

如果你在 WSL 里运行 claude 时看到 cannot execute binary file: Exec format error，说明你在用 WSL1，且碰到了一个已知的原生二进制回归，见 issue #38788。这是二进制程序头变化后，WSL1 的加载器无法处理导致的。

最干净的修复方式是从 PowerShell 把发行版转换到 WSL2：

powershell
wsl --set-version <DistroName> 2

如果你必须留在 WSL1，可以通过动态链接器调用这个二进制。把下面这个函数加到 WSL 里的 ~/.bashrc，如果你的 home 目录路径不同就相应调整：

bash
claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

然后执行 source ~/.bashrc，再重试 claude。

WSL 里的 npm install 错误 ​

这些问题只在你通过 npm install -g 在 WSL 里安装 Claude Code 时适用。如果你用的是 原生安装器，可以跳过这一节。

OS 或平台检测错误。 如果 npm 在安装时提示平台不匹配，WSL 很可能调用到了 Windows 的 npm。先运行 npm config set os linux，再执行 npm install -g @anthropic-ai/claude-code --force。不要用 sudo。

运行 claude 时出现 exec: node: not found。 你的 WSL 环境很可能用了 Windows 版 Node.js。用 which npm 和 which node 确认；路径以 /mnt/c/ 开头的是 Windows 二进制，以 /usr/ 开头的是 Linux 二进制。解决办法是用 Linux 发行版的包管理器安装 Node，或者用 nvm。

nvm 版本冲突。 如果你在 WSL 和 Windows 里都装了 nvm，WSL 切换 Node 版本时可能会出问题，因为 WSL 默认会导入 Windows PATH，Windows 的 nvm 会抢优先级。最常见的原因是 shell 没有加载 nvm。把 nvm 加载器写进 ~/.bashrc 或 ~/.zshrc：

bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

或者在当前会话里手动加载：

bash
source ~/.nvm/nvm.sh

如果 nvm 已经加载，但 Windows 路径仍然优先，可以显式把 Linux Node 路径放到最前面：

bash
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

不要为了规避问题去关闭 Windows PATH 导入，也不要为了 Windows 开发需要去卸载 Windows 里的 Node.js。

安装期间的权限错误 ​

如果原生安装器报权限错误，目标目录可能没有写权限。先看 检查目录权限。

如果你之前是用 npm 安装的，并且碰到了 npm 特有的权限错误，切换到原生安装器：

bash
curl -fsSL https://claude.ai/install.sh | bash

npm 安装后找不到原生二进制 ​

@anthropic-ai/claude-code 这个 npm 包会通过每个平台的 optional dependency 拉取原生二进制，比如 @anthropic-ai/claude-code-darwin-arm64。如果安装后运行 claude 提示 Could not find native binary package "@anthropic-ai/claude-code-<platform>"，检查下面这些原因：

  • optional dependencies 被禁用了。 从 npm 安装命令里去掉 --omit=optional，从 pnpm 里去掉 --no-optional，从 yarn 里去掉 --ignore-optional，并检查 .npmrc 有没有设置 optional=false。然后重新安装。原生二进制只通过 optional dependency 提供，没有 JavaScript fallback，跳过了就没法运行。
  • 平台不受支持。 预编译二进制发布给 darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64 和 win32-arm64。Claude Code 不为其他平台提供二进制；见 system requirements。
  • 企业 npm 镜像缺少平台包。 确认你的 registry 不只镜像 meta package，还镜像这 8 个 @anthropic-ai/claude-code-* 平台包。

如果你用了 --ignore-scripts，不会触发这个错误。因为 postinstall 步骤被跳过了，Claude Code 会退回到一个包装器，每次启动时再去定位并启动平台二进制。这样能用，但启动会更慢；重新安装并启用 scripts 后，会直接执行。

登录和认证 ​

这一部分处理登录失败、OAuth 错误和 token 问题。

重置登录 ​

当登录失败、原因又不明显时，重新干净地认证一次通常能解决大多数情况：

  1. 运行 /logout 完全退出登录
  2. 关闭 Claude Code
  3. 重新运行 claude，再走一遍认证流程

如果登录时浏览器没有自动打开，按 c 复制 OAuth URL 到剪贴板，然后手动贴到浏览器里。这个方法也适用于窄窗口或 SSH 终端里 URL 自动换行、没法直接点击的情况。

OAuth error: Invalid code ​

如果看到 OAuth error: Invalid code. Please make sure the full code was copied，说明登录码过期了，或者在复制粘贴时被截断了。

解决办法：

  • 浏览器打开后尽快按 Enter 重试并完成登录
  • 如果浏览器没有自动打开，输入 c 复制完整 URL
  • 如果你在远程/SSH 会话里，浏览器可能打开在了错误的机器上。把终端里显示的 URL 复制出来，在本地浏览器里打开。

登录后出现 403 Forbidden ​

如果登录后看到 API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}：

  • Claude Pro/Max 用户：在 claude.ai/settings 检查订阅是否仍然有效
  • Anthropic Console 用户：确认账号有 "Claude Code" 或 "Developer" 角色。管理员可在 Anthropic Console 的 Settings → Members 里分配
  • 在代理后面：企业代理可能干扰 API 请求。代理配置见 network configuration

This organization has been disabled 但你明明有订阅 ​

如果你看到 API Error: 400 ... "This organization has been disabled"，但账号确实有活跃的 Claude 订阅，通常是 ANTHROPIC_API_KEY 环境变量覆盖了你的订阅登录。这个问题经常出现在 shell profile 里还留着旧项目、旧雇主的 API key。

当 ANTHROPIC_API_KEY 存在且你已经授权时，Claude Code 会优先使用这个 key，而不是订阅的 OAuth 凭据。在非交互模式且带 -p 参数时，只要环境变量存在，就一定会用这个 key。完整优先级见 authentication precedence。

如果你想改回用订阅登录，先取消这个环境变量，并从 shell profile 里删掉它：

bash
unset ANTHROPIC_API_KEY
claude

检查 ~/.zshrc、~/.bashrc 或 ~/.profile 里有没有 export ANTHROPIC_API_KEY=...，删掉后才能永久生效。Windows 上检查 PowerShell profile 的 $PROFILE，以及 User 环境变量里的 ANTHROPIC_API_KEY。在 Claude Code 里运行 /status，可以确认当前到底用了哪种认证方式。

WSL2、SSH 或容器里的 OAuth 登录失败 ​

当 Claude Code 运行在 WSL2、远程机器的 SSH 会话里，或者容器中时，浏览器通常会打开到另一台主机上，重定向回调也到不了 Claude Code 本地的 callback server。登录后，浏览器通常会显示一个登录码，而不是自动跳回终端。把这个 code 粘贴到终端里 Paste code here if prompted 的提示处，就能完成登录。

如果在 WSL2 里浏览器根本没打开，把 BROWSER 环境变量设成你 Windows 浏览器的路径：

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

也可以在交互式登录提示里按 c 复制 OAuth URL，或者复制 claude auth login 打印出来的 URL，然后在本地机器的浏览器里打开。

如果把 code 粘到交互式提示里没有反应，通常是终端的粘贴快捷键没有真正送进输入框。可以换用终端的其他粘贴方式，Windows Terminal 里常见的是右键或 Shift+Insert；也可以直接用 claude auth login，它会从标准输入读取粘贴的 code：

bash
claude auth login

这个备用方式也适用于原生 Windows，或者任何在交互式提示里粘贴失败的终端。

未登录或 token 过期 ​

如果 Claude Code 在一个会话后又要求你重新登录，通常是 OAuth token 过期了。

运行 /login 重新认证。如果这种情况经常发生，检查系统时间是否准确，因为 token 校验依赖正确时间戳。

在 macOS 上，如果 Keychain 被锁定，或者 Keychain 密码和系统登录密码不同步，也会导致 Claude Code 无法保存凭据。运行 claude doctor 检查 Keychain 访问。要手动解锁 Keychain，运行 security unlock-keychain ~/Library/Keychains/login.keychain-db。如果还是不行，打开 Keychain Access，选中 login keychain，然后用 Edit > Change Password for Keychain "login" 把它和账户密码重新同步。

Bedrock、Vertex 或 Foundry 凭据未加载 ​

如果你把 Claude Code 配成使用云厂商，但在 Bedrock 上看到 Could not load credentials from any providers，在 Vertex 上看到 Could not load the default credentials，或者在 Foundry 上看到 ChainedTokenCredential authentication failed，通常是当前 shell 里云厂商 CLI 没有完成认证。

Bedrock：先确认 AWS 凭据有效：

bash
aws sts get-caller-identity

Vertex AI：确认 ANTHROPIC_VERTEX_PROJECT_ID 和 CLOUD_ML_REGION 已在 shell 中设置，然后设置 application default credentials：

bash
gcloud auth application-default login

Microsoft Foundry：确认 ANTHROPIC_FOUNDRY_API_KEY 已设置，或者用 Azure CLI 登录，让默认凭据链能找到账号：

bash
az login

如果这些凭据在终端里可用，但在 VS Code 或 JetBrains 扩展里不可用，通常是 IDE 进程没有继承你的 shell 环境。把 provider 环境变量写进 IDE 自己的设置里，或者从已经导出这些变量的终端启动 IDE。

完整配置见 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry。

还是卡住 ​

如果上面都没解决问题：

  1. 去 GitHub repository 查找已知问题，或者提交新 issue，附上你的操作系统、运行的安装命令和完整报错输出
  2. 如果 claude --version 能正常工作，但别的功能不对，运行 claude doctor 获取自动诊断报告
  3. 如果你已经能打开会话，可以在 Claude Code 里运行 /feedback 报告问题

常见问题 ​

为什么安装 Claude Code 后还是提示 command not found: claude？ ​

通常是安装目录没加进 PATH，或者系统里有多个 claude 安装互相冲突。先运行 claude --version、which -a claude 或 Windows 的 where.exe claude 检查，再把 ~/.local/bin 或 %USERPROFILE%\.local\bin 加入 PATH。

为什么 curl -fsSL https://claude.ai/install.sh | bash 会返回 HTML 或 403？ ​

这通常是下载地址被网络、代理、区域限制或临时服务异常拦住了。先用 curl -sI https://downloads.claude.ai/claude-code-releases/latest 验证连通性，再按提示改用 Homebrew、WinGet，或者配置 HTTPS_PROXY 和企业 CA。

Claude Code 登录后为什么又要求重新登录？ ​

常见原因是 OAuth token 过期、系统时间不准，或者 macOS Keychain 没有正常保存凭据。可以先运行 /login 重新认证；如果是 macOS，再用 claude doctor 检查 Keychain。

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

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策