Claude Code macOS 系统完整安装指南

系统要求

最低配置

操作系统: macOS 11.0 (Big Sur) 或更高版本
处理器: Intel 芯片或 Apple Silicon (M1/M2/M3)
内存: 至少 4GB RAM（推荐 8GB+）
存储空间: 至少 500MB 可用空间
网络: 需要互联网连接（用于 API 调用和更新）

必需软件

Terminal: macOS 内置终端或 iTerm2
curl: 用于下载安装脚本（系统自带）
Homebrew: 可选，用于包管理器安装方式
Node.js: 可选，用于 npm 安装方式

安装步骤

macOS 系统提供四种安装 Claude Code 的方式，可根据需求选择。

方式一: 使用 Shell 脚本一键安装（推荐）

这是最简单快捷的安装方式，适合大多数用户。

步骤 1: 打开终端

按 Command + Space 打开 Spotlight
输入 "Terminal" 或 "终端" 并按回车
或在应用程序 → 实用工具中找到"终端"

步骤 2: 执行安装命令

安装最新稳定版本:

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

安装指定版本:

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

安装最新开发版:

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

步骤 3: 等待安装完成

脚本会自动检测你的系统架构（Intel x64 或 Apple Silicon ARM64）
下载对应的二进制文件
安装到 ~/.local/bin/ 目录
自动配置执行权限

安装过程示例输出:

                        Detecting platform...
Platform: darwin-arm64
Downloading Claude Code v1.0.58...
Installing to /Users/username/.local/bin/
Claude Code installed successfully!
                    

方式二: 使用 Homebrew 安装

如果你习惯使用 Homebrew 管理软件包，这是最优雅的方式。

步骤 1: 安装 Homebrew（如果尚未安装）

                    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
                

步骤 2: 使用 Homebrew 安装 Claude Code

brew install claude-code

Homebrew 会自动：

下载适合你系统的版本
安装到 /opt/homebrew/bin/（Apple Silicon）或 /usr/local/bin/（Intel）
配置 PATH 环境变量

方式三: 手动下载安装

适合需要更多控制或离线安装的场景。

步骤 1: 确定你的芯片架构

uname -m

arm64: Apple Silicon (M1/M2/M3)
x86_64: Intel 芯片

步骤 2: 下载对应版本

访问 GitHub Releases 页面或使用 curl 下载：

Apple Silicon (M1/M2/M3):

                    curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-darwin-arm64 -o claude
                

Intel 芯片:

                    curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-darwin-x64 -o claude
                

步骤 3: 安装到本地目录

                    # 创建安装目录
mkdir -p ~/.local/bin

# 移动文件
mv claude ~/.local/bin/

# 添加执行权限
chmod +x ~/.local/bin/claude
                

方式四: 使用 Node.js/npm 安装

适合开发者或需要使用 npm 包管理器的场景。

步骤 1: 安装 Node.js 环境

方法一: 使用 Homebrew（推荐）

brew install node

方法二: 从官网下载

访问 https://nodejs.org/
下载 macOS 安装包（.pkg 文件）
双击安装包按照向导完成安装

验证安装:

                    node --version
npm --version
                

步骤 2: 安装 Claude Code

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

提示: 如果遇到权限问题，可能需要使用 sudo:

sudo npm install -g @anthropic-ai/claude-code

步骤 3: 验证安装

claude --version

如果显示版本号，说明安装成功。

环境配置

安装完成后，需要配置 PATH 环境变量和 Shell 配置。

配置 PATH 环境变量

自动配置（推荐）

大多数情况下，安装脚本已自动配置。验证一下：

echo $PATH | grep ".local/bin"

如果有输出，说明已配置成功。

手动配置 - Bash 用户

编辑 ~/.bash_profile 或 ~/.bashrc：

nano ~/.bash_profile

在文件末尾添加：

                    # 添加 Claude Code 到 PATH
export PATH="$HOME/.local/bin:$PATH"
                

保存并使配置生效：

source ~/.bash_profile

手动配置 - Zsh 用户（macOS 默认）

编辑 ~/.zshrc：

nano ~/.zshrc

在文件末尾添加：

                    # 添加 Claude Code 到 PATH
export PATH="$HOME/.local/bin:$PATH"
                

保存并使配置生��：

source ~/.zshrc

验证配置

                    # 检查 PATH
echo $PATH

# 检查 claude 命令位置
which claude
                

预期输出:

/Users/username/.local/bin/claude

API 配置

Claude Code 需要 Anthropic API Key 才能正常工作。

获取 API Key

官方 API

访问 https://console.anthropic.com/
登录或注册账号
进入 "API Keys" 页面
点击 "Create Key" 创建新的 API 密钥
复制生成的密钥（格式: sk-ant-api03-...）

中转 API（国内推荐）

如果你在中国大陆，可以使用中转服务：

访问中转服务商网站（如 https://api.nekoapi.com/）
注册账号并充值
获取中转 API Key 和 Base URL

配置 API 环境变量

Bash 用户配置

编辑 ~/.bash_profile：

nano ~/.bash_profile

添加以下内容：

                    # Claude Code API 配置
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

# 如果使用中转服务
export ANTHROPIC_BASE_URL="https://api.claudecode.net.cn/api/claudecode"

# Auth Token（与 API Key 相同）
export ANTHROPIC_AUTH_TOKEN="sk-ant-api03-你的密钥"
                

保存并使配置生效：

source ~/.bash_profile

Zsh 用户配置（macOS 默认）

编辑 ~/.zshrc：

nano ~/.zshrc

添加以下内容：

                    # Claude Code API 配置
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

# 如果使用中转服务
export ANTHROPIC_BASE_URL="https://api.claudecode.net.cn/api/claudecode"

# Auth Token（与 API Key 相同）
export ANTHROPIC_AUTH_TOKEN="sk-ant-api03-你的密钥"
                

保存并使配置生效：

source ~/.zshrc

验证配置

                    echo $ANTHROPIC_API_KEY
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN
                

应该显示你配置的值。

验证安装

配置完成后，验证 Claude Code 是否正常工作。

步骤 1: 打开新的终端

重要：必须打开新的终端窗口或重新加载配置，让环境变量生效。

                    # Bash
source ~/.bash_profile

# Zsh
source ~/.zshrc
                

步骤 2: 检查版本

claude --version

预期输出:

Claude Code v1.0.58

步骤 3: 检查安装位置

which claude

预期输出:

/Users/username/.local/bin/claude

步骤 4: 系统诊断

claude doctor

此命令会检查：

Claude Code 版本
安装类型（原生 vs npm）
API 配置状态
网络连接
系统架构

步骤 5: 测试运行

claude "你好，Claude！"

如果一切正常，Claude 会回复你的问候，说明安装和配置都成功了。

常见问题

Q1: 提示 "command not found: claude"

原因：PATH 环境变量未正确配置。

解决方法：

检查 PATH：echo $PATH | grep ".local/bin"
如果没有输出，重新配置 Shell 配置文件
确保重新加载配置：source ~/.zshrc 或 source ~/.bash_profile
验证安装位置：ls -la ~/.local/bin/claude

Q2: macOS 提示 "无法打开，因为无法验证开发者"

原因：macOS Gatekeeper 安全机制阻止未签名应用。

解决方法：

右键点击 claude 文件，选择"打开"
或在终端中运行：xattr -d com.apple.quarantine ~/.local/bin/claude
或在"系统偏好设置" → "安全性与隐私" → "通用"中点击"仍要打开"

Q3: Apple Silicon (M1/M2/M3) 性能问题

症状：运行缓慢或需要 Rosetta 转译。

解决方法：

确认下载了 ARM64 版本：file ~/.local/bin/claude
应该显示 Mach-O 64-bit executable arm64
如果是 x86_64，重新下载 ARM64 版本

Q4: Homebrew 安装路径问题

症状：Homebrew 安装后找不到命令。

解决方法：

Apple Silicon：确保 /opt/homebrew/bin 在 PATH 中
Intel：确保 /usr/local/bin 在 PATH 中

                    # Apple Silicon
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc

# Intel
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
                

进阶配置

Shell 别名配置

编辑 ~/.zshrc 或 ~/.bash_profile 添加别名：

                    # Claude Code 别名
alias cc='claude'
alias ccd='claude doctor'
alias ccu='claude update'

# 快速提问函数
ask() {
  claude "$@"
}
                

自动补全

Zsh 自动补全:

                    # 生成补全脚本
claude --zsh-completion > ~/.claude-completion.zsh

# 加载补全
echo 'source ~/.claude-completion.zsh' >> ~/.zshrc
source ~/.zshrc
                

更新 Claude Code

原生安装更新:

claude update

Homebrew 更新:

brew upgrade claude-code

npm 更新:

npm update -g @anthropic-ai/claude-code

卸载 Claude Code

原生/手动安装卸载:

                    # 删除二进制文件
rm ~/.local/bin/claude

# 删除配置文件（可选）
rm -rf ~/.claude

# 删除缓存（可选）
rm -rf ~/.cache/claude
                

Homebrew 卸载:

brew uninstall claude-code

npm 卸载:

npm uninstall -g @anthropic-ai/claude-code

总结

完成上述步骤后，你已经在 macOS 系统上成功安装并配置了 Claude Code。

快速命令参考

                    claude                    # 启动交互式会话
claude "帮我写一个脚本"   # 直接提问
claude --version          # 查看版本
claude doctor             # 系统诊断
claude update             # 更新 Claude Code
claude --help             # 查看帮助
which claude              # 查看安装位置
                

macOS 特有优势:

原生 Unix 环境：完美的命令行体验
Apple Silicon 优化：原生支持 M1/M2/M3 芯片
Homebrew 生态：优雅的包管理
Terminal 原生支持：无需额外配置

下一步建议:

阅读官方文档了解更多功能
在实际项目中使用 Claude Code
配置 Shell 别名提高效率
探索与 macOS 开发工具的集成

Claude Code macOS 系统完整安装指南

系统要求

最低配置

推荐配置

必需软件

安装步骤

方式一: 使用 Shell 脚本一键安装（推荐）

步骤 1: 打开终端

步骤 2: 执行安装命令

步骤 3: 等待安装完成

方式二: 使用 Homebrew 安装

步骤 1: 安装 Homebrew（如果尚未安装）

步骤 2: 使用 Homebrew 安装 Claude Code

方式三: 手动下载安装

步骤 1: 确定你的芯片架构

步骤 2: 下载对应版本

步骤 3: 安装到本地目录

方式四: 使用 Node.js/npm 安装

步骤 1: 安装 Node.js 环境

步骤 2: 安装 Claude Code

步骤 3: 验证安装

环境配置

配置 PATH 环境变量

自动配置（推荐）

手动配置 - Bash 用户

手动配置 - Zsh 用户（macOS 默认）

验证配置

API 配置

获取 API Key

官方 API

中转 API（国内推荐）

配置 API 环境变量

Bash 用户配置

Zsh 用户配置（macOS 默认）

验证配置

验证安装

步骤 1: 打开新的终端

步骤 2: 检查版本

步骤 3: 检查安装位置

步骤 4: 系统诊断

步骤 5: 测试运行

常见问题

Q1: 提示 "command not found: claude"

Q2: macOS 提示 "无法打开，因为无法验证开发者"

Q3: Apple Silicon (M1/M2/M3) 性能问题

Q4: Homebrew 安装路径问题

进阶配置

Shell 别名配置

自动补全

更新 Claude Code

卸载 Claude Code

总结

快速命令参考