安装指南
Installation Guide
本章将详细介绍 Claude Code 在各平台上的安装方法，包括系统要求、多种安装方式、网络配置以及常见问题排查。
系统要求
System Requirements
在安装 Claude Code 之前，请确认你的系统满足以下最低要求：
| 要求项 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.0+ | 20.x LTS 或 22.x LTS |
| npm | 8.0+ | 10.x+ |
| 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL） | macOS 14+、Ubuntu 22.04+、Windows 11（WSL2） |
| 内存 | 4 GB RAM | 8 GB+ RAM |
| 磁盘空间 | 500 MB | 1 GB+ |
| 网络 | 可访问 api.anthropic.com | 稳定的宽带连接 |
检查 Node.js 版本
node --version
# 输出应为 v18.x.x 或更高
npm --version
# 输出应为 8.x.x 或更高如果尚未安装 Node.js，推荐使用 nvm（Node Version Manager）进行安装：
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 安装 Node.js LTS
nvm install --lts
nvm use --lts# 在 WSL 中安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重启终端后
nvm install --lts
nvm use --lts方式一：原生安装器（推荐）
Method 1: Native Installer (Recommended)
原生安装器是最简单的安装方式，一行命令即可完成安装和配置。
curl -fsSL https://claude.ai/install.sh | shcurl -fsSL https://claude.ai/install.sh | shcurl -fsSL https://claude.ai/install.sh | sh# Windows 用户需要先安装 WSL，然后在 WSL 内运行
wsl --install
# 重启后，在 WSL 终端中执行：
curl -fsSL https://claude.ai/install.sh | sh安装完成后，验证安装是否成功：
claude --version
# 输出示例：Claude Code v1.x.x安装器做了什么？
原生安装器会自动完成以下步骤：
- 检测你的操作系统和架构
- 下载适合你平台的 Claude Code 二进制文件
- 将可执行文件放置到系统 PATH 中（通常是
/usr/local/bin/） - 设置必要的文件权限
方式二：npm 全局安装
Method 2: npm Global Install
如果你已有 Node.js 环境，可以通过 npm 全局安装：
npm install -g @anthropic-ai/claude-code安装过程说明
# 完整的安装流程
npm install -g @anthropic-ai/claude-code
# 验证安装
claude --version
# 查看安装位置
which claude # macOS/Linux
where claude # Windows (Git Bash)权限问题处理
在 macOS/Linux 上，如果遇到权限错误，不要使用 sudo。推荐修改 npm 的全局安装目录：
# 创建全局安装目录
mkdir -p ~/.npm-global
# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'
# 添加到 PATH（写入 shell 配置文件）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 重新安装
npm install -g @anthropic-ai/claude-code对于使用 zsh 的用户（macOS 默认），将上面的 ~/.bashrc 替换为 ~/.zshrc。
方式三：npx 临时运行
Method 3: npx Temporary Run
如果你只想试用 Claude Code 而不想全局安装，可以使用 npx：
npx @anthropic-ai/claude-codenpx 的特点
| 优点 | 缺点 |
|---|---|
| 无需全局安装 | 每次启动都需要下载 |
| 始终使用最新版本 | 启动速度较慢 |
| 不污染全局环境 | 无法使用部分全局配置 |
指定版本运行
# 运行特定版本
npx @anthropic-ai/claude-code@1.0.0
# 运行最新版本（跳过缓存）
npx @anthropic-ai/claude-code@latest何时使用 npx？
npx 适合以下场景：
- 初次试用 Claude Code
- 在无法全局安装软件的共享机器上
- 临时使用特定版本
- CI/CD 环境中一次性运行
Windows 特别说明
Windows Special Notes
Claude Code 在 Windows 上的支持需要额外注意。以下是推荐的配置方案：
方案一：WSL2（强烈推荐）
WSL2（Windows Subsystem for Linux 2）提供了最佳的 Claude Code 使用体验：
# 1. 安装 WSL2（以管理员身份运行 PowerShell）
wsl --install
# 2. 重启计算机
# 3. 打开 WSL 终端，安装 Claude Code
curl -fsSL https://claude.ai/install.sh | shWSL2 的优势：
- 完整的 Linux 环境，兼容性最好
- 文件系统性能优秀
- 与 VS Code 无缝集成（Remote - WSL 扩展）
方案二：Git Bash
如果不想安装 WSL，可以使用 Git for Windows 提供的 Bash 环境：
# 前提：已安装 Git for Windows
# 在 Git Bash 中执行
npm install -g @anthropic-ai/claude-code
claudeWindows 环境对比
| 特性 | WSL2 | Git Bash | CMD/PowerShell |
|---|---|---|---|
| 推荐度 | 强烈推荐 | 可用 | 不推荐 |
| 兼容性 | 完整 | 大部分 | 有限 |
| 文件操作 | 原生 Linux | 模拟 | 路径问题多 |
| Shell 命令 | 完整支持 | 大部分支持 | 不支持 |
| 性能 | 优秀 | 良好 | - |
Windows 原生终端
直接在 CMD 或 PowerShell 中运行 Claude Code 可能会遇到兼容性问题。Claude Code 的许多内部命令依赖 Unix shell 语法（如管道、重定向等），因此强烈建议使用 WSL2 或 Git Bash。
代理与网络配置
Proxy and Network Configuration
如果你的网络环境需要通过代理访问互联网，需要配置以下环境变量：
HTTP/HTTPS 代理
# 设置代理（在 shell 配置文件中添加以持久化）
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
# 如果代理需要认证
export HTTP_PROXY=http://username:password@proxy.example.com:8080
export HTTPS_PROXY=http://username:password@proxy.example.com:8080SOCKS 代理
export ALL_PROXY=socks5://proxy.example.com:1080不需要代理的地址
export NO_PROXY=localhost,127.0.0.1,.internal.company.com自定义 API 端点
如果你的组织使用自定义的 API 网关或中转服务：
# 设置自定义 API 基础 URL
export ANTHROPIC_BASE_URL=https://api-gateway.company.com/anthropicSSL 证书问题
在企业网络中，可能需要配置自定义 CA 证书：
# 指定自定义 CA 证书
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt常见安装问题排查
Troubleshooting Common Installation Issues
问题 1：command not found: claude
安装后找不到 claude 命令：
# 检查 npm 全局安装路径是否在 PATH 中
npm config get prefix
# 确保 <prefix>/bin 在你的 PATH 中
# 查看 PATH
echo $PATH
# 临时修复
export PATH=$(npm config get prefix)/bin:$PATH
# 永久修复（添加到 shell 配置文件）
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc问题 2：权限被拒绝（EACCES）
# 不要使用 sudo npm install！
# 正确的做法是修改 npm 全局目录（参见上文）
# 或者使用 nvm 管理 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
npm install -g @anthropic-ai/claude-code问题 3：网络超时
# 设置 npm 的超时时间
npm config set fetch-timeout 60000
# 使用镜像源（中国大陆用户）
npm config set registry https://registry.npmmirror.com
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code问题 4：Node.js 版本过低
# 检查当前版本
node --version
# 如果低于 18，使用 nvm 升级
nvm install 20
nvm use 20
nvm alias default 20
# 重新安装
npm install -g @anthropic-ai/claude-code问题 5：Windows 路径过长
Windows 默认有 260 字符的路径长度限制：
# 以管理员身份运行 PowerShell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force更新 Claude Code
Updating Claude Code
保持 Claude Code 更新到最新版本，以获取新功能和 bug 修复：
使用内置更新命令
claude update使用 npm 更新
npm update -g @anthropic-ai/claude-code查看当前版本和最新版本
# 当前安装的版本
claude --version
# npm 上的最新版本
npm view @anthropic-ai/claude-code version自动更新提示
Claude Code 会在有新版本时自动提示你更新。你可以在启动时看到类似以下的提示：
╔══════════════════════════════════════════╗
║ Claude Code v1.1.0 is available! ║
║ Run `claude update` to upgrade. ║
╚══════════════════════════════════════════╝卸载
Uninstallation
如果需要卸载 Claude Code：
# npm 全局安装的情况
npm uninstall -g @anthropic-ai/claude-code
# 清理配置文件（可选）
rm -rf ~/.claude小结
Summary
| 安装方式 | 命令 | 适用场景 |
|---|---|---|
| 原生安装器 | curl -fsSL https://claude.ai/install.sh | sh | 推荐给大多数用户 |
| npm 全局安装 | npm install -g @anthropic-ai/claude-code | 已有 Node.js 环境 |
| npx 临时运行 | npx @anthropic-ai/claude-code | 试用或临时使用 |
安装完成后，让我们进入下一章：初次使用 Claude Code。