# Claude Code 安装文档

## 1. 环境准备

### 1.1 检查 Node.js 和 npm 版本

在安装 Claude Code 之前，需要确保系统已安装 Node.js 18 或更高版本。

```bash

node -v

npm -v

```

**输出示例**：

```

v24.13.0

11.6.2

```

## 2. 安装 git-bash

Claude Code 在 Windows 上需要 git-bash 环境。

### 2.1 下载并安装 Git

1. 访问 Git 官网下载页面：https://git-scm.com/download/win

2. 下载适合您系统的 Git 安装包（推荐 64 位版本）

3. 运行安装程序，按照默认选项安装即可

### 2.2 验证 git-bash 安装

安装完成后，打开命令提示符或 PowerShell，运行以下命令验证：

```bash

git --version

bash --version

```

### 2.3 配置环境变量（如果 git-bash 不在 PATH 中）

如果 git-bash 命令无法直接使用，需要配置环境变量 `CLAUDE_CODE_GIT_BASH_PATH`：

1. 找到 git-bash 的安装路径，通常为：`C:\Program Files\Git\bin\bash.exe`

2. 配置环境变量：

   ```bash

   setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"

   ```

   或在系统属性中手动添加环境变量

## 3. npm 源配置

为了提高在国内网络环境下的安装速度，建议将 npm 源配置为国内镜像。

### 3.1 查看当前 npm 源

```bash

npm config list

```

### 3.2 设置为国内源

```bash

npm config set registry https://registry.npmmirror.com

```

### 3.3 验证源设置

```bash

npm config list

```

**预期输出**：

```

registry = "https://registry.npmmirror.com"

```

## 4. Claude Code 安装

### 4.1 全局安装 Claude Code

使用以下命令全局安装 Claude Code：

```bash

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

```

**注意**：

- 正确的包名是 `@anthropic-ai/claude-code`，而非 `claudecode`

- 如果安装速度较慢，可以在命令末尾添加 `--registry=https://registry.npmmirror.com` 强制使用国内源

### 4.2 验证安装结果

```bash

claude --version

```

**预期输出**：

```

2.1.19 (Claude Code)

```

## 5. 配置连接代理

### 5.1 问题分析

在中国大陆运行 Claude Code 时，可能会遇到以下连接错误：

```

Unable to connect to Anthropic services

Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

```

这是因为中国大陆不在 Anthropic 服务支持范围内。

### 5.2 解决方案

使用代理服务连接 Anthropic API。需要准备以下信息：

1. 有效的 API 令牌（由管理员提供）

2. 代理服务地址（由管理员提供）

### 5.3 创建启动脚本

为了确保每次运行 Claude Code 时都能正确加载环境变量，建议创建一个启动脚本：

#### PowerShell 脚本（适合开发者）

创建 `claude-start.ps1` 文件：

```powershell

# Claude Code 启动脚本

# 设置环境变量（请从管理员处获取正确的值）

$env:ANTHROPIC_AUTH_TOKEN = "[请从管理员处获取API令牌]"

$env:ANTHROPIC_BASE_URL = "[请从管理员处获取代理服务地址]"

Write-Host "正在启动 Claude Code..."

Write-Host "使用代理服务：$env:ANTHROPIC_BASE_URL"

Write-Host ""

if ($args.Count -gt 0) {

    claude @args

} else {

    claude

}

```

#### 批处理脚本（适合普通用户）

创建 `claude-start.bat` 文件：

```batch

@echo off

echo 正在启动 Claude Code...

echo 设置代理服务环境变量...

echo 设置 ANTHROPIC_AUTH_TOKEN...

set ANTHROPIC_AUTH_TOKEN=[请从管理员处获取API令牌]

echo 设置 ANTHROPIC_BASE_URL...

set ANTHROPIC_BASE_URL=[请从管理员处获取代理服务地址]

echo.

echo 使用代理服务: %ANTHROPIC_BASE_URL%

echo.

echo 正在启动 Claude Code...

echo.

claude

```

## 6. 常用命令

### 6.1 基本命令

| 命令 | 描述 |

|------|------|

| `claude --version` | 查看 Claude Code 版本 |

| `claude` | 启动 Claude Code 交互式会话 |

| `claude mcp list` | 查看已配置的 MCP 服务器 |

| `claude mcp add <name> <command>` | 添加新的 MCP 服务器 |

| `claude mcp remove <name>` | 移除 MCP 服务器 |

### 6.2 API 模式命令

| 命令 | 描述 |

|------|------|

| `claude --print "你的提示"` | 使用 API 模式获取非交互式输出 |

| `claude -p --model sonnet "编写一个 Hello World 程序"` | 指定模型并使用 API 模式 |

| `claude --print --json-schema <schema> "你的提示"` | 获取结构化 JSON 输出 |

## 7. 故障排除

### 7.1 安装时出现 404 错误

- 确认使用的是正确的包名 `@anthropic-ai/claude-code`

- 检查 npm 源是否配置正确

### 7.2 安装速度慢

- 确保已配置国内 npm 源

- 安装命令中添加 `--registry=https://registry.npmmirror.com`

### 7.3 命令无法识别

- 确认 Node.js 和 npm 已正确安装

- 确认 Claude Code 已成功安装

- 检查系统 PATH 环境变量是否包含 npm 全局安装目录

### 7.4 无法连接到 Anthropic 服务

**错误信息**：

```

Unable to connect to Anthropic services

Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

```

**解决方案**：

- 确保已正确配置代理服务环境变量

- 联系管理员获取有效的 API 令牌和代理服务地址

- 检查网络连接和防火墙设置

## 8. 后续使用建议

1. 定期更新 Claude Code：

   ```bash

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

   ```

2. 查看官方文档获取更多功能信息

3. 根据实际需求配置 MCP 服务器

## 9. 环境信息

- 操作系统：Windows

- Node.js 版本：v24.13.0

- npm 版本：11.6.2

- Claude Code 版本：2.1.19

- 安装日期：2026-01-26