macOS 安装 Claude Code 完整教程

macOS 安装 Claude Code 完整教程

本文适配 macOS 12+（Monterey 及以上）系统，支持 Intel/Apple Silicon（M1/M2/M3）全机型，涵盖 Claude Code CLI 命令行、VS Code 插件两种核心使用方式的安装、配置与验证流程。

一、前置准备（必做）

1.1 系统与环境要求

• 系统版本：macOS 12.0+（Monterey、Ventura、Sonoma 均支持）

• 硬件兼容：Intel 芯片、Apple Silicon（M1/M2/M3）芯片全机型

• 基础依赖：Python 3.8+（CLI 方式必需）、网络环境（需可访问 Anthropic 服务器）

1.2 关键准备工作

1. 安装 Homebrew（推荐，简化依赖安装）

   打开「终端」（访达 → 应用程序 → 实用工具 → 终端），执行以下命令：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装过程中按提示输入电脑密码，等待完成即可。无 Homebrew 可跳过，后续采用手动安装方式。

2. 获取 Claude API Key1. 访问 Anthropic 官网控制台，注册/登录账号；2. 进入「API Keys」页面，点击「Create API Key」创建密钥；3. 复制生成的 API Key 并保存（后续配置必需，请勿泄露）。

二、安装方式一：Claude Code CLI（命令行，推荐）

通过 pip 安装官方 CLI 工具，支持终端直接执行编程交互、代码生成等操作。

2.1 安装 Python 依赖

# 1. 用 Homebrew 安装最新版 Python 3（推荐）
brew install python3

# 2. 验证 Python 版本（需 ≥3.8）
python3 --version

# 3. 升级 pip（避免安装失败）
pip3 install --upgrade pip

2.2 安装 Claude Code CLI

# 全局安装 anthropic-cli（Claude 官方 CLI 包）
pip3 install anthropic-cli

# 验证安装（输出版本号即成功）
anthropic --version

2.3 解决「command not found: anthropic」问题

若终端提示命令未识别，需配置 Python 二进制文件路径到系统环境变量：

# 1. 查看 Python 包安装路径
pip3 show anthropic-cli | grep Location

# 2. 复制路径（示例：/Users/你的用户名/Library/Python/3.11/lib/python/site-packages）
# 3. 将路径添加到环境变量（根据终端类型选择命令）
# 若终端是 zsh（macOS 默认）
echo 'export PATH="$HOME/Library/Python/3.11/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 若终端是 bash
echo 'export PATH="$HOME/Library/Python/3.11/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

注：将命令中的「3.11」替换为你的 Python 实际版本（通过python3 --version 查看）。

2.4 配置 API Key（核心步骤）

配置 API Key 后，CLI 工具才能正常调用 Claude 服务，支持临时配置和永久配置两种方式：

# 方式 1：临时配置（终端关闭后失效）
export ANTHROPIC_API_KEY="你的 Claude API Key"

# 方式 2：永久配置（推荐）
# zsh 终端
echo 'export ANTHROPIC_API_KEY="你的 Claude API Key"' >> ~/.zshrc
source ~/.zshrc

# bash 终端
echo 'export ANTHROPIC_API_KEY="你的 Claude API Key"' >> ~/.bash_profile
source ~/.bash_profile

# 验证配置（输出 API Key 即成功）
echo $ANTHROPIC_API_KEY

2.5 CLI 基础使用示例

# 1. 进入编程交互模式（实时对话编程）
anthropic code

# 2. 直接提交编程需求（生成指定代码）
anthropic code "写一个 Python 爬虫，爬取豆瓣 Top250 电影列表，保存为 CSV 文件，包含异常处理"

# 3. 指定模型（推荐 Claude 3 Sonnet，平衡速度与效果）
anthropic code --model claude-3-sonnet-20240229 "优化这段 JavaScript 代码的性能：[粘贴你的代码]"

# 4. 读取本地文件并分析/修复
anthropic code --file ./main.py "分析这段代码的性能瓶颈，给出优化方案"

# 5. 生成 iOS SwiftUI 代码（适配 Apple 生态开发）
anthropic code "用 SwiftUI 写一个待办事项 APP，包含添加/删除/标记完成功能，适配深色模式"

三、安装方式二：VS Code 插件集成（可视化使用，推荐）

通过 VS Code 插件实现可视化操作，支持右键生成/修复代码、侧边栏实时聊天，适配编程习惯。

3.1 安装 VS Code 插件

1. 打开 VS Code（官网下载：https://code.visualstudio.com/Download）；

2. 进入扩展商店（快捷键 Cmd + Shift + X）；

3. 搜索「Claude AI」（Anthropic 官方出品，认准蓝色官方图标）；

4. 点击「安装」，安装完成后重启 VS Code 生效。

3.2 配置插件 API Key

1. 打开 VS Code 设置（快捷键Cmd + ,）；

2. 在搜索框输入「Claude API Key」；

3. 在对应输入框粘贴你的 Claude API Key；

4. （可选）设置默认模型：搜索「Claude Model」，选择 claude-3-sonnet-20240229（推荐）。

3.3 插件核心功能使用

• 代码生成：右键编辑器空白处 → 选择「Claude: Generate Code」，输入编程需求；

• 代码修复：选中报错/待优化代码 → 右键 → 选择「Claude: Fix Code」或「Claude: Optimize Code」；

• 实时聊天编程：打开 VS Code 左侧边栏的「Claude」面板，直接输入需求对话；

• 文件分析：拖拽本地代码文件到 Claude 面板，输入「分析这个文件的功能和潜在问题」。

四、安装方式三：Homebrew 一键安装（仅 CLI，简化版）

若已安装 Homebrew，可通过官方源一键安装 Claude CLI，步骤更简洁：

# 1. 添加 Anthropic 官方 Homebrew 源
brew tap anthropic-ai/tap

# 2. 安装 Claude CLI
brew install claude-cli

# 3. 验证安装
claude --version

配置 API Key 方式与「方式一」一致，仅命令名从 anthropic 改为 claude，使用逻辑完全相同。

五、常见问题排查

问题现象	可能原因	解决方法
安装 pip 包时提示「Permission denied」权限错误	无全局安装权限	添加 --user 参数安装：pip3 install --user anthropic-cli
配置 API Key 后仍提示「未授权」	API Key 错误、过期，或账号无可用额度	1. 检查 API Key 是否完整（无空格/换行）；2. 登录 Anthropic 控制台确认账号有余额/免费额度；3. 重新创建并配置新的 API Key
VS Code 插件无响应，无法加载 Claude	网络无法访问 Anthropic 服务器，或插件未重启生效	1. 检查网络环境（需可访问境外网络）；2. 重启 VS Code；3. 卸载并重新安装插件
Apple Silicon 机型安装 Homebrew 后提示命令未识别	安装了 Intel 版本 Homebrew，与芯片不兼容	1. 卸载旧版 Homebrew：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"2. 重新安装 ARM 版本 Homebrew：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
CLI 执行命令时提示「模型不存在」	模型名称错误，或版本号不匹配	使用官方支持的模型名称，推荐：claude-3-sonnet-20240229（代码生成首选）claude-3-opus-20240229（复杂任务）

六、Apple Silicon 机型专属优化（可选）

针对 M1/M2/M3 芯片机型，优化安装配置以提升性能：

# 1. 确认 Homebrew 是 ARM 版本（输出 /opt/homebrew 即正确）
brew --prefix

# 2. 重新安装适配 ARM 的 Python
brew reinstall python3

# 3. 配置 pip 优先安装 ARM 版本包
echo 'export PIP_NO_BINARY=:all:' >> ~/.zshrc
source ~/.zshrc

# 4. 重新安装 Claude CLI
pip3 install --user anthropic-cli

七、总结

• 核心推荐：「CLI 命令行 + VS Code 插件」组合，兼顾终端高效操作与可视化编程；

• 关键步骤：安装依赖 → 配置 API Key → 验证使用，API Key 是核心（需确保有效且未泄露）；

• 适配要点：Intel/Apple Silicon 机型均支持，Apple 芯片需确保 Homebrew 为 ARM 版本；

• 网络要求：需可访问 Anthropic 服务器，否则无法调用 Claude 服务。