Claude Code安装完全指南(Mac版):Git,环境变量,PATH与常见报错一次讲清实践整理

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Claude Code安装完全指南(Mac版):Git,环境变量,PAT……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际使用顺序，把思路、关键写法和容易踩坑的地方讲清楚，方便你直接对照操作。

在这个场景下，很多 “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 真正依赖什么。

可以把它理解成一条链：

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

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

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

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

执行：

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。

echo $SHELL

常用输出：

• /bin/zsh
• /bin/bash

如果你是 zsh，重点关注：

• ~/.zshrc
• ~/.zprofile

如果你是 bash，重点关注：

• ~/.bashrc
• ~/.bash_profile

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

四、安装 Homebrew

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

先检查系统里有没有：

brew --version

若提示 command not found，就安装它：

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

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

Apple Silicon 常用写法

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

Intel Mac 常用写法

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

然后验证：

which brew
brew --version

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

五、安装 Git

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

先检查：

git --version

如果没有，就安装：

brew install git

装完后验证：

which git
git --version

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

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

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

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

顺手设置 Git 身份

git config --global user.name "你的名字"
git config --global user.email "[email protected]"

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

cd ~/Projects/my-project
git init

六、安装 Node.js 和 npm

实际处理时，Claude Code 常用安装方式依赖 npm，所以 Node.js 和 npm 要先正常。

先检查：

node --version
npm --version

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

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

brew install node

然后再检查：

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

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

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

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

然后在当前 shell 加载：

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

安装 LTS 版本：

nvm install --lts
nvm use --lts

再验证：

node --version
npm --version

Homebrew 和 nvm 选哪个

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

• 想轻松稳定：Homebrew
• 想长期做 Node 开发并管理多个版本：nvm

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

七、正式安装 Claude Code

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

先检查系统里有没有：

which claude
claude --version

如果没有，再执行安装：

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

安装完成后再次验证：

which claude
claude --version

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

2.1.76 (Claude Code)

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

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

你明明执行了：

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

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

claude --version

却得到：

zsh: command not found: claude

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

第一步：先看 npm 全局前缀

npm config get prefix

它可能得到：

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

接着检查它的 bin 目录：

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

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

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

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

然后再次验证：

which claude
claude --version

理解这一步时，若你用的是 bash，就把上面的设置写进 ~/.bashrc 或 ~/.bash_profile。

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

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

比如你可能需：

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• OPENAI_BASE_URL

示例：

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

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

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

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

然后检查：

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL

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

常用原因：

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

轻松理解：

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

结合项目来看，对于大多数日常终端采用，把环境变量写进 ~/.zshrc 更直观。

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

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

建议执行：

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 环境正常加载
• 当前目录适合真正开始写代码

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

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

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

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

claude --help

若你的版本兼容非交互或普通 prompt，也建议先让它做这些小事：

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

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

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

command not found: claude

原因：

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

处理：

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

git: command not found

原因：

• Git 没装
• Xcode Command Line Tools 没配好

处理：

brew install git

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

node: command not found

原因：

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

处理：

which node
node --version

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

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

原因：

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

处理：

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

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

原因：

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

处理：

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

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

你可能需代理环境变量：

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

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

npm config get proxy
npm config get https-proxy

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

不要一上来就乱用：

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

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

常用问题解答

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，真正难的从来不是那条安装命令，而是后面的环境完整性。

只要你按这个顺序排：

1. 终端
2. Homebrew
3. Git
4. Node/npm
5. Claude Code
6. PATH
7. 环境变量
8. Git 仓库验证

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

结合项目来看，总的来说，Claude这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。