安装错误合集

Claude Code / Codex CLI / 各种客户端安装阶段踩坑大全。

程序 "claude.exe" 无法运行（Windows）

症状：

程序"claude.exe"无法运行
找不到 npm 或路径错误

或：

'claude' is not recognized as an internal or external command

根因：npm 老安装残留 / PATH 冲突 / 缺依赖。

解决（按顺序做完，别跳步）：

步骤 1：清理旧环境

# 1. 卸载 npm 全局安装
npm uninstall -g @anthropic-ai/claude-code

# 2. 删除残留文件（很关键）
Remove-Item -Recurse -Force "$env:APPDATA\npm\claude*" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\AnthropicClaude" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude" -ErrorAction SilentlyContinue

# 3. 确认清干净
where.exe claude  # 应输出 "INFO: 没有找到匹配的文件"

步骤 2：装 Git for Windows（必要依赖！）

https://git-scm.com/download/win

下载安装包 → 一路 Next 默认即可。安装完确认：

git --version
# 应输出: git version 2.x.x

步骤 3：用 WinGet 重装 Claude Code（推荐）

winget install Anthropic.ClaudeCode

或官方脚本：

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

步骤 4：验证

# 关掉 PowerShell 重新打开
claude --version
# 应输出: 2.1.x (Claude Code)

npm -v 报错

症状：

npm : The term 'npm' is not recognized as the name of a cmdlet

根因：Node.js 没装或 PATH 没生效。

解决：

Windows

1. 去 nodejs.org 下 LTS 版本
2. 安装时勾选 "Add to PATH"
3. 关掉 PowerShell 重开
4. node -v 和 npm -v 都应有输出

macOS

# Homebrew 装
brew install node

# 或官方 .pkg
# https://nodejs.org

Linux

# Debian/Ubuntu - 注意系统自带的 nodejs 12 太老
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 验证
node -v   # 应为 v20.x 或更高
npm -v

claude --version 报错（PowerShell 执行策略）

症状：

claude.ps1 cannot be loaded because running scripts is disabled on this system.

根因：Windows PowerShell 默认禁止运行未签名脚本。

解决：

# 以管理员身份打开 PowerShell（重要！）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 然后重试
claude --version

别用 Unrestricted

有教程让你用 Set-ExecutionPolicy Unrestricted。不安全，会让任何脚本都能跑。用 RemoteSigned 已足够（本地脚本可跑，远程脚本必须签名）。

command not found: claude（macOS / Linux）

症状：

$ claude
zsh: command not found: claude
# 或
fish: claude: command not found

根因：claude 装到了 ~/.local/bin/、~/.npm-global/bin/ 等，但 PATH 没加。

解决：

zsh / bash

# 找 claude 实际位置
find ~ -name claude -type f -o -name claude -type l 2>/dev/null

# 加进 PATH（最常见两个位置）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
exec $SHELL

fish

# fish_add_path 一键
fish_add_path ~/.local/bin
fish_add_path ~/.npm-global/bin

# 验证
echo $fish_user_paths

npm 全局装报权限错误（EACCES）

症状：

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@anthropic-ai
npm error errno -13

根因：npm 默认 prefix 是 /usr/local，普通用户没写权限。

解决（不要用 sudo！）：

# 改 npm prefix 到用户目录
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# 加 PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
exec $SHELL

# 重装
npm install -g @anthropic-ai/claude-code

install.sh 显示 ✅ 但实际没装上

详细见 安装下载失败。

curl install.sh | bash 看似成功但实际没装上，几乎一定是这个问题 —— 改用 npm 安装路线绕过。

Node.js 版本太低

症状：

SyntaxError: Unexpected token '?'
# 或
Error: Node.js version 12.x.x is not supported. Requires >= 18.

根因：Node.js 版本 < 18。

解决：升级到 Node 20 LTS（见上面 npm -v 报错的 Linux 部分）。

Bun / Yarn 装不了

Claude Code 用 npm/pnpm 兼容生态。不建议用 Bun / Yarn 装，会有些边角不兼容。

如果坚持用：

# pnpm（推荐）
npm install -g pnpm
pnpm install -g @anthropic-ai/claude-code

# yarn（可能有警告）
yarn global add @anthropic-ai/claude-code

Codex CLI: Codex could not find bubblewrap（Linux）

症状：

warning: Codex could not find bubblewrap on PATH.
Codex will use the bundled bubblewrap in the meantime.

根因：Linux 沙盒工具 bubblewrap 没装。Codex 自带 fallback 版本，不影响功能。

解决（可选）：

sudo apt install bubblewrap     # Debian/Ubuntu
sudo dnf install bubblewrap     # Fedora
sudo pacman -S bubblewrap       # Arch

升级现有安装

Windows

winget upgrade Anthropic.ClaudeCode
# 或
npm update -g @anthropic-ai/claude-code

macOS / Linux

# 如果用 install.sh 装的
curl -fsSL https://claude.ai/install.sh | bash

# 如果用 npm 装的
npm update -g @anthropic-ai/claude-code

验证升级

claude --version
# 看版本号是否更新

还不行？

• 区域屏蔽
• retry 死循环
• FAQ