Claude Code 安装配置完全指南：Windows / macOS / Linux
TLDR: 本文详细介绍如何在 Windows、macOS 和 Linux 三大操作系统上安装和配置 Claude Code。Windows 支持原生安装或 WSL 方式，macOS 和 Linux 可直接使用官方安装脚本。全文覆盖环境准备、安装步骤、代理配置和常见问题排查。
什么是 Claude Code
Claude Code 是 Anthropic 推出的官方 CLI 工具，让你可以在终端中直接与 Claude 交互进行软件开发。它支持：
- 直接在终端中与 Claude 对话
- 读取、编写和修改代码文件
- 执行 Shell 命令
- 搜索和分析代码库
- 集成 Git 工作流
与传统的 Web 界面相比，Claude Code 更适合开发者：无需复制粘贴代码，Claude 可以直接操作你的项目文件。
系统要求
通用要求
| 组件 | 最低要求 |
|---|---|
| 网络 | 能访问 claude.ai（或配置 API 代理） |
| 终端 | 支持 ANSI 转义序列的现代终端 |
注意：原生安装方式不需要预装 Node.js，安装脚本会自动处理依赖。
各平台特定要求
| 平台 | 版本要求 |
|---|---|
| Windows | Windows 10 2004 或更高版本 |
| macOS | macOS 13 Ventura 或更高版本 |
| Linux | 主流发行版（Ubuntu 20.04+、Debian 11+、Fedora 36+） |
第一部分：Windows 安装指南
Windows 用户有两种安装方式：原生安装（推荐）和 WSL 安装。
方式一：原生安装（推荐）
原生安装支持自动更新，是官方推荐的安装方式。
PowerShell 安装
以管理员身份打开 PowerShell，执行：
irm https://claude.ai/install.ps1 | iex
CMD 安装
打开命令提示符，执行：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
WinGet 安装
如果你使用 Windows 包管理器：
winget install Anthropic.ClaudeCode
注意：WinGet 安装不支持自动更新，需要手动执行
winget upgrade Anthropic.ClaudeCode更新。
安装完成后，打开新的终端窗口，输入 claude 即可启动。
方式二：WSL 安装
适用场景：如果你需要与 macOS/Linux 完全一致的终端体验，或需要使用 Linux 特定工具，可以选择 WSL 方式。
步骤 1：启用 Windows 子系统功能
- 按
Win + S搜索「启用或关闭 Windows 功能」 - 找到「适用于 Linux 的 Windows 子系统」选项
- 勾选后点击「确定」
- 等待安装完成，按提示重启电脑
步骤 2：安装 WSL
⚠️ 注意：请使用 PowerShell 或 Windows Terminal，不要使用 CMD。
打开 PowerShell（以管理员身份），执行：
wsl --install
安装完成后系统会提示重启，按要求重启电脑。
步骤 3：安装 Ubuntu 发行版
重启后，打开 PowerShell 或 Windows Terminal：
wsl --install -d Ubuntu
安装完成后会要求创建 Linux 用户名和密码。
💡 密码输入提示：输入密码时屏幕不会显示任何字符，这是 Linux 的安全特性，正常输入后按回车即可。
步骤 4：进入 WSL 终端
两种方式打开 WSL：
方式一：在 Windows Terminal 标签栏右侧的下拉菜单中选择「Ubuntu」
方式二：在 PowerShell 中直接输入：
wsl
步骤 5：配置网络代理（可选）
⚠️ 重要：WSL 终端的网络与 Windows 系统网络是独立的，需要单独配置代理。
根据你的代理软件选择对应端口：
| 代理软件 | 默认端口 |
|---|---|
| Clash | 7890 |
| V2Ray | 10808 |
| Shadowsocks | 1080 |
将以下命令中的端口号替换为你的代理端口：
# 设置代理环境变量（以 10808 端口为例）
echo 'export http_proxy=http://127.0.0.1:10808 https_proxy=http://127.0.0.1:10808 all_proxy=socks5://127.0.0.1:10808' >> ~/.bashrc && source ~/.bashrc
验证代理是否生效：
curl -I https://www.google.com
步骤 6：安装基础开发工具
更新包管理器并安装必要工具：
sudo apt update && sudo apt install -y git curl unzip
步骤 7：安装 Claude Code
执行官方安装脚本（推荐）：
curl -fsSL https://claude.ai/install.sh | bash
💡 提示：原生安装脚本会自动处理依赖，无需手动安装 Node.js。安装过程可能需要几分钟，请耐心等待。
步骤 8：启动并配置 Claude Code
首次启动：
claude
首次启动会有多个初始化设置：
- 认证方式：选择登录 Anthropic 账号或使用 API Key
- 主题设置：选择深色/浅色主题
- 权限设置：选择默认权限级别
一路按回车使用默认值即可。
步骤 9：验证安装
在 Claude Code 中输入：
hi
如果 Claude 正常回复，说明安装成功！
按 Ctrl + C 两次可退出 Claude Code。
可以使用 claude doctor 命令检查安装状态和版本信息。
第二部分：macOS 安装指南
macOS 有两种安装方式：原生脚本安装（推荐）和 Homebrew 安装。
方式一：原生脚本安装（推荐）
打开终端，执行：
curl -fsSL https://claude.ai/install.sh | bash
原生安装支持自动后台更新，始终保持最新版本。
方式二：Homebrew 安装
如果你习惯使用 Homebrew 管理软件：
brew install --cask claude-code
注意：Homebrew 安装不支持自动更新，需要定期执行
brew upgrade claude-code手动更新。
安装 Homebrew（如未安装）
如果你还没有 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装完成后，根据终端提示将 Homebrew 添加到 PATH：
# Apple Silicon Mac (M1/M2/M3/M4)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
# Intel Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"
配置网络代理（可选）
如果需要配置代理，编辑 ~/.zshrc：
# 临时设置代理
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890
# 或添加到 ~/.zshrc 持久化
echo 'export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890' >> ~/.zshrc
source ~/.zshrc
启动 Claude Code
claude
完成初始化设置后即可使用。使用 claude doctor 可检查安装状态。
macOS 特有配置
终端推荐
macOS 推荐使用以下终端之一：
- iTerm2：功能强大的终端模拟器
- Warp：现代化 AI 终端
- Alacritty：轻量高性能终端
- 系统终端：macOS 自带终端也可满足基本需求
Rosetta 2（Intel 兼容层）
如果你使用 Apple Silicon Mac 并遇到兼容性问题：
softwareupdate --install-rosetta
第三部分：Linux 安装指南
Linux 上推荐使用官方安装脚本，适用于所有主流发行版。
通用安装方式（推荐）
适用于 Ubuntu、Debian、Fedora、Arch 等所有发行版：
curl -fsSL https://claude.ai/install.sh | bash
安装脚本会自动检测系统架构（x64/arm64）和 libc 类型（glibc/musl），下载对应的二进制文件并完成安装。
验证安装
# 检查版本
claude --version
# 检查安装状态
claude doctor
手动安装依赖（可选）
如果安装脚本执行失败，可能需要先安装 curl：
# Ubuntu / Debian
sudo apt update && sudo apt install -y curl
# Fedora
sudo dnf install -y curl
# Arch Linux
sudo pacman -S curl
# 然后重新执行安装脚本
curl -fsSL https://claude.ai/install.sh | bash
Linux 代理配置
编辑 ~/.bashrc 或 ~/.zshrc：
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1
保存后执行 source ~/.bashrc 生效。
第四部分：高级配置
配置 API Key
Claude Code 支持多种认证方式：
方式一：OAuth 登录（推荐）
首次启动时选择「Login with Anthropic」，会自动打开浏览器完成认证。
方式二：API Key
如果你有 Anthropic API Key：
# 设置环境变量
export ANTHROPIC_API_KEY=your-api-key-here
# 或添加到配置文件持久化
echo 'export ANTHROPIC_API_KEY=your-api-key-here' >> ~/.bashrc
source ~/.bashrc
方式三：配置第三方 API 代理
如果使用第三方 API 代理服务：
# 设置 API 基础 URL
export ANTHROPIC_BASE_URL=https://your-proxy.com/v1
# 设置 API Key
export ANTHROPIC_API_KEY=your-proxy-api-key
配置文件位置
Claude Code 的配置文件位于：
| 平台 | 配置目录 |
|---|---|
| macOS | ~/.claude/ |
| Linux | ~/.claude/ |
| Windows (WSL) | ~/.claude/ |
主要配置文件：
~/.claude/settings.json：全局设置~/.claude/CLAUDE.md：自定义系统提示词项目目录/.claude/settings.local.json：项目级设置
自定义系统提示词
创建或编辑 ~/.claude/CLAUDE.md：
# My Custom Instructions
- 使用中文回复
- 代码注释使用英文
- 优先使用 TypeScript
IDE 集成
VS Code 集成
Claude Code 可以与 VS Code 终端无缝配合：
- 在 VS Code 中打开项目
- 打开终端（
Ctrl +） - 运行
claude
Cursor 集成
Cursor 用户可以直接在 Cursor 终端中使用 Claude Code。
第五部分：常用命令速查
基本操作
| 命令 | 说明 |
|---|---|
claude |
启动 Claude Code |
claude --help |
查看帮助信息 |
claude --version |
查看版本号 |
claude -c "your prompt" |
单次对话模式 |
会话内命令
| 命令 | 说明 |
|---|---|
/help |
查看帮助 |
/clear |
清除上下文 |
/compact |
压缩上下文 |
/cost |
查看当前会话成本 |
/model |
切换模型 |
/config |
打开配置 |
快捷键
| 快捷键 | 说明 |
|---|---|
Ctrl + C |
中断当前操作 |
Ctrl + C × 2 |
退出 Claude Code |
Ctrl + L |
清屏 |
↑ / ↓ |
浏览历史输入 |
Tab |
自动补全 |
常见问题排查
Q1: 安装脚本执行失败
问题：curl 命令报错或脚本下载失败
解决方案：
# 检查网络连接
curl -I https://claude.ai
# 如果网络不通，检查代理配置
echo $http_proxy
# 手动下载安装（macOS/Linux）
# 访问 https://code.claude.com/docs/en/setup 获取最新安装方式
Q2: WSL 中网络不通
问题：WSL 中无法访问网络或代理不生效
解决方案：
- 确保 Windows 代理软件开启了「允许局域网连接」
- 检查 WSL 中的代理端口是否正确
- 尝试使用 Windows 主机 IP 而非 127.0.0.1：
# 获取 Windows 主机 IP
export WIN_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export http_proxy=http://$WIN_HOST:7890
export https_proxy=http://$WIN_HOST:7890
Q3: Claude Code 启动后无响应
问题：启动后长时间无响应或报错
排查步骤：
- 检查网络连接：
curl -I https://claude.ai - 检查 API Key：
echo $ANTHROPIC_API_KEY - 查看详细日志：
claude --verbose - 重置配置：
rm -rf ~/.claude && claude
Q4: 安装后命令找不到
问题：安装完成后执行 claude 提示 command not found
解决方案：
# 重新打开终端窗口，或手动加载配置
source ~/.bashrc # Linux/WSL
source ~/.zshrc # macOS
# 检查安装路径
which claude
ls -la /usr/local/bin/claude
# 如果仍然找不到，重新执行安装脚本
curl -fsSL https://claude.ai/install.sh | bash
Q5: macOS 防火墙阻止连接
问题：macOS 系统提示是否允许网络连接
解决方案：点击「允许」。如果误点了拒绝：
- 打开「系统设置」→「隐私与安全性」→「防火墙」
- 点击「防火墙选项」
- 找到 Claude Code 相关项目，设置为「允许传入连接」
Q6: 如何更新 Claude Code
根据安装方式选择更新方法：
# 原生安装（自动更新，通常无需手动操作）
# 如需强制更新，重新执行安装脚本：
curl -fsSL https://claude.ai/install.sh | bash
# Homebrew 安装
brew upgrade claude-code
# WinGet 安装
winget upgrade Anthropic.ClaudeCode
Q7: 如何完全卸载
# macOS / Linux 原生安装
rm -rf ~/.claude
rm -f /usr/local/bin/claude
# Homebrew 安装
brew uninstall claude-code
# WinGet 安装
winget uninstall Anthropic.ClaudeCode
# 清理配置文件（所有平台通用）
rm -rf ~/.claude
最佳实践
1. 使用项目级配置
为每个项目创建 .claude/ 目录，存放项目特定的配置和提示词。
2. 配合 Git 使用
Claude Code 与 Git 集成良好，可以直接进行 commit、创建 PR 等操作。建议在 Git 仓库中使用。
3. 合理使用上下文
- 使用
/clear清除无关上下文 - 使用
/compact压缩长对话 - 大型项目中善用
@file引用
4. 安全注意事项
- 不要在公共环境中暴露 API Key
- 定期检查 Claude Code 的文件操作权限
- 敏感项目建议使用受限权限模式
总结
完成本指南后，你应该能够：
✅ 在 Windows（通过 WSL）上成功安装 Claude Code ✅ 在 macOS 上直接安装配置 Claude Code ✅ 在各主流 Linux 发行版上安装 Claude Code ✅ 配置网络代理和 API Key ✅ 解决常见的安装和使用问题
Claude Code 是一个强大的 AI 编程助手，熟练使用后可以显著提升开发效率。如有问题，可参考 官方文档 或在 GitHub Issues 提交反馈。