解決 iTerm2 中 nvm 不生效的問題（Mac 環境）

標題

《為什么 iTerm2 無法使用 nvm？—— 解決 Mac 終端環境變量沖突指南》

---

問題描述

許多開發者在 Mac 上使用 nvm 管理 Node.js 版本時，發現：

• 原生終端：nvm、npm、pnpm 等工具正常工作。
• iTerm2：只有 git 和全局安裝的 node v20 可用，其他工具（如 nvm）無法識別。

典型報錯：

?  ~ nvm ls
zsh: command not found: nvm

或

?  ~ which node
/usr/local/bin/node  # 不是 nvm 管理的路徑

---

線索分析

通過以下線索定位問題：

1. Shell 類型：

   echo $SHELL
   # 輸出 /bin/zsh（說明使用 zsh）
   

2. Node.js 路徑：

   which node
   # 輸出 /usr/local/bin/node（非 nvm 管理路徑）
   

3. 環境變量沖突：
   • nvm 未被加載到 Shell 配置中。
   • 全局安裝的 node 優先于 nvm 管理的版本。

---

解決方法

1. 卸載全局 Node.js（避免沖突）

# 通過 Homebrew 卸載
brew uninstall --force node# 或手動刪除
sudo rm -rf /usr/local/bin/{node,npm,npx} /usr/local/lib/node_modules

2. 確保 nvm 正確安裝與加載

(1) 檢查 nvm 是否已安裝

ls ~/.nvm
# 應顯示 nvm 目錄

(2) 在 ~/.zshrc 中加載 nvm

編輯 ~/.zshrc 文件，確保包含以下內容：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # 加載 nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # 自動補全

保存后重新加載配置：

source ~/.zshrc

3. 通過 nvm 重新安裝 Node.js

nvm install 20      # 安裝最新 Node.js 20 版本
nvm use 20          # 切換到該版本
nvm alias default 20  # 設為默認版本

4. 檢查 PATH 優先級

確保 nvm 路徑優先于 /usr/local/bin：

echo $PATH
# 正確順序示例：/Users/xxx/.nvm/...:/usr/local/bin:...

若順序錯誤，在 ~/.zshrc 最前面添加：

export PATH="$HOME/.nvm/versions/node/v20.x.x/bin:$PATH"

重新加載配置：

source ~/.zshrc

5. 驗證修復結果

nvm --version       # 顯示 nvm 版本
nvm ls              # 列出已安裝的 Node.js 版本
which node          # 應顯示 ~/.nvm 路徑
node -v             # 應為 nvm 管理的版本

---

可能遇到的坑

1. Shell 配置沖突：
   • 檢查 ~/.zprofile、~/.zshenv 是否有覆蓋 PATH 的設置。
2. 權限問題：
   • 如果 nvm install 失敗，嘗試：

     sudo chown -R $(whoami) ~/.nvm
     

3. iTerm2 配置未繼承：
   • 在 iTerm2 中確保 Shell 路徑為 /bin/zsh（Preferences > Profiles > General）。

---

總結

1. 卸載全局 Node.js，避免與 nvm 沖突。
2. 正確加載 nvm 到 ~/.zshrc。
3. 用 nvm 重新安裝 Node.js 并設為默認版本。
4. 調整 PATH 順序，確保 nvm 路徑優先。

通過以上步驟，iTerm2 即可正常使用 nvm 管理的 Node.js 和工具鏈。

---

延伸閱讀

• nvm 官方文檔
• Mac 環境變量加載順序詳解

希望這篇指南能幫你解決問題！如果有其他疑問，歡迎留言討論。 🚀