🍎 Mac 部署 Claude Code CLI 完整教程

🍎 Mac 部署 Claude Code CLI 完整教程

版本: 2.1.x | 更新日期: 2026年6月 | 适用平台: macOS 13.0+ (Ventura 及以上)

---

📑 目录

• Claude Code 简介
• 系统要求
• 订阅方案
• 安装方法（三种方式）
  • 4.1 方法一：原生安装脚本（推荐）
  • 4.2 方法二：Homebrew 安装
  • 4.3 方法三：npm 安装（已弃用但可用）
    
• 身份认证
• 验证安装
• 首次使用
• 常用命令速查
• 常见问题排查
• 卸载方法
• 附：与 Windows 环境的差异对照
  

---

1. Claude Code 简介

Claude Code 是 Anthropic 推出的终端 AI 编程助手，它能够：

• 🤖 理解整个代码库，回答代码相关的问题
• ✏️ 直接编辑文件，执行重构、修复 bug
• 🔄 管理 Git 工作流，创建 PR、解决冲突
• 🧪 运行测试并诊断失败原因
• 📦 集成 MCP 协议，扩展能力边界
  

Claude Code 通过 npm 包 @anthropic-ai/claude-code 分发，当前稳定版本为 2.1.x。

---

2. 系统要求

硬件要求

项目

最低配置

推荐配置

操作系统macOS 13.0 (Ventura)macOS 14+ (Sonoma/Sequoia)

处理器

Intel 或 Apple Silicon (M1)

Apple Silicon (M2/M3/M4)

内存

4 GB

8 GB+

磁盘空间

200 MB

500 MB

网络

需连接 Anthropic API

稳定宽带连接

软件要求

软件

最低版本

推荐版本

Git2.30+2.44+

Node.js（仅 npm 方式需要）

18.x

22.x LTS

npm（仅 npm 方式需要）

9+

10+

Shell

Zsh 或 Bash

Zsh (macOS 默认)

💡 GPU 非必需 — 所有计算在 Anthropic 服务器端运行。

---

3. 订阅方案

Claude Code 需要有效订阅才能使用。目前支持的方案：

方案

月费

适用场景

Claude Pro$20/月个人开发者，日常使用

Claude Max

$200/月

重度用户，更高额度

Claude Team

联系销售

团队协作

Claude Enterprise

联系销售

企业级部署

Console API

按量付费

CI/CD 流水线、无头环境

🔗 注册地址：https://claude.ai

---

4. 安装方法（三种方式）

4.1 方法一：原生安装脚本（✅ 强烈推荐）

这是 2026 年官方推荐的安装方式，无需预先安装 Node.js，安装速度快（约 30 秒），自动处理依赖。

步骤 1：执行安装脚本

打开终端（Terminal.app），运行：

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

步骤 2：重启终端

安装完成后，关闭并重新打开终端窗口，或运行：

source ~/.zshrc

步骤 3：验证版本

claude --version

预期输出类似：2.1.165 (Claude Code)

---

4.2 方法二：Homebrew 安装

适合已经使用 Homebrew 管理软件的 Mac 用户，便于后续升级管理。

步骤 1：安装 Homebrew（如未安装）

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

步骤 2：添加 Anthropic Tap 并安装

brew install anthropic/tap/claude

步骤 3：验证安装

claude --version

步骤 4：后续升级

brew upgrade claude

---

4.3 方法三：npm 安装（⚠️ 已弃用但可用）

官方已弃用此方法，但仍可正常工作。适合已安装 Node.js 环境的用户，与你当前的 Windows 环境一致。

步骤 1：检查 Node.js 环境

node -v    # 需要 18+npm -v     # 需要 9+

如果未安装 Node.js，推荐使用 nvm 安装：

# 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash# 重启终端后安装 Node.js 22 LTSnvm install 22nvm use 22

步骤 2：全局安装 Claude Code

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

⚠️ 不要使用 sudo npm install，这会导致权限问题。如果遇到权限错误，请参考下面的修复方法。

修复 npm 权限问题（如遇到 EACCES 错误）：

# 配置 npm 使用用户目录mkdir ~/.npm-globalnpm config set prefix '~/.npm-global'# 添加到 PATHecho 'export PATH=~/.npm-global/binPATH' >> ~/.zshrcsource ~/.zshrc# 重新安装npm install -g @anthropic-ai/claude-code@^2.1

步骤 3：验证安装

claude --version

---

5. 身份认证

安装完成后，需要认证才能使用 Claude Code。

方式一：OAuth 浏览器登录（推荐）

在项目目录中直接运行 claude：

cd /path/to/your/projectclaude

终端会显示一条链接，同时自动打开浏览器窗口。在浏览器中登录你的 Claude 账户并授权即可。

🔐 认证令牌存储在 ~/.claude/ 目录中，有效期约 30 天，会自动续期。

方式二：API Key 认证（适合 CI/CD 或无头环境）

# 设置环境变量export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"# 启动 Claude Codeclaude

API Key 可在 Anthropic Console 获取。

方式三：其他认证方式

claude auth login                   # 标准浏览器 OAuthclaude auth login --email you@example.com  # 邮箱验证claude auth login --sso             # 企业 SSO 登录claude auth login --console         # API Key 计费模式

---

6. 验证安装

运行全面的健康检查：

claude doctor

该命令会检查：

• ✅ 安装完整性
• ✅ 认证状态
• ✅ 网络连接
• ✅ 系统权限
  

健康检查输出示例：

Claude Code version: 2.1.165 ✓Authentication: ✓ (logged in as user@example.com)Network connectivity: ✓System permissions: ✓

---

7. 首次使用

7.1 基本启动

cd /path/to/your/projectclaude7.2 常用指令示例

进入交互界面后，你可以直接使用自然语言：

# 代码审查"Review the auth logic in auth.js and suggest improvements"# 生成测试"Generate unit tests for the UserService class"# 代码理解"Explain how the payment processing pipeline works"# Git 操作"Create a PR for the current branch with a summary of changes"# Bug 修复"Find the bug causing the login redirect loop"7.3 命令行模式（非交互）

# 一次性提问claude -p "What does the main function do?"# 管道输入cat main.js | claude -p "Review this code for bugs"# 处理 Git diffgit diff | claude -p "Review these changes"

---

8. 常用命令速查

命令

用途

claude --version查看版本号

claude doctor

运行健康检查

claude auth login

登录认证

claude auth logout

登出

claude auth status

查看认证状态

claude -p "提问"

一次性提问

claude --help

查看帮助

claude config

查看/修改配置

---

9. 常见问题排查

❌ command not found: claude

原因：安装路径未加入 PATH 环境变量。

解决方法：

• 原生/Homebrew 安装：重启终端，或运行 source ~/.zshrc
• npm 安装：确认 npm 全局 bin 目录在 PATH 中echo 'export PATH=$(npm config get prefix)/binPATH' >> ~/.zshrcsource ~/.zshrc
  

❌ 认证时浏览器未自动打开

解决方法：手动复制终端中显示的 URL 到浏览器中打开。

❌ 权限错误（EACCES）

原因：使用了 sudo npm install 或 npm 全局目录权限不正确。

解决方法：配置 npm 使用用户目录（见 4.3 节的修复方法），然后重新安装。

❌ 公司代理/防火墙导致无法连接

解决方法：

# 设置 HTTP 代理export HTTP_PROXY=http://your-proxy:portexport HTTPS_PROXY=http://your-proxy:port# 确保 claude.ai 和 api.anthropic.com 在允许列表中❌ 订阅过期

解决方法：登录 claude.ai 续费订阅，然后重新认证。

❌ 认证令牌过期

解决方法：重新运行 claude auth login 或设置 API Key。

---

10. 卸载方法

原生安装的卸载

# 查找安装路径which claude# 删除可执行文件和配置rm -f $(which claude)rm -rf ~/.claudeHomebrew 卸载

brew uninstall claudebrew untap anthropic/tapnpm 卸载

npm uninstall -g @anthropic-ai/claude-code清理配置文件（可选）

rm -rf ~/.claude        # 认证令牌和配置rm -rf ~/.claude.json   # 旧版配置文件（如有）

---

11. 附：与 Windows 环境的差异对照

项目

Windows（你的当前环境）

Mac（目标环境）

安装方式npm 全局安装推荐原生脚本或 Homebrew

安装路径

E:\AI\ClaudeCode

/usr/local/bin/claude 或 ~/.npm-global/bin/claude

版本

@anthropic-ai/claude-code@2.1.165

同样为 2.1.x

Shell

Git Bash (Unix 风格)

Zsh (默认) 或 Bash

配置目录

%USERPROFILE%\.claude\

~/.claude/

环境变量

set ANTHROPIC_API_KEY=xxx

export ANTHROPIC_API_KEY=xxx

Node.js 需求

必需（npm 安装）

非必需（推荐原生安装）

---

📚 参考来源

• Claude Code 官方 GitHub 仓库
• Anthropic 帮助中心 — 第一天使用 Claude Code
• Claude Code 官方文档 — 概览
• Claude Code 官方文档 — 安装指南
• Anthropic Console — API Key 管理
  

---

提示：如在部署过程中遇到任何问题，欢迎随时咨询。本教程基于 2026 年 6 月的最新信息编写，官方文档可能随时更新，建议定期检查版本更新。