在 Mac 上安装和配置 nvm

关键问题

当尝试在 Mac 上使用 nvm 时出现 zsh: command not found: nvm 错误，即使通过 Homebrew 安装成功后仍然无法识别。

问题原因分析

安装 nvm 后出现 command not found 错误通常由以下原因导致：

1. Shell 配置文件（.zshrc 或 .bashrc ）中缺少 nvm 的环境变量配置
2. ~/.nvm 目录缺失或路径不正确
3. Shell 配置未重新加载或终端未重启
4. Homebrew 安装存在依赖问题
5. 系统残留多个 Node.js 版本冲突

完整解决方案

步骤 1：验证 nvm 已正确安装

在终端中运行以下命令确认 Homebrew 已安装 nvm：

brew list | grep nvm

如果未安装，执行安装命令：

brew install nvm

步骤 2：修复 Homebrew 环境

确保 Homebrew 环境健康：

brew doctor
# 按提示修复所有警告
brew cleanup

步骤 3：创建 nvm 专用目录

mkdir -p ~/.nvm

步骤 4：配置 Shell 环境

编辑 zsh 配置文件（使用 Nano 或 VS Code）：

nano ~/.zshrc

在文件末尾添加以下配置：

# NVM 配置
export NVM_DIR="$HOME/.nvm"
[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"
[ -s "$(brew --prefix nvm)/etc/bash_completion.d/nvm" ] && . "$(brew --prefix nvm)/etc/bash_completion.d/nvm"

保存退出后应用新配置：

source ~/.zshrc

重要提示

如果使用 bash，请替换所有 .zshrc 为 .bash_profile 或 .bashrc

步骤 5：验证安装

nvm --version
# 应显示版本号，例如：0.39.5

步骤 6：使用 nvm 管理 Node.js

安装最新 LTS 版本 Node.js：

nvm install --lts

切换使用新安装的版本：

nvm use --lts

确认 Node.js 版本：

node -v

疑难排查

1. 命令仍不可用

尝试手动加载 nvm：

source ~/.nvm/nvm.sh

2. 卸载冲突的 Node.js 版本

操作警告

此操作会移除系统全局安装的 Node.js，建议仅在出现冲突时执行

# 查看 Homebrew 安装的 node 版本
cd /opt/homebrew/Cellar
ls -a | grep node

# 卸载特定版本
brew uninstall node@20  # 替换为实际版本

# 移除全局 node 链接
cd /usr/local/bin
ls -a | grep node  # 确认 node 相关文件
sudo rm -rf node   # 删除单个文件，不要删除整个目录！

3. 重启终端

关闭所有终端窗口重新打开，使配置完全生效。

最佳实践建议

1. 优先使用 nvm 安装 Node.js
   避免同时使用 Homebrew 直接安装 Node.js，防止版本冲突

2. 设置默认 Node.js 版本

   nvm alias default 18.20.0

3. 定期更新 nvm

   brew upgrade nvm

4. 常用 nvm 命令速查

   命令	功能
   nvm install 20	安装 v20.x.x
   nvm use 18	切换到 v18.x.x
   nvm ls	查看已安装版本
   nvm ls-remote	查看远程可用版本

结论

通过正确配置环境变量并确保 .nvm 目录存在，可解决 99% 的 nvm 命令不可用问题。坚持使用 nvm 作为唯一的 Node.js 版本管理工具，可以避免大多数版本冲突问题。