Claude 命令行工具安装完整指南

从官方原生安装脚本讲起，同时保留 npm 安装这条路，覆盖 macOS、Linux 与 Windows（含 WSL 2）的准备步骤，再逐一处理权限、PATH、网络超时和 Node 版本四类报错，最后给出升级与卸载方法。

一条命令，一次验证

前提只有一条：网络能连上。Claude Code 官方推荐的是原生安装脚本，不依赖 Node：

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

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

装完打开一个新终端再验证：

claude --version

能打印出版本号，命令就可用；再跑一次 claude --help，看看子命令是否齐全。报错的话，先别急着重装，多数问题在下面的四类里。

已经有一套 Node 工具链、或者需要在流水线里固定版本，也可以走 npm。npm 包当前要求 Node.js 22 及以上：

npm install -g @anthropic-ai/claude-code

-g 表示装到全局，所有项目共用一份。装之前先看一眼它会落到哪：

npm config get prefix

这个目录下的 bin 必须在 PATH 里，命令才找得到。用系统自带 Node 时，该目录往往需要更高权限才能写入，这正是后面权限报错的来源。

macOS 与 Linux：npm 安装先把 Node 理顺

原生安装脚本一行就结束，不需要这一节。走 npm 安装时，这两个平台步骤几乎一样，差别只在 Shell 的配置文件。用版本管理器装 Node 最省事：

# 安装 nvm（已装可跳过）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash

# 让当前终端读到 nvm
source ~/.zshrc      # macOS 或 zsh
source ~/.bashrc     # Linux 或 bash

# 装 LTS 版本并设为默认
nvm install --lts
nvm use --lts
nvm alias default node

然后执行全局安装，再验证一次。macOS 上如果缺少 git 等基础命令行工具，可以先跑 xcode-select --install 补齐。已经用 Homebrew 的人，也可以用 brew install nvm，但之后仍要把 nvm 的初始化语句写进 Shell 配置，否则新开终端会找不到它。

CentOS 一类的系统，把 source ~/.bashrc 换成 source ~/.bash_profile 即可，其余不变。改完配置记得重开终端，或者手动 source 一次；很多「明明装了却没生效」的情况，都是当前窗口还在用旧环境。

Windows：原生能装，WSL 2 更接近 Linux

原生 PowerShell 用上面的 irm 命令就能装好，不需要管理员权限；装了 Git for Windows 时，它执行 shell 命令会走 Git Bash。如果项目依赖 Linux 工具链，或者想要沙箱隔离，再上 WSL 2。

在管理员权限的 PowerShell 里执行：

wsl --install

重启后系统会准备好 Ubuntu。进入 WSL 终端，用 Linux 的原生安装脚本；也可以按上面的 npm 步骤，先装 nvm、Node，再执行 npm 命令。

日常使用时，用 Windows Terminal 的下拉菜单选 Ubuntu 标签，或者直接 wsl 进入。先跑 wsl -l -v 确认发行版和版本号，看到 2 才说明装对了。

项目文件放在 WSL 自己的文件系统里，读写性能比跨盘访问好，也能避免路径换行符和权限映射带来的小毛病。代码留在 Windows 盘上也能用，只是大批量文件操作会明显变慢。

四类报错，对症处理

权限不足（EACCES）：全局目录不可写。改一个归当前用户所有的目录，比提权干净：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

用 nvm 管的 Node 自带可写权限，是更彻底的解法。

命令找不到：包装上了，PATH 没跟上。npm config get prefix 查到目录，把其中的 bin 加进 Shell 配置，重启终端。

下载超时：换镜像而不是反复重试：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

只想临时用一次，就在命令后面加这个参数；想长期生效，改成 npm config set registry 写进配置。

Node 版本过低：按提示里的最低版本要求，切一个更高的 LTS 再重新安装。npm 在版本不够时往往只给警告而不中断，但既然包已经写明了要求，就别带着警告往下走。

排查时先读报错的第一行，它通常直接点名类别：EACCES 是权限，ETIMEDOUT 是网络，EBADENGINE（Unsupported engine）是 Node 版本不满足。按类别找上面的解法，比从头重装快得多。

升级与卸载

升级有两条路。工具自带更新命令，最省事：

claude update

npm 安装的也可以让 npm 重新拉取最新版，效果等价：

npm install -g @anthropic-ai/claude-code@latest

更新后同样用 claude --version 确认。

如果某台机器要保持稳定，别每次都追最新版，固定一个验证过的版本号再装。升级前看一眼发布说明，遇到行为变化也方便回退。

不再需要时，原生安装删两个目录即可：

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

npm 装的反向操作是一条命令：

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

如果之前手动改过全局目录，记得顺手清理残留的配置文件和缓存。

装完先做这三步

claude --version，确认命令可用；
claude --help，确认子命令完整；
进入任意项目运行 claude，完成登录，问一句只读的问题，比如「这个项目的入口文件在哪」。

三步都通过，安装才算真正结束。第三步尤其重要：只有真的问过一句、拿到正确回答，才能确认登录、网络和文件读取三条链路都是通的。

版本与参数会随发布调整，遇到与本文不一致的地方，以 claude --help 和官方文档当前说明为准。

下一步是账户与凭据：账户与 API Key 配置。