解决 iTerm2 中 nvm 不生效的问题（Mac 环境）

解决 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 环境变量加载顺序详解

希望这篇指南能帮你解决问题！如果有其他疑问，欢迎留言讨论。 🚀