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

目录

• 一、在 Mac 上安装 Claude Code，到底需要哪些东西？
• 二、先确认你的 Mac 环境：Apple Silicon 还是 Intel？
• 三、先确认你当前使用的 Shell
• 四、安装 Homebrew
• Apple Silicon 常见写法
• Intel Mac 常见写法
• 五、安装 Git
• 六、安装 Node.js 和 npm
• 最适合新手的方案：Homebrew 安装 Node
• 进阶方案：用 nvm 管理 Node 版本
• Homebrew 和 nvm 选哪个
• 七、正式安装 Claude Code
• 八、如果安装成功但claude还是找不到，怎么修？
• 九、环境变量怎么配，为什么很多人配了却不生效？
• 十、如何检查是不是“真的装好了”？
• 十一、第一次测试，不要直接上高风险命令
• 十二、Mac 上最常见的 7 类问题和修复方法
• command not found: claude
• git: command not found
• node: command not found
• Homebrew 在一个终端能用，在另一个终端不能用
• 环境变量只在当前标签页有效
• 公司网络、代理、校园网导致安装失败
• 全局 npm 安装时提示权限不足
• 十三、给新手的最稳妥 Mac 方案
• 常见问题解答
• 结语

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

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

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

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

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

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

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

可以把它理解成一条链：

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

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

虽然大部分步骤一致，但 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、命令位置排查，都可能受这个影响。

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

echo $SHELL

常见输出：

• /bin/zsh
• /bin/bash

如果你是 zsh，重点关注：

• ~/.zshrc
• ~/.zprofile

如果你是 bash，重点关注：

• ~/.bashrc
• ~/.bash_profile

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

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

先检查系统里有没有：

brew --version

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

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

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

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

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

然后验证：

which brew
brew --version

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

很多人会先装 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 "you@example.com"

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

cd ~/Projects/my-project
git init

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

先检查：

node --version
npm --version

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

brew install node

然后再检查：

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

如果你经常切换多个 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
• 想长期做 Node 开发并管理多个版本：nvm

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

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

先检查系统里有没有：

which claude
claude --version

如果没有，再执行安装：

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

安装完成后再次验证：

which claude
claude --version

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

2.1.76 (Claude Code)

这是 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
• 给出项目初始化建议

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

原因：

• 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 没装
• Xcode Command Line Tools 没配好

处理：

brew install git

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

原因：

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

处理：

which node
node --version

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

原因：

• 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

不要一上来就乱用：

sudo npm install -g ...

更稳妥的做法是：

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

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

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

• 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 Code安装完全指南(Mac版):Git,环境变量,PATH与常见报错一次讲清的详细内容，更多关于Claude Code安装教学的资料请关注风君子博客其它相关文章！