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

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 详细对比。

系统要求是安装前必须确认的关键信息。根据官方文档，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 支持的国家/地区使用。

安装方式选择指南

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 命令即可自动迁移。

选择建议：如果你是新用户，直接选择原生安装。如果你是 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 安装。

方案一：使用原生 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 使用现有的云基础设施。这需要额外的配置，具体请参考官方文档。

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

常见问题与故障排查

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 安装失败

常见原因和解决方案：

问题 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 服务器完整配置指南。对于 API 使用和配置，可以查看 Claude API 购买和配置指南。如需了解更多 API 服务信息，可以访问 laozhang.ai 文档 获取详细说明。