Claude Code 安装完全指南（Mac 版）：Git、环境变量、PATH 与常见报错一次讲清（2026）

很多 "Claude Code 安装教程" 最大的问题，不是写错了，而是写得太快。

通常只告诉你一条安装命令，最多再补一句 "配置一下 API Key"，然后就结束了。但新手真正踩坑，往往发生在安装之后：

Claude Code 显示安装成功，但终端里找不到 claude
Claude Code 能启动，但发现机器上没有 Git
Git 装好了，当前目录却不是 Git 仓库
环境变量配了，但换个终端窗口就失效
Apple Silicon 和 Intel Mac 的路径不一样
Homebrew 装好了，但 zsh 没正确加载
npm 全局安装成功，但 PATH 没更新

如果你是第一次从零配置 Claude Code，最容易失败的不是安装命令本身，而是整个环境链条没有打通。

这篇文章就专门讲这个链条，而且尽量讲全。

一、在 Mac 上安装 Claude Code，到底需要哪些东西？

先不要急着安装。你要先知道 Claude Code 真正依赖什么。

组件	为什么需要
终端	Claude Code 是命令行工具
Git	绝大多数代码工作流都离不开 Git
Node.js / npm	Claude Code 通常通过 npm 全局安装
Shell 配置	PATH 和环境变量都在这里生效
网络环境	安装包下载、登录、模型调用都依赖网络
认证信息	没有账号登录或相关密钥，CLI 很多功能跑不起来

可以把它理解成一条链：

终端 -> Homebrew -> Git -> Node/npm -> Claude Code -> PATH -> 环境变量 -> 项目验证

只要中间任何一个环节断掉，你就会感觉 "明明装了，但就是不能用"。

二、先确认你的 Mac 环境：Apple Silicon 还是 Intel？

虽然大部分步骤一致，但 Homebrew 路径常常不同。

执行：

bash 复制代码

uname -m

结果一般是：

arm64：Apple Silicon（M1/M2/M3/M4）
x86_64：Intel Mac

这件事很重要，因为：

Apple Silicon 上 Homebrew 常见路径是 /opt/homebrew
Intel 上 Homebrew 常见路径是 /usr/local

后面 PATH、brew shellenv、命令位置排查，都可能受这个影响。

三、先确认你当前使用的 Shell

macOS 新版本默认基本都是 zsh。

bash 复制代码

echo $SHELL

常见输出：

/bin/zsh
/bin/bash

如果你是 zsh，重点关注：

~/.zshrc
~/.zprofile

如果你是 bash，重点关注：

~/.bashrc
~/.bash_profile

对于大多数 Mac 新手来说，后续最常编辑的是 ~/.zshrc。

四、安装 Homebrew

在 macOS 上，最省心的开发环境安装方式，基本就是 Homebrew。

先检查系统里有没有：

bash 复制代码

brew --version

如果提示 command not found，就安装它：

bash 复制代码

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

安装完成后，Homebrew 往往会提示你把它加入 shell 环境。

Apple Silicon 常见写法

bash 复制代码

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac 常见写法

bash 复制代码

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

然后验证：

bash 复制代码

which brew
brew --version

如果 which brew 能返回正确路径，说明这一步通了。

五、安装 Git

很多人会先装 Claude Code，后面才发现 Git 没装，这样很容易在真正开始用时出问题。

先检查：

bash 复制代码

git --version

如果没有，就安装：

bash 复制代码

brew install git

装完后验证：

bash 复制代码

which git
git --version

为什么 Claude Code 用户最好先装 Git？

因为你后续的很多正常工作都离不开 Git：

查看改动
回滚修改
管理分支
审核 patch
管理项目历史

哪怕 Claude Code 能在没有 Git 的情况下装上，也不代表这个环境适合真正拿来开发。

顺手配置 Git 身份

bash 复制代码

git config --global user.name "你的名字"
git config --global user.email "you@example.com"

如果你是新建项目目录，还建议先初始化一下：

bash 复制代码

cd ~/Projects/my-project
git init

六、安装 Node.js 和 npm

Claude Code 常见安装方式依赖 npm，所以 Node.js 和 npm 要先正常。

先检查：

bash 复制代码

node --version
npm --version

如果命令不存在，说明还没装好。

最适合新手的方案：Homebrew 安装 Node

bash 复制代码

brew install node

然后再检查：

bash 复制代码

node --version
npm --version
which node
which npm

进阶方案：用 nvm 管理 Node 版本

如果你经常切换多个 Node 版本，可以装 nvm。

bash 复制代码

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

然后在当前 shell 加载：

bash 复制代码

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

安装 LTS 版本：

bash 复制代码

nvm install --lts
nvm use --lts

再验证：

bash 复制代码

node --version
npm --version

Homebrew 和 nvm 选哪个？

如果你是第一次配置开发环境：

想简单稳定：Homebrew
想长期做 Node 开发并管理多个版本：nvm

对新手来说，Homebrew 更容易排错。

七、正式安装 Claude Code

把前面的基础环境搞定后，再装 Claude Code。

先检查系统里有没有：

bash 复制代码

which claude
claude --version

如果没有，再执行安装：

bash 复制代码

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

安装完成后再次验证：

bash 复制代码

which claude
claude --version

正常情况下，你会看到类似：

bash 复制代码

2.1.76 (Claude Code)

八、如果安装成功但 `claude` 还是找不到，怎么修？

这是 Mac 上最常见的问题之一。

你明明执行了：

bash 复制代码

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

终端也没报错，但再输入：

bash 复制代码

claude --version

却得到：

bash 复制代码

zsh: command not found: claude

这通常说明：npm 全局安装目录不在 PATH 里。

第一步：先看 npm 全局前缀

bash 复制代码

npm config get prefix

它可能返回：

/opt/homebrew
/usr/local
/Users/你的用户名/.npm-global

接着检查它的 bin 目录：

bash 复制代码

ls "$(npm config get prefix)/bin"

如果里面能看到 claude，那就说明程序已经装上了，只是当前 shell 找不到。

第二步：把 npm 全局 bin 加入 PATH

bash 复制代码

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

然后再次验证：

bash 复制代码

which claude
claude --version

如果你用的是 bash，就把上面的配置写进 ~/.bashrc 或 ~/.bash_profile。

九、环境变量怎么配，为什么很多人配了却不生效？

很多新手最容易出错的，不是安装命令，而是环境变量。

比如你可能需要：

ANTHROPIC_API_KEY
OPENAI_API_KEY
OPENAI_BASE_URL

示例：

bash 复制代码

export ANTHROPIC_API_KEY="your_key_here"
export OPENAI_API_KEY="your_crazyrouter_key"
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

如果你只是这样直接执行，这些变量通常只在当前终端窗口有效。你关掉窗口，它们就没了。

正确做法：写入 shell 配置文件

bash 复制代码

echo 'export ANTHROPIC_API_KEY="your_key_here"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="your_crazyrouter_key"' >> ~/.zshrc
echo 'export OPENAI_BASE_URL="https://crazyrouter.com/v1"' >> ~/.zshrc
source ~/.zshrc

然后检查：

bash 复制代码

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL

为什么有时当前窗口能看到，开新窗口又没了？

常见原因：

你只是 export 到当前会话，没有写入配置文件
你写进了 ~/.zprofile，但当前终端只加载 ~/.zshrc
你用的是 iTerm2 / Terminal，不同启动方式加载文件略有差异

简单理解：

~/.zprofile 更偏登录时加载
~/.zshrc 更偏交互 shell 加载

对于大多数日常终端使用，把环境变量写进 ~/.zshrc 更直观。

十、如何检查是不是"真的装好了"？

不要只看 npm install 成不成功，而要完整检查整条链。

建议执行：

bash 复制代码

which brew || true
brew --version || true

git --version || true
node --version || true
npm --version || true
claude --version || true

echo $SHELL
pwd
git status || true

你要确认的是：

Homebrew 正常
Git 正常
Node 正常
npm 正常
Claude Code 正常
Shell 环境正常加载
当前目录适合真正开始写代码

十一、第一次测试，不要直接上高风险命令

可以先新建一个测试目录：

bash 复制代码

mkdir -p ~/Projects/claude-code-test
cd ~/Projects/claude-code-test
git init
printf "# test\n" > README.md

然后先做低风险测试，比如：

bash 复制代码

claude --help

如果你的版本支持非交互或普通 prompt，也建议先让它做这些小事：

解释当前目录结构
帮你补一个 .gitignore
改写一下 README
给出项目初始化建议

不要一开始就让它执行高权限或高风险修改。

十二、Mac 上最常见的 7 类问题和修复方法

1）`command not found: claude`

原因：

npm 全局 bin 不在 PATH
安装成功但 shell 没刷新
程序装到了你当前 shell 读不到的位置

处理：

bash 复制代码

npm config get prefix
ls "$(npm config get prefix)/bin"
export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.zshrc
which claude

2）`git: command not found`

原因：

Git 没装
Xcode Command Line Tools 没配好

处理：

bash 复制代码

brew install git

如果系统弹出安装开发者工具的提示，也按流程装完再试。

3）`node: command not found`

原因：

Node 没装
nvm 没被 shell 正确加载
老版本 Node 冲突

处理：

bash 复制代码

which node
node --version

如果你是用 nvm，重点检查 ~/.zshrc 里有没有正确加载 nvm.sh。

4）Homebrew 在一个终端能用，在另一个终端不能用

原因：

Homebrew 初始化写进了不合适的 profile 文件
不同终端窗口加载文件顺序不同

处理：

把 brew shellenv 配到 ~/.zprofile
PATH 和环境变量主要放 ~/.zshrc
完整关闭终端后重新打开

5）环境变量只在当前标签页有效

原因：

只是临时 export
没写入 ~/.zshrc

处理：

写进配置文件
执行 source ~/.zshrc
再开一个新标签页做验证

6）公司网络、代理、校园网导致安装失败

你可能需要代理环境变量：

bash 复制代码

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

如果 npm 安装异常，也可以检查：

bash 复制代码

npm config get proxy
npm config get https-proxy

7）全局 npm 安装时提示权限不足

不要一上来就乱用：

bash 复制代码

sudo npm install -g ...

更稳妥的做法是：

用 Homebrew 安装 Node
或用 nvm 管理 Node
保证 npm 全局目录归当前用户所有

这样后面可维护性会好很多。

十三、给新手的最稳妥 Mac 方案

如果你只想要一个最容易成功、最容易排查的配置，我建议这样：

Terminal.app 或 iTerm2
zsh
Homebrew
Git via Homebrew
Node via Homebrew
Claude Code via npm global install
环境变量写入 ~/.zshrc

这套不是最炫的，但最容易稳定用起来。

FAQ

Q1：在 Mac 上安装 Claude Code，一定要先装 Git 吗？

严格来说，安装命令本身不一定依赖 Git。但从实际使用看，绝大多数 Claude Code 场景都强烈建议先把 Git 配好。

Q2：Apple Silicon 的 Mac 能正常用 Claude Code 吗？

可以，主要区别只是 Homebrew 路径通常变成 /opt/homebrew，所以 PATH 排查要注意。

Q3：Homebrew 和 nvm 应该选哪个？

新手优先 Homebrew，后续如果你开始管理多个 Node 版本，再切到 nvm 也不迟。

Q4：为什么明明安装成功了，zsh 里还是找不到 `claude`？

通常不是 Claude Code 本身坏了，而是 npm 全局可执行目录没有进 PATH，或者 shell 配置没有重新加载。

Q5：我能不能不用直连 Anthropic，而是走统一 API 网关？

可以，前提是你的 CLI 工作流支持相应的 provider 或兼容配置。这样做的好处是多个模型可以共用一套入口和账单。

结语

Mac 上配置 Claude Code，真正难的从来不是那条安装命令，而是后面的环境完整性。

只要你按这个顺序排：

终端
Homebrew
Git
Node/npm
Claude Code
PATH
环境变量
Git 仓库验证

大多数新手安装问题都能更快定位，也更容易一次配好。

Claude Code 安装完全指南（Mac 版）：Git、环境变量、PATH 与常见报错一次讲清（2026）