很多 “Claude Code 安裝教程” 最大的問題，不是寫錯了，而是寫得太快。

通常只告訴你一條安裝命令，最多再補(bǔ)一句 “配置一下 API Key”，然后就結(jié)束了。但新手真正踩坑，往往發(fā)生在安裝之后：

• Claude Code 顯示安裝成功，但終端里找不到 claude
• Claude Code 能啟動，但發(fā)現(xiàn)機(jī)器上沒有 Git
• Git 裝好了，當(dāng)前目錄卻不是 Git 倉庫
• 環(huán)境變量配了，但換個終端窗口就失效
• Apple Silicon 和 Intel Mac 的路徑不一樣
• Homebrew 裝好了，但 zsh 沒正確加載
• npm 全局安裝成功，但 PATH 沒更新

如果你是第一次從零配置 Claude Code，最容易失敗的不是安裝命令本身，而是整個環(huán)境鏈條沒有打通。

這篇文章就專門講這個鏈條，而且盡量講全。

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

先不要急著安裝。你要先知道 Claude Code 真正依賴什么。

可以把它理解成一條鏈：

終端 -> Homebrew -> Git -> Node/npm -> Claude Code -> PATH -> 環(huán)境變量 -> 項目驗(yàn)證

只要中間任何一個環(huán)節(jié)斷掉，你就會感覺 “明明裝了，但就是不能用”。

二、先確認(rèn)你的 Mac 環(huán)境：Apple Silicon 還是 Intel？

雖然大部分步驟一致，但 Homebrew 路徑常常不同。

執(zhí)行：

uname -m

結(jié)果一般是：

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

這件事很重要，因?yàn)椋?/p>

• Apple Silicon 上 Homebrew 常見路徑是 /opt/homebrew
• Intel 上 Homebrew 常見路徑是 /usr/local

后面 PATH、brew shellenv、命令位置排查，都可能受這個影響。

三、先確認(rèn)你當(dāng)前使用的 Shell

macOS 新版本默認(rèn)基本都是 zsh。

echo $SHELL

常見輸出：

• /bin/zsh
• /bin/bash

如果你是 zsh，重點(diǎn)關(guān)注：

• ~/.zshrc
• ~/.zprofile

如果你是 bash，重點(diǎn)關(guān)注：

• ~/.bashrc
• ~/.bash_profile

對于大多數(shù) Mac 新手來說，后續(xù)最常編輯的是 ~/.zshrc。

四、安裝 Homebrew

在 macOS 上，最省心的開發(fā)環(huán)境安裝方式，基本就是 Homebrew。

先檢查系統(tǒng)里有沒有：

brew --version

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

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

安裝完成后，Homebrew 往往會提示你把它加入 shell 環(huán)境。

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)"

然后驗(yàn)證：

which brew
brew --version

如果 which brew 能返回正確路徑，說明這一步通了。

五、安裝 Git

很多人會先裝 Claude Code，后面才發(fā)現(xiàn) Git 沒裝，這樣很容易在真正開始用時出問題。

先檢查：

git --version

如果沒有，就安裝：

brew install git

裝完后驗(yàn)證：

which git
git --version

為什么 Claude Code 用戶最好先裝 Git？

因?yàn)槟愫罄m(xù)的很多正常工作都離不開 Git：

• 查看改動
• 回滾修改
• 管理分支
• 審核 patch
• 管理項目歷史

哪怕 Claude Code 能在沒有 Git 的情況下裝上，也不代表這個環(huán)境適合真正拿來開發(fā)。

順手配置 Git 身份

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

如果你是新建項目目錄，還建議先初始化一下：

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

進(jìn)階方案：用 nvm 管理 Node 版本

如果你經(jīng)常切換多個 Node 版本，可以裝 nvm。

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

然后在當(dāng)前 shell 加載：

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

安裝 LTS 版本：

nvm install --lts
nvm use --lts

再驗(yàn)證：

node --version
npm --version

Homebrew 和 nvm 選哪個

如果你是第一次配置開發(fā)環(huán)境：

• 想簡單穩(wěn)定：Homebrew
• 想長期做 Node 開發(fā)并管理多個版本：nvm

對新手來說，Homebrew 更容易排錯。

七、正式安裝 Claude Code

把前面的基礎(chǔ)環(huán)境搞定后，再裝 Claude Code。

先檢查系統(tǒng)里有沒有：

which claude
claude --version

如果沒有，再執(zhí)行安裝：

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

安裝完成后再次驗(yàn)證：

which claude
claude --version

正常情況下，你會看到類似：

2.1.76 (Claude Code)

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

這是 Mac 上最常見的問題之一。

你明明執(zhí)行了：

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，那就說明程序已經(jīng)裝上了，只是當(dāng)前 shell 找不到。

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

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

然后再次驗(yàn)證：

which claude
claude --version

如果你用的是 bash，就把上面的配置寫進(jìn) ~/.bashrc 或 ~/.bash_profile。

九、環(huán)境變量怎么配，為什么很多人配了卻不生效？

很多新手最容易出錯的，不是安裝命令，而是環(huán)境變量。

比如你可能需要：

• 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"

如果你只是這樣直接執(zhí)行，這些變量通常只在當(dāng)前終端窗口有效。你關(guān)掉窗口，它們就沒了。

正確做法：寫入 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

為什么有時當(dāng)前窗口能看到，開新窗口又沒了？

常見原因：

• 你只是 export 到當(dāng)前會話，沒有寫入配置文件
• 你寫進(jìn)了 ~/.zprofile，但當(dāng)前終端只加載 ~/.zshrc
• 你用的是 iTerm2 / Terminal，不同啟動方式加載文件略有差異

簡單理解：

• ~/.zprofile 更偏登錄時加載
• ~/.zshrc 更偏交互 shell 加載

對于大多數(shù)日常終端使用，把環(huán)境變量寫進(jìn) ~/.zshrc 更直觀。

十、如何檢查是不是“真的裝好了”？

不要只看 npm install 成不成功，而要完整檢查整條鏈。

建議執(zhí)行：

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

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

echo $SHELL
pwd
git status || true

你要確認(rèn)的是：

• Homebrew 正常
• Git 正常
• Node 正常
• npm 正常
• Claude Code 正常
• Shell 環(huán)境正常加載
• 當(dāng)前目錄適合真正開始寫代碼

十一、第一次測試，不要直接上高風(fēng)險命令

可以先新建一個測試目錄：

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

然后先做低風(fēng)險測試，比如：

claude --help

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

• 解釋當(dāng)前目錄結(jié)構(gòu)
• 幫你補(bǔ)一個 .gitignore
• 改寫一下 README
• 給出項目初始化建議

不要一開始就讓它執(zhí)行高權(quán)限或高風(fēng)險修改。

十二、Mac 上最常見的 7 類問題和修復(fù)方法

command not found: claude

原因：

• npm 全局 bin 不在 PATH
• 安裝成功但 shell 沒刷新
• 程序裝到了你當(dāng)前 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

如果系統(tǒng)彈出安裝開發(fā)者工具的提示，也按流程裝完再試。

node: command not found

原因：

• Node 沒裝
• nvm 沒被 shell 正確加載
• 老版本 Node 沖突

處理：

which node
node --version

如果你是用 nvm，重點(diǎn)檢查 ~/.zshrc 里有沒有正確加載 nvm.sh。

Homebrew 在一個終端能用，在另一個終端不能用

原因：

• Homebrew 初始化寫進(jìn)了不合適的 profile 文件
• 不同終端窗口加載文件順序不同

處理：

• 把 brew shellenv 配到 ~/.zprofile
• PATH 和環(huán)境變量主要放 ~/.zshrc
• 完整關(guān)閉終端后重新打開

環(huán)境變量只在當(dāng)前標(biāo)簽頁有效

原因：

• 只是臨時 export
• 沒寫入 ~/.zshrc

處理：

• 寫進(jìn)配置文件
• 執(zhí)行 source ~/.zshrc
• 再開一個新標(biāo)簽頁做驗(yàn)證

公司網(wǎng)絡(luò)、代理、校園網(wǎng)導(dǎo)致安裝失敗

你可能需要代理環(huán)境變量：

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 安裝時提示權(quán)限不足

不要一上來就亂用：

sudo npm install -g ...

更穩(wěn)妥的做法是：

• 用 Homebrew 安裝 Node
• 或用 nvm 管理 Node
• 保證 npm 全局目錄歸當(dāng)前用戶所有

這樣后面可維護(hù)性會好很多。

十三、給新手的最穩(wěn)妥 Mac 方案

如果你只想要一個最容易成功、最容易排查的配置，我建議這樣：

• Terminal.app 或 iTerm2
• zsh
• Homebrew
• Git via Homebrew
• Node via Homebrew
• Claude Code via npm global install
• 環(huán)境變量寫入 ~/.zshrc

這套不是最炫的，但最容易穩(wěn)定用起來。

常見問題解答

Q1：在 Mac 上安裝 Claude Code，一定要先裝 Git 嗎？

嚴(yán)格來說，安裝命令本身不一定依賴 Git。但從實(shí)際使用看，絕大多數(shù) Claude Code 場景都強(qiáng)烈建議先把 Git 配好。

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

可以，主要區(qū)別只是 Homebrew 路徑通常變成 /opt/homebrew，所以 PATH 排查要注意。

Q3：Homebrew 和 nvm 應(yīng)該選哪個？

新手優(yōu)先 Homebrew，后續(xù)如果你開始管理多個 Node 版本，再切到 nvm 也不遲。

Q4：為什么明明安裝成功了，zsh 里還是找不到claude？

通常不是 Claude Code 本身壞了，而是 npm 全局可執(zhí)行目錄沒有進(jìn) PATH，或者 shell 配置沒有重新加載。

Q5：我能不能不用直連 Anthropic，而是走統(tǒng)一 API 網(wǎng)關(guān)？

可以，前提是你的 CLI 工作流支持相應(yīng)的 provider 或兼容配置。這樣做的好處是多個模型可以共用一套入口和賬單。

結(jié)語

Mac 上配置 Claude Code，真正難的從來不是那條安裝命令，而是后面的環(huán)境完整性。

只要你按這個順序排：

1. 終端
2. Homebrew
3. Git
4. Node/npm
5. Claude Code
6. PATH
7. 環(huán)境變量
8. Git 倉庫驗(yàn)證

大多數(shù)新手安裝問題都能更快定位，也更容易一次配好。

以上就是Claude Code安裝完全指南(Mac版):Git,環(huán)境變量,PATH與常見報錯一次講清的詳細(xì)內(nèi)容，更多關(guān)于Claude Code安裝教學(xué)的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論