故障排查

Troubleshoot installation and login

Troubleshoot installation and login 这一页讲的，就是 Troubleshoot installation and login 这件事在 Claude Code 里到底怎么用。

页面信息

对应原页

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

这页主要讲 Troubleshoot installation and login：Fix command not found, PATH, permission, network, and authentication errors when installing or signing in to Claude Code.

你可以把它当成"Troubleshooting"这块里专门管这一摊事的说明书。

你可以把"Troubleshoot installation and login"理解成 Troubleshooting 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。

原文这页大多会按 Find your error、Run diagnostic checks、Check network connectivity、Verify your PATH 这些环节往下讲。

翻成人话，大概就是：Check network connectivity

第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。

第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。

第三，照着原文这几个环节挨个过：Find your error -> Run diagnostic checks -> Check network connectivity -> Verify your PATH。像下地先看水路、再试机器、再正式开干，一步一步最稳。

终端里敲

原页关键片段：Check network connectivity 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

原页关键片段：Check network connectivity 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

原页关键片段：Check network connectivity 3

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

关键片段

原页关键片段：Verify your PATH 1

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

关键片段

原页关键片段：Verify your PATH 2

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

关键片段

原页关键片段：Verify your PATH 3

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

终端里敲

原页关键片段：Check for conflicting installations 1

真到动手的时候了，下面这条直接敲一遍，看它回什么。

which -a claude

终端里敲

原页关键片段：Check for conflicting installations 2

真到动手的时候了，下面这条直接敲一遍，看它回什么。

ls -la ~/.local/bin/claude

终端里敲

原页关键片段：Check for conflicting installations 3

真到动手的时候了，下面这条直接敲一遍，看它回什么。

ls -la ~/.claude/local/

终端里敲

原页关键片段：Check directory permissions 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

原页关键片段：Check directory permissions 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

原页关键片段：Verify the binary works 1

看到这里，别光点头，下面这条命令先跑起来再说。

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

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

Find your error

这里不是让你背"Find your error"这个词，而是让你看它真干活时怎么使。

Run diagnostic checks

看到这里，就把"Run diagnostic checks"当成一件真要上手的活来看。

Check network connectivity

别把这段只当成标题看，它其实是在给"Check network connectivity"划边界。

终端里敲

Check network connectivity 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

Check network connectivity 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

Check network connectivity 3

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

Verify your PATH

这一段就是验收，看它到底有没有真的通。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

关键片段

Verify your PATH 1

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

关键片段

Verify your PATH 2

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

关键片段

Verify your PATH 3

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

终端里敲

Verify your PATH 4

看到这里，别光点头，下面这条命令先跑起来再说。

claude --version

Check for conflicting installations

这里不是让你背"Check for conflicting installations"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Check for conflicting installations 1

真到动手的时候了，下面这条直接敲一遍，看它回什么。

which -a claude

终端里敲

Check for conflicting installations 2

真到动手的时候了，下面这条直接敲一遍，看它回什么。

ls -la ~/.local/bin/claude

终端里敲

Check for conflicting installations 3

真到动手的时候了，下面这条直接敲一遍，看它回什么。

ls -la ~/.claude/local/

终端里敲

Check for conflicting installations 4

真到动手的时候了，下面这条直接敲一遍，看它回什么。

npm -g ls @anthropic-ai/claude-code 2>/dev/null

终端里敲

Check for conflicting installations 5

真到动手的时候了，下面这条直接敲一遍，看它回什么。

where.exe claude

终端里敲

Check for conflicting installations 6

真到动手的时候了，下面这条直接敲一遍，看它回什么。

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

Check directory permissions

别把这段只当成标题看，它其实是在给"Check directory permissions"划边界。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Check directory permissions 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

Check directory permissions 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

Verify the binary works

这里讲的是"别只装完就算了"，而是要确认它真能用、真认主、真跑通。

终端里敲

Verify the binary works 1

看到这里，别光点头，下面这条命令先跑起来再说。

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

终端里敲

Verify the binary works 2

看到这里，别光点头，下面这条命令先跑起来再说。

Get-Command claude | Select-Object Source

终端里敲

Verify the binary works 3

看到这里，别光点头，下面这条命令先跑起来再说。

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

终端里敲

Verify the binary works 4

看到这里，别光点头，下面这条命令先跑起来再说。

claude --version

Common installation issues

这段就是排错时拿来照着查的，先一项项看清楚，再动手改。

Install script returns HTML instead of a shell script

这段就是手把手操作，照顺序来最稳。

关键片段

Install script returns HTML instead of a shell script 1

先看下面这块原始片段，等会儿再回头看解释会顺得多。

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

终端里敲

Install script returns HTML instead of a shell script 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

brew install --cask claude-code

终端里敲

Install script returns HTML instead of a shell script 3

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

winget install Anthropic.ClaudeCode

command not found: claude after installation

这段看着像个标题，其实是在说"command not found: claude after installation"管到哪儿。

curl: (56) Failure writing output to destination

这里主要是在交代"curl: (56) Failure writing output to destination"这一块会碰到哪些事。

终端里敲

curl: (56) Failure writing output to destination 1

真到动手的时候了，下面这条直接敲一遍，看它回什么。

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

终端里敲

curl: (56) Failure writing output to destination 2

真到动手的时候了，下面这条直接敲一遍，看它回什么。

brew install --cask claude-code

终端里敲

curl: (56) Failure writing output to destination 3

真到动手的时候了，下面这条直接敲一遍，看它回什么。

winget install Anthropic.ClaudeCode

TLS or SSL connection errors

看到这里，就把"TLS or SSL connection errors"当成一件真要上手的活来看。

改配置

TLS or SSL connection errors 1

这一段说完，最后还得写到配置里才算真的生效。

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

终端里敲

TLS or SSL connection errors 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

关键片段

TLS or SSL connection errors 3

先看下面这块原始片段，等会儿再回头看解释会顺得多。

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

终端里敲

TLS or SSL connection errors 4

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

Failed to fetch version from downloads.claude.ai

别把这段只当成标题看，它其实是在给"Failed to fetch version from downloads.claude.ai"划边界。

终端里敲

Failed to fetch version from downloads.claude.ai 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

Failed to fetch version from downloads.claude.ai 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

Failed to fetch version from downloads.claude.ai 3

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

brew install --cask claude-code

终端里敲

Failed to fetch version from downloads.claude.ai 4

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

winget install Anthropic.ClaudeCode

Wrong install command on Windows

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

终端里敲

Wrong install command on Windows 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

Wrong install command on Windows 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

The process cannot access the file during Windows install

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

The process cannot access the file during Windows install

看到这里，别光点头，下面这条命令先跑起来再说。

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

Install killed on low-memory Linux servers

这段就是手把手操作，照顺序来最稳。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Install killed on low-memory Linux servers 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

关键片段

Install killed on low-memory Linux servers 2

先看下面这块原始片段，等会儿再回头看解释会顺得多。

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

终端里敲

Install killed on low-memory Linux servers 3

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

Install hangs in Docker

这里属于实操步骤，重点是照着顺序做，不要自己脑补省略中间步骤。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

终端里敲

Install hangs in Docker 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

关键片段

Install hangs in Docker 2

先看下面这块原始片段，等会儿再回头看解释会顺得多。

docker build --memory=4g .

Claude Desktop overrides the claude command on Windows

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

这一段主要是在把"Claude Code on Windows requires either Git for Windows (for bash) or PowerShell"讲实，不是只摆个标题给你看。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

改配置

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

这会儿轮到改配置了，字段名和关键字别自己乱换。

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

Claude Code does not support 32-bit Windows

这里不是让你背"Claude Code does not support 32-bit Windows"这个词，而是让你看它真干活时怎么使。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

改配置

Claude Code does not support 32-bit Windows

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

[Environment]::Is64BitOperatingSystem

Linux musl or glibc binary mismatch

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

终端里敲

Linux musl or glibc binary mismatch

真到动手的时候了，下面这条直接敲一遍，看它回什么。

apk add libgcc libstdc++ ripgrep

Illegal instruction

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

dyld: cannot load on macOS

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

终端里敲

dyld: cannot load on macOS 1

真到动手的时候了，下面这条直接敲一遍，看它回什么。

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

关键片段

dyld: cannot load on macOS 2

下面这块是这一段最值钱的原文样板，先对着看一眼。

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

Exec format error on WSL1

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

关键片段

Exec format error on WSL1

这一段要真抓重点，通常就抓下面这块原文。

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

npm install errors in WSL

这一段主要是在把"npm install errors in WSL"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

关键片段

npm install errors in WSL 1

这一段要真抓重点，通常就抓下面这块原文。

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

关键片段

npm install errors in WSL 2

这一段要真抓重点，通常就抓下面这块原文。

source ~/.nvm/nvm.sh

关键片段

npm install errors in WSL 3

这一段要真抓重点，通常就抓下面这块原文。

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

Permission errors during installation

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

终端里敲

Permission errors during installation

看到这里，别光点头，下面这条命令先跑起来再说。

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

Native binary not found after npm install

这一段不只是挂个标题，它是在说明"Native binary not found after npm install"这一块到底负责什么。

这一段主要是在把"Login and authentication"讲实，不是只摆个标题给你看。

Reset your login

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

OAuth error: Invalid code

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

照着做一遍

如果你不想来回翻，就先照这几步顺着做。

每做完一步就看一下结果，再决定要不要继续往下。

终端里敲

第 1 步：Check network connectivity 1

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

第 2 步：Check network connectivity 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

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

终端里敲

第 3 步：Check network connectivity 3

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

关键片段

第 4 步：Verify your PATH 1

"Verify your PATH"这一段里最要紧的原始写法在下面，先看它怎么落地。

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

一眼看懂这一页

先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。

Troubleshoot installation and login
   |
   v
这是 Troubleshooting 里的一摊要紧活
   |
   v
先弄懂，再下手

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。