---
title: "Claude 命令行工具安装完整指南"
description: "从官方原生安装脚本讲起，同时保留 npm 安装这条路，覆盖 macOS、Linux 与 Windows（含 WSL 2）的准备步骤，再逐一处理权限、PATH、网络超时和 Node 版本四类报错，最后给出升级与卸载方法。"
updated: 2026-11-13
canonical: https://docai.cc/learn/cli-tool-installation-guide/
markdown_mirror: https://docai.cc/learn/cli-tool-installation-guide.md
---
## 一条命令，一次验证

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

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

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

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

```bash
claude --version
```

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

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

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

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

```bash
npm config get prefix
```

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

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

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

```bash
# 安装 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 里执行：

```powershell
wsl --install
```

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

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

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

## 四类报错，对症处理

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

```bash
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 配置，重启终端。

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

```bash
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 版本不满足。按类别找上面的解法，比从头重装快得多。

## 升级与卸载

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

```bash
claude update
```

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

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

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

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

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

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

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

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

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

## 装完先做这三步

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

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

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

下一步是账户与凭据：[账户与 API Key 配置](/learn/account-and-api-key-setup/)。