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

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

很多 “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 路径常常不同。

执行：

GPT plus 代充 只需 145uname -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。

先检查系统里有没有：

GPT plus 代充 只需 145brew --version

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

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

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

Apple Silicon 常见写法

GPT plus 代充 只需 145echo '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)"

然后验证：

GPT plus 代充 只需 145which brew brew --version

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

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

先检查：

git --version

如果没有，就安装：

GPT plus 代充 只需 145brew install git

装完后验证：

which git git --version

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

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

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

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

顺手配置 Git 身份

GPT plus 代充 只需 145git config --global user.name "你的名字" git config --global user.email ""

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

cd ~/Projects/my-project git init

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

先检查：

GPT plus 代充 只需 145node --version npm --version

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

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

brew install node

然后再检查：

GPT plus 代充 只需 145node --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 加载：

GPT plus 代充 只需 145export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

安装 LTS 版本：

nvm install --lts nvm use --lts

再验证：

GPT plus 代充 只需 145node --version npm --version

Homebrew 和 nvm 选哪个？

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

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

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

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

先检查系统里有没有：

which claude claude --version

如果没有，再执行安装：

GPT plus 代充 只需 145npm install -g @anthropic-ai/claude-code

安装完成后再次验证：

which claude claude --version

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

GPT plus 代充 只需 1452.1.76 (Claude Code)

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

你明明执行了：

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

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

GPT plus 代充 只需 145claude --version

却得到：

zsh: command not found: claude

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

第一步：先看 npm 全局前缀

GPT plus 代充 只需 145npm config get prefix

它可能返回：

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

接着检查它的 bin 目录：

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

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

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

GPT plus 代充 只需 145echo '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

示例：

GPT plus 代充 只需 145export 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

然后检查：

GPT plus 代充 只需 145echo $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 环境正常加载
当前目录适合真正开始写代码

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

GPT plus 代充 只需 145mkdir -p ~/Projects/claude-code-test cd ~/Projects/claude-code-test git init printf "# test " > README.md

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

claude --help

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

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

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

1）`command not found: claude`

原因：

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

处理：

GPT plus 代充 只需 145npm 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 没配好

处理：

brew install git

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

3）`node: command not found`

原因：

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

处理：

GPT plus 代充 只需 145which node node –version

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

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

原因：

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

处理：

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

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

原因：

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

处理：

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

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

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

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

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

GPT plus 代充 只需 145npm config get proxy npm config get https-proxy

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

不要一上来就乱用：

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

只要你按这个顺序排：

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

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