# Claude Code 安装教程完整指南：Windows/Mac/Linux 全平台详解（2026年1月）

> Claude Code 是 Anthropic 推出的终端 AI 编程助手。本文提供 Windows、macOS、Linux 三个平台的完整安装教程，包括原生安装、WSL 配置、认证方式详解和常见问题解决。

- Source: https://www.aifreeapi.com/zh/posts/claude-code-installation-guide
- Language: zh
- Published: 2026-01-19
- Updated: 2026-01-19
- Publisher: AI Free API (https://www.aifreeapi.com)

Claude Code 是 Anthropic 推出的终端 AI 编程助手，它可以理解你的代码库、执行常规任务、解释复杂代码，并通过自然语言命令处理 git 工作流。2026 年 1 月的最新推荐安装方式是原生安装，macOS 和 Linux 用户只需执行 `curl -fsSL https://claude.ai/install.sh | bash`，Windows 用户使用 `irm https://claude.ai/install.ps1 | iex`。这种方式无需预先安装 Node.js，安装完成后会自动保持更新。本文将详细介绍三个平台的完整安装流程，包括系统要求、安装方式选择、认证配置和常见问题解决。

## Claude Code 简介与系统要求

Claude Code 与传统的代码补全工具不同，它是一个完整的 AI 编程助手，能够理解整个代码库的上下文。根据 Anthropic 官方文档（https://code.claude.com/docs/en/setup），它支持代码生成、调试、git 操作、测试和重构等多种功能。如果你想了解它与其他编程工具的区别，可以参考 [Cursor 与 Claude Code 详细对比](/zh/posts/claude-code-vs-cursor)。

![Claude Code 安装方式对比](https://www.aifreeapi.com/posts/zh/claude-code-installation-guide/img/comparison.png)

**系统要求**是安装前必须确认的关键信息。根据官方文档，Claude Code 支持以下操作系统：macOS 10.15 或更高版本（Catalina 及以上）、Ubuntu 20.04+ 或 Debian 10+ 的 Linux 发行版、以及 Windows 10 或更高版本。需要特别注意的是，Windows 用户必须通过 WSL（Windows Subsystem for Linux）1 或 2、或者 Git for Windows 来运行 Claude Code，它无法在原生的 Windows Command Prompt 或 PowerShell 中直接运行。

**硬件要求**相对简单：4GB 以上 RAM 和稳定的互联网连接。如果你选择 npm 安装方式（已废弃，不推荐），还需要 Node.js 18 或更高版本。软件方面，Claude Code 在 Bash、Zsh 或 Fish shell 中效果最佳。此外，你需要在 Anthropic 支持的国家/地区使用。

| 平台 | 最低版本 | 特殊要求 |
|------|---------|---------|
| macOS | 10.15 (Catalina) | 无 |
| Windows | 10 | WSL 1/2 或 Git Bash |
| Linux | Ubuntu 20.04 / Debian 10 | 无 |
| RAM | 4GB+ | - |
| Node.js | 18+（仅 npm 安装需要） | - |

## 安装方式选择指南

2026 年 1 月，Claude Code 提供四种安装方式：原生安装（推荐）、Homebrew、WinGet 和 npm（已废弃）。选择正确的安装方式可以避免很多问题。

**原生安装是官方首选推荐的方式**，它有三个显著优势。首先是无需 Node.js，安装脚本会自动下载预编译的二进制文件到 `~/.local/bin/claude`。其次是自动更新，原生安装会在后台静默下载和安装更新，你会在更新完成后看到通知，下次启动 Claude Code 时生效。第三是全平台支持，无论是 macOS、Linux 还是 Windows（通过 PowerShell），都可以使用统一的安装命令。

**Homebrew 安装适合已经在使用 Homebrew 的 Mac 开发者**。命令简单：`brew install --cask claude-code`。但需要注意的是，Homebrew 安装不会自动更新，你需要定期运行 `brew upgrade claude-code` 来获取最新版本。

**WinGet 安装是 Windows 用户的另一个选择**，命令是 `winget install Anthropic.ClaudeCode`。同样，WinGet 安装也不会自动更新，需要手动运行 `winget upgrade Anthropic.ClaudeCode`。

**npm 安装已被标记为废弃（deprecated）**，强烈不建议新用户使用。如果你之前通过 npm 安装过 Claude Code，建议迁移到原生安装：运行 `claude install` 命令即可自动迁移。

| 对比维度 | 原生安装 | Homebrew | WinGet | npm |
|---------|---------|----------|--------|-----|
| 需要 Node.js | 否 | 否 | 否 | 是 (18+) |
| 自动更新 | 是 | 否 | 否 | 否 |
| 支持平台 | 全平台 | macOS/Linux | 仅 Windows | 全平台 |
| 推荐程度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ (废弃) |

**选择建议**：如果你是新用户，直接选择原生安装。如果你是 Mac 用户且已有 Homebrew 环境，可以选择 Homebrew。如果你是 Windows 用户且偏好包管理器，可以选择 WinGet。无论如何，避免使用 npm 安装。

## macOS 安装完整指南

macOS 是 Claude Code 支持最好的平台之一，安装过程非常简单。整个过程通常只需要 3-5 分钟。

**原生安装（推荐）**只需要一行命令。打开终端（Terminal.app 或 iTerm2），执行以下命令：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

这个命令会自动下载 Claude Code 的二进制文件，安装到 `~/.local/bin/claude`，并配置 PATH 环境变量。安装完成后，你可能需要重新打开终端才能使用 `claude` 命令。

**如果你想安装特定版本**，可以使用以下命令：

```bash
# 安装最新版本（包括预发布版）
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 安装特定版本号
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
```

**Homebrew 安装**同样简单：

```bash
brew install --cask claude-code
```

安装完成后，使用以下命令验证：

```bash
# 检查版本
claude --version

# 运行诊断
claude doctor
```

如果 `claude doctor` 显示 "Installation: native" 或 "Installation: homebrew"，说明安装成功。

**常见问题：PATH 未配置**

如果运行 `claude` 命令时提示 "command not found"，说明 PATH 环境变量没有正确配置。对于 Zsh 用户（macOS 默认），执行：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

对于 Bash 用户，将 `.zshrc` 替换为 `.bashrc` 或 `.bash_profile`。

## Windows 安装完整指南

Windows 是三个平台中安装最复杂的，因为 Claude Code 无法在原生 Windows 环境中直接运行。根据官方文档，你有三个选择：WSL、Git Bash 或原生 PowerShell 安装。

![Claude Code 安装流程](https://www.aifreeapi.com/posts/zh/claude-code-installation-guide/img/process.png)

**方案一：使用原生 PowerShell 安装（最简单）**

2026 年的最新版本支持直接在 PowerShell 中安装，这是最简单的方式。以管理员身份打开 PowerShell，执行：

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

如果你想安装特定版本：

```powershell
# 安装最新版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# 安装特定版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
```

安装完成后，你可以在 PowerShell、Windows Terminal 或 Git Bash 中使用 Claude Code。

**方案二：使用 WSL（推荐给需要 Linux 环境的开发者）**

如果你还没有安装 WSL，以管理员身份运行 PowerShell，执行：

```powershell
wsl --install -d Ubuntu
```

安装完成后重启电脑，然后打开 Ubuntu 终端。如果你安装了多个 WSL 发行版（如 Docker Desktop），确保 Ubuntu 是默认发行版：

```powershell
wsl --set-default Ubuntu
```

在 Ubuntu 终端中，使用标准的 Linux 安装命令：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**方案三：使用 Git Bash**

如果你已经安装了 Git for Windows，可以直接在 Git Bash 中运行安装命令。如果你使用的是便携版 Git，需要设置环境变量指定 bash.exe 的路径：

```powershell
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
```

**方案四：使用 WinGet**

如果你偏好 Windows 的包管理器，可以使用：

```cmd
winget install Anthropic.ClaudeCode
```

**验证安装**：

无论使用哪种方式，安装完成后都应该运行：

```bash
claude --version
claude doctor
```

**常见问题：WSL 相关**

如果你在 WSL 中安装失败，常见原因包括：

1. WSL 版本过旧：运行 `wsl --update` 更新
2. 默认发行版不是 Ubuntu：运行 `wsl --set-default Ubuntu`
3. Windows 和 WSL 的 Node.js 冲突：在 WSL 中运行 `which node`，确保指向 `/usr/` 开头的路径

## Linux 安装完整指南

Linux 用户的安装过程与 macOS 类似，但可能需要处理一些权限问题。

**原生安装（推荐）**：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**对于 Alpine Linux 和其他 musl/uClibc 基础发行版**，需要额外安装依赖：

```bash
apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0
```

**npm 安装**（如果你必须使用）：

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

⚠️ 重要提示：**不要使用 `sudo npm install -g`**，这会导致权限问题和安全风险。

如果你遇到权限错误，正确的做法是配置 npm 的全局目录：

```bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

**验证安装**：

```bash
claude --version
claude doctor
```

**常见问题：命令找不到**

如果第二天打开终端发现 `claude` 命令找不到了，这通常是 PATH 配置问题。确保 `~/.local/bin` 在你的 PATH 中：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

如果问题仍然存在，尝试删除配置重新安装：

```bash
rm -rf ~/.claude
curl -fsSL https://claude.ai/install.sh | bash
```

## 认证与激活详解

安装完成后，你需要完成认证才能使用 Claude Code。有三种认证方式可选，选择取决于你的使用场景和账户类型。

**方式一：Claude Console（默认，按量付费）**

这是最常见的认证方式。首次运行 `claude` 命令时，会自动打开浏览器进行 OAuth 登录。你需要有一个 Anthropic Console 账户（https://console.anthropic.com）并开通账单。登录后，系统会自动创建一个 "Claude Code" 工作区用于使用情况跟踪和成本管理。

```bash
cd your-project
claude
# 浏览器会自动打开，完成 OAuth 登录
```

**方式二：Claude Pro/Max 订阅（统一订阅）**

如果你已经订阅了 Claude 的 Pro（$20/月）或 Max（$100/月）计划，可以使用同一个账户登录。这种方式的好处是统一管理订阅，同时包含 Claude Code 和网页版 Claude。

**方式三：企业平台（Amazon Bedrock / Google Vertex AI）**

企业用户可以配置 Claude Code 使用现有的云基础设施。这需要额外的配置，具体请参考官方文档。

| 认证方式 | 适用人群 | 计费方式 | 特点 |
|---------|---------|---------|------|
| Claude Console | 个人开发者 | 按量付费 | 灵活，用多少付多少 |
| Claude Pro/Max | 重度用户 | 订阅制 | 统一管理，含网页版 |
| 企业平台 | 企业用户 | 云平台计费 | 集成现有基础设施 |

对于需要使用 API 方式认证的开发者，laozhang.ai 提供的 API 中转服务价格与官方一致，支持多模型切换，可以作为一个灵活的选择。如果你在认证过程中遇到 OAuth 错误，可以参考 [Claude Code OAuth 认证错误解决方案](/zh/posts/claude-code-oauth-error)。

## 常见问题与故障排查

Claude Code 的安装过程中可能遇到各种问题。以下是最常见的问题和解决方案。

**`claude doctor` 是你的好帮手**。当遇到问题时，首先运行这个命令，它会提供有关安装类型、版本和潜在问题的诊断信息。

**问题 1：command not found**

这是最常见的问题，通常是 PATH 配置问题。解决方法：

```bash
# 1. 检查 claude 是否真的安装了
ls ~/.local/bin/claude

# 2. 如果存在，添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # 或 ~/.bashrc
source ~/.zshrc

# 3. 如果不存在，重新安装
curl -fsSL https://claude.ai/install.sh | bash
```

**问题 2：Windows 安装失败**

常见原因和解决方案：

| 症状 | 原因 | 解决方案 |
|------|------|---------|
| WSL 相关错误 | WSL 未正确安装 | 运行 `wsl --install -d Ubuntu` |
| Docker 相关错误 | Docker 设为默认 WSL | 运行 `wsl --set-default Ubuntu` |
| 权限错误 | 未以管理员运行 | 以管理员身份运行 PowerShell |

**问题 3：Node.js 版本问题（npm 安装）**

如果你使用 npm 安装并遇到版本错误：

```bash
# 检查版本
node -v  # 需要 18+，建议 20+

# 更新 Node.js（使用 nvm）
nvm install 20
nvm use 20
```

**问题 4：认证失败**

如果 OAuth 登录后仍然无法使用：

1. 确认你的 Anthropic Console 账户已开通账单
2. 检查网络连接（需要访问 claude.ai）
3. 尝试删除配置后重新认证：

```bash
rm -rf ~/.claude
rm ~/.claude.json
claude  # 重新触发认证流程
```

**问题 5：更新后出现问题**

如果更新后 Claude Code 无法正常工作：

```bash
# 原生安装：重新安装
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew：重新安装
brew uninstall --cask claude-code
brew install --cask claude-code
```

**问题 6：VS Code 扩展安装失败**

如果自动安装 VS Code 扩展失败，通常是因为 `code` 命令未添加到 PATH。在 VS Code 中按 `Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），搜索并运行 "Shell Command: Install 'code' command in PATH"。

## 总结与最佳实践

本文详细介绍了 Claude Code 在 Windows、macOS 和 Linux 三个平台上的完整安装流程。

**核心要点回顾**：

首先，原生安装是 2026 年官方推荐的方式，它无需 Node.js、支持自动更新、并且在所有平台上都可用。macOS 和 Linux 用户使用 `curl -fsSL https://claude.ai/install.sh | bash`，Windows 用户使用 `irm https://claude.ai/install.ps1 | iex`。

其次，Windows 用户需要特别注意，Claude Code 需要 WSL 或 Git Bash 环境才能完整运行，虽然 PowerShell 安装脚本可以直接使用。

第三，认证方式选择取决于你的使用场景：个人开发者推荐 Claude Console 按量付费，重度用户推荐 Pro/Max 订阅，企业用户可以使用 Bedrock/Vertex 集成。

**最佳实践清单**：

1. 优先选择原生安装，避免使用已废弃的 npm 安装
2. 安装后立即运行 `claude doctor` 验证
3. 遇到问题时先检查 PATH 配置
4. Windows 用户确保 WSL 或 Git Bash 正确配置
5. 定期更新（原生安装自动更新，其他方式需手动）
6. 在项目根目录运行 Claude Code 以获得最佳上下文

如果你想进一步了解 Claude Code 的高级功能，如 MCP 服务器配置，可以参考 [MCP 服务器完整配置指南](/zh/topics/claude)。对于 API 使用和配置，可以查看 [Claude API 购买和配置指南](/zh/posts/claude-api-purchasing-guide)。如需了解更多 API 服务信息，可以访问 [laozhang.ai 文档](https://docs.laozhang.ai/) 获取详细说明。