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 关键准备工作
- 安装 Homebrew（推荐，简化依赖安装）
打开「终端」（访达 → 应用程序 → 实用工具 → 终端），执行以下命令：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装过程中按提示输入电脑密码，等待完成即可。无 Homebrew 可跳过，后续采用手动安装方式。 - 获取 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 # 若终端是 bashecho'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：临时配置（终端关闭后失效）exportANTHROPIC_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_KEY2.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 插件
- 打开 VS Code（官网下载：https://code.visualstudio.com/Download）；
- 进入扩展商店（快捷键
Cmd + Shift + X）； - 搜索「Claude AI」（Anthropic 官方出品，认准蓝色官方图标）；
- 点击「安装」，安装完成后重启 VS Code 生效。
3.2 配置插件 API Key
- 打开 VS Code 设置（快捷键
Cmd + ,）； - 在搜索框输入「Claude API Key」；
- 在对应输入框粘贴你的 Claude API Key；
- （可选）设置默认模型：搜索「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 服务。
