Claude Code macOS 安装完整指南：Homebrew、原生脚本与常见问题解决

Claude Code macOS 完整安装教程：原生 curl 脚本、Homebrew cask 两种方式，PATH 配置、OAuth 登录、Xcode 依赖、M1/M2/M3 芯片兼容性、dyld 报错修复，以及 VS Code 和 iTerm2 集成配置。

2026/3/153分钟阅读ClaudeEagle

macOS 是 Claude Code 体验最好的平台，Terminal.app、iTerm2 都完美支持。本文覆盖从安装到第一次运行的全流程，包含 Apple Silicon（M 系列）的注意事项。

前提要求

macOS 12 Monterey 及以上
有 claude.com 账号（免费或订阅）
终端 app（Terminal、iTerm2 均可）

方式一：原生脚本安装（推荐）

bash 复制代码

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

安装后重新加载 shell 配置：

bash 复制代码

source ~/.zshrc  # 大多数 macOS 用 zsh
# 或
source ~/.bash_profile  # 如果你用 bash

验证安装：

bash 复制代码

claude --version
which claude  # 应该显示 /Users/你的用户名/.local/bin/claude

优点：自动后台更新，始终保持最新版本。

方式二：Homebrew 安装

如果你已经用 Homebrew 管理工具链：

bash 复制代码

brew install --cask claude-code

升级：

bash 复制代码

brew upgrade claude-code

注意：Homebrew 安装不自动更新，需要手动运行升级命令。建议把 brew upgrade claude-code 加入定期维护习惯。

第一次使用

bash 复制代码

# 进入你的项目目录
cd ~/projects/your-project

# 启动
claude

Apple Silicon（M1/M2/M3）特别说明

Claude Code 原生支持 Apple Silicon，不需要 Rosetta。

如果遇到 dyld 相关错误：

bash 复制代码

# 方法 1：移除隔离属性
xattr -d com.apple.quarantine $(which claude)

# 方法 2：在「系统设置 -> 隐私与安全」里点击「仍要打开」

# 方法 3：重新安装（通常能解决大多数问题）
curl -fsSL https://claude.ai/install.sh | bash

PATH 问题排查

如果安装后 `command not found: claude`：

bash 复制代码

# 检查安装位置
ls -la ~/.local/bin/claude

# 检查 PATH
echo $PATH | tr ':' '\n' | grep local

# 手动添加到 zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Xcode Command Line Tools

部分功能依赖 Git，确保已安装：

bash 复制代码

xcode-select --install
# 或检查是否已安装
git --version

VS Code 集成

bash 复制代码

# 安装 Claude Code 扩展
code --install-extension anthropic.claude-code

# 或在 VS Code 里 Cmd+Shift+X 搜索 "Claude Code"

安装后在 VS Code 的内置终端里运行 claude，侧边栏会出现 Claude Code 面板。

iTerm2 推荐配置

Claude Code 在 iTerm2 里体验最佳，推荐开启：

自然文本编辑：Preferences -> Profiles -> Keys -> Presets -> Natural Text Editing
字体：Cascadia Code 或 JetBrains Mono（等宽字体，代码显示更清晰）
主题：One Dark 或 Dracula（深色背景减少眼睛疲劳）

更新和卸载

bash 复制代码

# 手动更新（原生安装自动更新，Homebrew 需要手动）
brew upgrade claude-code

# 卸载
# 原生安装
rm -rf ~/.local/bin/claude ~/.claude

# Homebrew
brew uninstall --cask claude-code

常见问题

Q：安装报 "Permission denied" 不要用 sudo，脚本安装到用户目录：~/.local/bin/，不需要 root 权限。

Q：每次打开终端都要重新登录 登录状态存储在 ~/.claude/auth.json，如果丢失需要重新 /login。检查这个文件是否存在。

Q：Claude Code 版本很旧，怎么强制更新

bash 复制代码

curl -fsSL https://claude.ai/install.sh | bash
# 原生安装会自动覆盖旧版本

Claude Code macOS 安装完整指南：Homebrew、原生脚本与常见问题解决