---
url: /ai/aym5dtfp/index.md
description: Claude Code 安装指南，包括 Node.js 环境配置、包管理器安装方法及常见问题解决。
---
# 安装 Claude Code

记录一下 Claude Code 的安装方法，方便以后翻。

## 前置要求

安装前先确保满足这些条件：

* Node.js 18+（推荐 24）
* 包管理器：npm、pnpm 或 yarn
* 一个 Anthropic 账号（需要注册并获取 API key）

::: tip 为什么用 Claude Code？
在终端里直接用 Claude 帮你写代码、改 bug、执行命令，不用切换到浏览器。跟 AI 配合开发效率提升明显。
:::

### 安装 Node.js

::: tabs#os

@tab ::mdi:apple:: macOS

推荐使用 Homebrew 或 nvm 安装：

```bash
# 使用 Homebrew
brew install node

# 或使用 nvm（推荐，方便切换版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 24
nvm use 24
```

@tab ::mdi:microsoft-windows:: Windows

**1. 修改 PowerShell 执行策略（必须）**

Windows 默认禁止运行脚本，需要先修改执行策略，否则 npm 等命令无法运行：

```powershell
# 以管理员身份运行 PowerShell，执行以下命令
Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned
```

> 参数说明：
>
> * `-Scope LocalMachine`：对整个系统生效
> * `-ExecutionPolicy RemoteSigned`：允许运行本地脚本和已签名的远程脚本
>
> **优点**：设置后无需再次更改，方便后续使用。
>
> **缺点**：可能会带来一定的安全风险，因为允许运行本地脚本。

**2. 安装 Git（必须）**

Claude Code 依赖 Git，请先安装：

```powershell
# 使用 winget
winget install Git.Git

# 或使用 Chocolatey
choco install git
```

> ⚠️ 务必在安装 Claude Code 之前先安装 Git，否则可能导致路径识别等问题。

**3. 配置 Git（推荐）**

安装完成后，建议进行以下配置：

**设置用户名和邮箱**（全局配置，适用于本机所有 Git 仓库）：

```powershell
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"
```

**配置网络代理**：

```powershell
# 注意修改成自己的 IP 和端口号
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
```

**4. 安装 Node.js**

推荐使用以下方式之一：

```powershell
# 方式一：使用 winget
winget install OpenJS.NodeJS.LTS

# 方式二：使用 Chocolatey
choco install nodejs-lts

# 方式三：使用 nvm-windows（推荐）
# 先从 https://github.com/coreybutler/nvm-windows/releases 下载安装
nvm install 24
nvm use 24
```

:::

## 安装方法

### 方法一：全局安装（推荐）

直接安装到系统全局，任何项目都能用。

::: npm-to tabs="npm,pnpm"

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

:::

装完之后，在任意目录运行：

```bash
claude
```

第一次运行会提示你登录，按指引操作就行。

::: info 登录时会发生什么？
会弹出一个浏览器窗口，让你登录 Anthropic 账号并授权。授权成功后，终端就可以用了。
:::

### 方法二：临时使用

不想全局安装的话，可以直接运行：

::: npm-to tabs="npm,pnpm"

```sh
npx @anthropic-ai/claude-code
```

:::

适合偶尔用一下的情况。

### 方法三：项目本地安装

只想在某个项目里用：

::: npm-to tabs="npm,pnpm"

```sh
npm install -D @anthropic-ai/claude-code
```

:::

然后在项目里运行：

::: npm-to tabs="npm,pnpm"

```sh
npx claude
```

:::

## 配置 API Key

Claude Code 需要配置 API 才能使用。推荐使用 **CC-Switch** 工具来管理配置。

### 方法一：使用 CC-Switch（推荐）

[CC-Switch](https://github.com/SaladDay/cc-switch) 是一个跨平台桌面应用，用于管理和快速切换 AI 编程 CLI 工具的 API 配置，支持 Claude Code、Codex、Gemini CLI 等。

**主要功能：**

* 一键切换不同的 API 提供商/配置
* 多提供商管理（官方 Anthropic、MiniMax、自定义网关等）
* MCP 服务器配置统一管理
* API 连接速度测试
* 配置导入/导出和云同步

**安装方式：**

::: tabs#os

@tab ::mdi:apple:: macOS

```bash
# 使用 Homebrew 安装
brew install SaladDay/tap/cc-switch

# 或从 GitHub Releases 下载
# https://github.com/SaladDay/cc-switch/releases
```

@tab ::mdi:microsoft-windows:: Windows

```powershell
# 使用 winget 安装
winget install SaladDay.CC-Switch

# 或从 GitHub Releases 下载 .exe 安装包
# https://github.com/SaladDay/cc-switch/releases
```

:::

**使用步骤：**

1. 打开 CC-Switch
2. 添加 Provider（填写 API Key 和 Base URL）
3. 点击切换到目标 Provider
4. 打开 Claude Code 验证配置已生效

::: tip 为什么推荐 CC-Switch？

* **多配置管理**：轻松管理多个 API Key 和网关
* **一键切换**：无需手动修改环境变量或配置文件
* **云同步**：支持坚果云同步，多设备配置共享
* **速度测试**：直观显示 API 连接质量
  :::

### 方法二：手动配置

如果不想使用工具，也可以手动配置 API Key。

**获取 API Key：**

1. 去 [Anthropic Console](https://console.anthropic.com/)
2. 登录账号
3. 进入 API Keys 页面
4. 创建一个新的 API Key

**设置环境变量：**

::: tabs#os

@tab ::mdi:apple:: macOS

添加到 shell 配置文件（根据你使用的 shell 选择）：

```bash
# Zsh（macOS 默认）- 添加到 ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.zshrc
source ~/.zshrc

# Bash - 添加到 ~/.bash_profile
echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.bash_profile
source ~/.bash_profile
```

@tab ::mdi:microsoft-windows:: Windows

使用 PowerShell 或命令提示符：

```powershell
# 方式一：使用 setx（永久设置，需要重启终端生效）
setx ANTHROPIC_API_KEY "your_api_key_here"

# 方式二：仅当前会话有效
$env:ANTHROPIC_API_KEY="your_api_key_here"
```

或通过系统设置界面配置：

1. 右键「此电脑」→「属性」→「高级系统设置」
2. 点击「环境变量」
3. 在「用户变量」中新建，变量名 `ANTHROPIC_API_KEY`

:::

::: warning 注意
API Key 要保密，别提交到 Git 仓库。记得把 `.claude` 目录加到 `.gitignore`。
:::

## 常用命令

```bash
# 启动 Claude Code
claude

# 查看版本
claude --version

# 查看帮助
claude --help
```

## 基本使用

启动后，直接在终端里跟 Claude 对话就行：

```
你: 帮我写一个快速排序
Claude: 好的，这是快速排序的实现...
```

Claude Code 可以帮你：

* 写代码和改代码
* 执行终端命令
* 读写文件
* 搜索代码
* 调试问题

## 升级

定期升级到最新版本：

::: npm-to tabs="npm,pnpm"

```sh
npm update -g @anthropic-ai/claude-code
```

:::

## 常见问题

### 安装失败

检查 Node.js 版本：

```bash
node --version
```

确保是 18+（推荐 24）。版本不对的话，升级 Node.js：

::: tabs#os

@tab ::mdi:apple:: macOS

```bash
# 使用 nvm
nvm install 24
nvm use 24

# 或使用 Homebrew
brew upgrade node
```

@tab ::mdi:microsoft-windows:: Windows

```powershell
# 使用 nvm-windows
nvm install 24
nvm use 24

# 或使用 winget
winget upgrade OpenJS.NodeJS.LTS
```

:::

### API Key 无效

确认 API Key 是否正确设置：

::: tabs#os

@tab ::mdi:apple:: macOS

```bash
echo $ANTHROPIC_API_KEY
```

@tab ::mdi:microsoft-windows:: Windows

```powershell
# PowerShell
$env:ANTHROPIC_API_KEY

# CMD
echo %ANTHROPIC_API_KEY%
```

:::

### 权限问题

::: tabs#os

@tab ::mdi:apple:: macOS

如果安装时遇到权限问题（EACCES），推荐修复 npm 权限而不是使用 sudo：

```bash
# 方式一：修改 npm 默认目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到 PATH（根据你的 shell 选择）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
```

或使用 pnpm 避免权限问题：

```bash
npm install -g pnpm
pnpm setup
```

@tab ::mdi:microsoft-windows:: Windows

Windows 上通常不会遇到权限问题。如果遇到，尝试：

1. 以管理员身份运行终端
2. 检查 npm 全局目录权限：

```powershell
# 查看全局安装路径
npm config get prefix

# 如果路径在 Program Files 下，修改到用户目录
npm config set prefix "$env:APPDATA\npm"
```

:::

## 卸载

不再需要的话，可以卸载：

::: npm-to tabs="npm,pnpm"

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

:::

::: info
配置文件和缓存数据会保留在 `~/.claude` 目录，如果需要彻底清理可以手动删除这个目录。
:::

***