Claude Code macOS 安装与配置指南

Claude Code macOS 安装指南

前置要求

• macOS 10.15 (Catalina) 或更高版本
• Node.js 环境（版本 18 或更高）
• 有效的 API 密钥

安装步骤

1. 安装 Node.js 环境

Claude Code 需要 Node.js 环境才能运行。

方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，使用它安装 Node.js 会更方便：

# 更新 Homebrew
brew update
# 安装 Node.js
brew install node

如果尚未安装 Homebrew：

访问 https://brew.sh/ 或在终端运行以下命令安装：

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

方法二：官网下载

1. 访问 https://nodejs.org/
2. 点击 "LTS" 版本进行下载（推荐长期支持版本）
3. 下载完成后打开 .pkg 文件
4. 按照安装向导完成安装，保持默认设置即可

验证 Node.js 安装

安装完成后，打开终端（Terminal 或 iTerm2），输入以下命令：

node --version
npm --version

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

macOS 注意事项：

• 如果遇到权限问题，可能需要使用 sudo 命令
• 首次运行某些命令时，系统可能会提示安全设置
• 推荐使用 Terminal 或 iTerm2 作为终端工具

2. 安装 Claude Code

打开终端，运行以下命令：

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

如果遇到权限问题，可以使用 sudo：

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

这个命令会从 npm 官方仓库下载并安装最新版本的 Claude Code。

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

如果显示版本号，恭喜你！Claude Code 已经成功安装了。

提示：

• 如果提示找不到命令，尝试重新打开终端窗口
• 某些情况下可能需要重新加载 shell 配置文件

3. 获取 API 密钥

注册相应的 AI 服务账号，并在控制台创建新的 API 密钥。

登录控制台，在 API 密钥页面创建一个新的密钥。

4. 设置环境变量

为了让 Claude Code 连接到服务，需要设置环境变量。

确定你使用的 Shell

macOS Catalina (10.15) 及更高版本默认使用 zsh，而较早版本使用 bash。

检查当前 shell：

echo $SHELL

• 如果显示 /bin/zsh，使用 zsh 配置方法
• 如果显示 /bin/bash，使用 bash 配置方法

方法一：临时设置（当前会话）

在终端中运行以下命令：

export ANTHROPIC_API_KEY="你的 API 密钥"

注意：这种方式只在当前终端会话有效，关闭终端后需要重新设置。

方法二：永久设置（推荐）

对于 zsh（macOS Catalina 及更高版本）：

# 编辑 .zshrc 文件
echo 'export ANTHROPIC_API_KEY="你的 API 密钥"' >> ~/.zshrc
# 重新加载配置
source ~/.zshrc

对于 bash（较早版本 macOS）：

# 编辑 .bash_profile 文件
echo 'export ANTHROPIC_API_KEY="你的 API 密钥"' >> ~/.bash_profile
# 重新加载配置
source ~/.bash_profile

方法三：手动编辑配置文件

你也可以使用文本编辑器手动编辑配置文件：

对于 zsh：

# 使用 nano 编辑器
nano ~/.zshrc
# 或使用 vim 编辑器
vim ~/.zshrc

对于 bash：

# 使用 nano 编辑器
nano ~/.bash_profile
# 或使用 vim 编辑器
vim ~/.bash_profile

在文件末尾添加以下内容：

export ANTHROPIC_API_KEY="你的 API 密钥"

保存文件后，重新加载配置：

# zsh
source ~/.zshrc
# bash
source ~/.bash_profile

验证环境变量设置

设置完环境变量后，可以通过以下命令验证是否设置成功：

echo $ANTHROPIC_API_KEY

预期输出示例：

sk-xxxxxxxxxxxxxxxxxx

如果输出为空，说明环境变量设置失败，请检查配置文件并重新加载。

5. 开始使用 Claude Code

现在你可以开始使用 Claude Code 了！

启动 Claude Code

claude

在特定项目中使用

# 进入你的项目目录
cd /path/to/your/project
# 启动 Claude Code
claude

macOS 常见问题解决

安装时提示 "permission denied" 错误

这通常是权限问题，尝试以下解决方法：

方法一：使用 sudo

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

方法二：配置 npm 使用用户目录

# 创建全局安装目录
mkdir ~/.npm-global
# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'
# 将路径添加到 shell 配置文件
# zsh
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# bash
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profile

macOS 安全设置阻止运行

如果系统提示 "无法打开，因为无法验证开发者"：

1. 打开 系统偏好设置 → 安全性与隐私
2. 在 通用 标签下，点击 仍要打开 或 允许
3. 或者在终端中运行：

# 临时允许所有来源（不推荐）
sudo spctl --master-disable
# 使用完后建议恢复
sudo spctl --master-enable

环境变量设置后不生效

检查以下几点：

1. 确认修改了正确的配置文件
   • macOS Catalina+ 使用 ~/.zshrc
   • 早期版本使用 ~/.bash_profile
2. 重新加载配置文件

# zsh
source ~/.zshrc
# bash
source ~/.bash_profile

3. 完全重启终端
   • 关闭所有终端窗口
   • 重新打开一个新的终端窗口
4. 验证设置

echo $ANTHROPIC_API_KEY

Homebrew 安装缓慢或失败

如果 Homebrew 安装很慢，可以尝试更换镜像源。

Apple Silicon (M1/M2/M3) 芯片注意事项

如果你使用的是搭载 Apple Silicon 的 Mac：

• Node.js 和 Claude Code 都已完全支持 Apple Silicon
• 如果遇到兼容性问题，可以尝试使用 Rosetta 2
• 某些第三方包可能需要额外配置