解决 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 管理的路径

线索分析

通过以下线索定位问题：

Shell 类型：

echo $SHELL
# 输出 /bin/zsh（说明使用 zsh）

Node.js 路径：

which node
# 输出 /usr/local/bin/node（非 nvm 管理路径）

环境变量冲突：
- 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 管理的版本

可能遇到的坑

Shell 配置冲突：
- 检查 ~/.zprofile、~/.zshenv 是否有覆盖 PATH 的设置。
权限问题：
- 如果 nvm install 失败，尝试：
```
sudo chown -R $(whoami) ~/.nvm
```
iTerm2 配置未继承：
- 在 iTerm2 中确保 Shell 路径为 /bin/zsh（Preferences > Profiles > General）。