Claude Code 安装配置指南：macOS 篇
TLDR: 本文详细介绍如何在 macOS 上安装和配置 Claude Code。推荐使用官方安装脚本（支持自动更新），也可通过 Homebrew 安装。全文覆盖环境准备、安装步骤、代理配置和常见问题排查。
什么是 Claude Code
Claude Code 是 Anthropic 推出的官方 CLI 工具，让你可以在终端中直接与 Claude 交互进行软件开发。它支持：
- 直接在终端中与 Claude 对话
- 读取、编写和修改代码文件
- 执行 Shell 命令
- 搜索和分析代码库
- 集成 Git 工作流
与传统的 Web 界面相比，Claude Code 更适合开发者：无需复制粘贴代码，Claude 可以直接操作你的项目文件。
系统要求
| 组件 | 要求 |
|---|---|
| 操作系统 | macOS 13 Ventura 或更高版本 |
| 芯片 | Apple Silicon (M1/M2/M3/M4) 或 Intel |
| 网络 | 能访问 claude.ai（或配置 API 代理） |
| 终端 | 系统终端、iTerm2、Warp 等 |
注意：原生安装方式不需要预装 Node.js，安装脚本会自动处理依赖。
安装方式
macOS 有两种安装方式：官方脚本安装（推荐）和 Homebrew 安装。
方式一：官方脚本安装（推荐）
打开终端，执行：
curl -fsSL https://claude.ai/install.sh | bash
官方脚本安装支持自动后台更新，始终保持最新版本。
安装完成后，输入 claude 即可启动。
方式二：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)"
验证安装
# 检查版本
claude --version
# 检查安装状态
claude doctor
首次启动与配置
启动 Claude Code：
claude
首次启动会有多个初始化设置：
- 认证方式：选择登录 Anthropic 账号或使用 API Key
- 主题设置：选择深色/浅色主题
- 权限设置：选择默认权限级别
一路按回车使用默认值即可。
在 Claude Code 中输入 hi 测试是否正常工作。按 Ctrl + C 两次可退出。
网络代理配置（可选）
如果你需要配置代理访问网络，编辑 ~/.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
或添加到配置文件持久化：
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
常见代理软件默认端口：
| 代理软件 | 默认端口 |
|---|---|
| ClashX / Clash | 7890 |
| V2RayU | 10808 |
| Shadowsocks | 1080 |
| Surge | 6152 |
高级配置
配置 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' >> ~/.zshrc
source ~/.zshrc
方式三：配置第三方 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 的配置文件位于 ~/.claude/ 目录：
| 文件 | 说明 |
|---|---|
settings.json |
全局设置 |
CLAUDE.md |
自定义系统提示词 |
项目目录/.claude/settings.local.json |
项目级设置 |
自定义系统提示词
创建或编辑 ~/.claude/CLAUDE.md：
# My Custom Instructions
- 使用中文回复
- 代码注释使用英文
- 优先使用 TypeScript
IDE 集成
VS Code 集成
Claude Code 可以与 VS Code 终端无缝配合：
- 在 VS Code 中打开项目
- 打开终端（
Cmd +） - 运行
claude
Cursor 集成
Cursor 用户可以直接在 Cursor 终端中使用 Claude Code。
macOS 特有配置
终端推荐
macOS 推荐使用以下终端之一：
| 终端 | 特点 |
|---|---|
| iTerm2 | 功能强大的终端模拟器，支持分屏、热键窗口 |
| Warp | 现代化 AI 终端，内置 AI 辅助 |
| Alacritty | 轻量高性能，GPU 加速渲染 |
| Kitty | 高性能，支持图片显示 |
| 系统终端 | macOS 自带，满足基本需求 |
Rosetta 2（Intel 兼容层）
如果你使用 Apple Silicon Mac 并遇到某些工具的兼容性问题：
softwareupdate --install-rosetta
防火墙设置
如果 macOS 防火墙阻止 Claude Code 网络连接：
- 打开「系统设置」→「隐私与安全性」→「防火墙」
- 点击「防火墙选项」
- 找到相关项目，设置为「允许传入连接」
常用命令速查
基本操作
| 命令 | 说明 |
|---|---|
claude |
启动 Claude Code |
claude --help |
查看帮助信息 |
claude --version |
查看版本号 |
claude doctor |
检查安装状态 |
claude -c "your prompt" |
单次对话模式 |
会话内命令
| 命令 | 说明 |
|---|---|
/help |
查看帮助 |
/clear |
清除上下文 |
/compact |
压缩上下文 |
/cost |
查看当前会话成本 |
/model |
切换模型 |
/config |
打开配置 |
快捷键
| 快捷键 | 说明 |
|---|---|
Ctrl + C |
中断当前操作 |
Ctrl + C × 2 |
退出 Claude Code |
Ctrl + L |
清屏 |
↑ / ↓ |
浏览历史输入 |
Tab |
自动补全 |
常见问题排查
Q1: 安装脚本执行失败
问题：curl: command not found 或下载失败
解决方案：
# 确保 curl 已安装（macOS 默认自带）
which curl
# 如果网络问题，检查代理配置
echo $http_proxy
# 尝试直接访问
curl -I https://claude.ai
Q2: Homebrew 安装报错
问题：brew install 失败
解决方案：
# 更新 Homebrew
brew update
# 清理缓存
brew cleanup
# 重试安装
brew install --cask claude-code
Q3: 防火墙阻止连接
问题：macOS 系统提示是否允许网络连接
解决方案：点击「允许」。如果误点了拒绝：
- 打开「系统设置」→「隐私与安全性」→「防火墙」
- 点击「防火墙选项」
- 找到相关项目，设置为「允许传入连接」
Q4: Claude Code 启动后无响应
问题：启动后长时间无响应或报错
排查步骤：
- 检查网络连接：
curl -I https://claude.ai - 检查 API Key：
echo $ANTHROPIC_API_KEY - 查看详细日志：
claude --verbose - 重置配置：
rm -rf ~/.claude && claude
Q5: Apple Silicon 兼容性问题
问题：在 M1/M2/M3/M4 Mac 上某些功能异常
解决方案：
# 安装 Rosetta 2
softwareupdate --install-rosetta
# 或在 Rosetta 模式下运行终端
# 右键终端应用 → 显示简介 → 勾选「使用 Rosetta 打开」
Q6: 如何更新 Claude Code
根据安装方式选择更新方法：
# 官方脚本安装（自动更新，通常无需手动操作）
# 如需强制更新，重新执行安装脚本：
curl -fsSL https://claude.ai/install.sh | bash
# Homebrew 安装
brew upgrade claude-code
Q7: 如何完全卸载
# 官方脚本安装
rm -rf ~/.claude
rm -f /usr/local/bin/claude
# Homebrew 安装
brew uninstall claude-code
rm -rf ~/.claude
最佳实践
1. 使用项目级配置
为每个项目创建 .claude/ 目录，存放项目特定的配置和提示词。
mkdir -p your-project/.claude
echo "# Project-specific instructions" > your-project/.claude/CLAUDE.md
2. 配合 Git 使用
Claude Code 与 Git 集成良好，可以直接进行 commit、创建 PR 等操作。建议在 Git 仓库中使用。
3. 合理使用上下文
- 使用
/clear清除无关上下文 - 使用
/compact压缩长对话 - 大型项目中善用
@file引用特定文件
4. 终端配置优化
# 在 ~/.zshrc 中添加别名
alias cc='claude'
alias ccc='claude -c'
5. 安全注意事项
- 不要在公共环境中暴露 API Key
- 定期检查 Claude Code 的文件操作权限
- 敏感项目建议使用受限权限模式
- API Key 不要提交到 Git 仓库
总结
完成本指南后，你应该能够：
✅ 使用官方脚本或 Homebrew 安装 Claude Code ✅ 完成首次启动和基本配置 ✅ 配置网络代理和 API Key ✅ 解决常见的安装和使用问题
Claude Code 是一个强大的 AI 编程助手，熟练使用后可以显著提升开发效率。如有问题，可参考 官方文档 或在 GitHub Issues 提交反馈。