NVM 安装：如何在 Mac Silicon 上管理 Node.js 版本

摘要

第一次在 Mac 上安装 Node.js 时： brew install node似乎就足够了。然而，即使只有两三个项目，问题也会很快出现。有些项目需要 Node 18，而其他项目只能在 Node 22 或更高版本上正常工作。

在这种情况下，您无法每次都删除并重新安装 Node.js。通常，Node 版本使用NVM进行划分和管理。尤其是在 Mac Silicon 环境下，只要了解 zsh 设置、arm64 支持以及旧 Node 版本中 Rosetta 的问题，使用起来并不困难。

目录

• 背景
• 详情
• 最佳实践
• 常见错误
• 故障案例及解决方案
• 结论
• 参考资料

背景

Node.js 版本问题出现的频率比您想象的要高。

例如，现有项目可能运行在 Node 18 上，但新项目可能需要 Node 22 或 24。在这种状态下，如果仅使用一个系统节点， npm install它可以工作，但构建已损坏，或者相反，它可以构建但某些包无法工作。

NVM（节点版本管理器）是一个工具，允许您在这种情况下更改每个项目的 Node.js 版本。

# 프로젝트 A
nvm use 18

# 프로젝트 B
nvm use 24

这样，您就可以更改版本并使用它们。

本文确认的标准

旧的博客文章和当前的官方文档之间的安装说明可能略有不同。于是，我根据下面的数据重新查了一下这篇文章。

验证数据	我们发现了什么
nvm 官方自述文件	安装脚本，zsh配置， .nvmrc, LTS 命令
nvm GitHub Releases	最新的 nvm 版本 v0.40.5
Node.js 官方下载页面	当前 LTS 和当前版本流程
Node.js 发布政策	主动 LTS、维护 LTS、EOL 概念
Apple Support	自 macOS Catalina 以来 zsh 默认 shell
自制官方文档	通往 Apple Silicon 的自制之路 /opt/homebrew
Volta/fnm 官方文档	nvm替代工具比较

详情

步骤1.检查当前的shell和CPU架构

对于 Mac Silicon，默认 shell 通常是 zsh。首先我们检查当前的 shell：

echo $SHELL

在正常的Mac环境下，通常是这样的。

/bin/zsh

还要检查您的 CPU 架构。

uname -m

如果是 Mac Silicon，通常会如下所示。

arm64

如果您已经检查到这里，大部分后续配置文件将是 ~/.zshrc 你可以把它当作一个标准。

步骤2.NVM安装

根据nvm官方README安装。截至撰写本文时的最新版本是 v0.40.5是的。

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

wget如果您正在使用环境，也可以使用以下命令。

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash

安装脚本通常是 ~/.nvm 创建一个目录，并将nvm加载代码添加到shell配置文件中。

步骤 3. 重新打开终端或加载 zsh 设置

安装后立即 nvm 有时您键入命令但它没有输出。这并不意味着安装失败，仍然存在 ~/.zshrc在许多情况下，它不会重新加载。

source ~/.zshrc

或者，您可以完全关闭终端并重新打开它。

使用以下命令检查安装。

command -v nvm

如果是正常的话，就会出现这样的情况。

nvm

步骤 4. 检查 zsh 设置

~/.zshrc检查是否包含以下内容。

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

在nvm官方README中： $XDG_CONFIG_HOME我们还将指导您完成考虑到这一点的设置。

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

如果您有个人 Mac 开发环境，第一种方法通常就足够了。如果您的公司管理点文件或常见的 shell 设置，您也可以检查第二种方法。

步骤 5. 安装 Node.js LTS

对于新项目，通常先安装 LTS 版本会更安全。

nvm install --lts

安装后检查版本。

node -v
npm -v

如果您想使用当前安装的版本作为默认版本，请按如下方式指定。

nvm alias default node

如果要将特定版本设置为默认版本，可以写入版本号。

nvm alias default 24

步骤 6. 创建项目特定的 .nvmrc

在实践中，这是最重要的部分。在项目根目录中 .nvmrc通过创建 ，团队成员可以更轻松地使用相同的 Node 版本。

例如，如果您的项目使用 Node 24， .nvmrc 在文件中写入以下内容：

24

如果你想跟上最新版本的LTS，也可以这样写：

lts/*

在项目文件夹中运行以下命令。

nvm install
nvm use

如果您这样做，您也可以轻松地在自述文件中提供说明。

nvm install
nvm use
npm install

由于 Node 版本不匹配，构建错误比您想象的要多。 .nvmrc 即使只有一项提交也可以显着减少团队成员之间环境的差异。

步骤 7. 移动文件夹时自动运行 nvm use

每次 nvm use如果您不想费心打字，可以使用 zsh 挂钩。

autoload -U add-zsh-hook

load-nvmrc() {
  local node_version="$(nvm version)"
  local nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version="$(nvm version "$(cat "$nvmrc_path")")"

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$node_version" ]; then
      nvm use
    fi
  elif [ "$node_version" != "$(nvm version default)" ]; then
    nvm use default
  fi
}

add-zsh-hook chpwd load-nvmrc
load-nvmrc

然而，对于这个设置有好有坏。每次移动文件夹时，您可能会看到输出，或者终端启动速度可能会稍慢。你可以认为它只是在个人开发环境中尝试一下，如果不方便就将其删除。

如果您需要 Mac Silicon 上的 Rosetta

如果您使用的是最新的 Node.js LTS，通常不必担心 Rosetta。根据nvm官方文档，Node.js从v16.0.0开始为Apple Silicon提供arm64 Darwin二进制文件。

问题是旧的 Node 版本。

Node.js 版本	这对 Mac Silicon 意味着什么
Node.js 16+	arm64 Darwin 二进制文件可用
Node.js 14.17 或更高版本	提及基于源码编译的实验性arm64支持
旧 Node.js 14 及以下版本	可能需要 Rosetta 2 或 x86_64 环境

要检查您的节点当前运行的架构，请使用以下命令：

node -p "process.arch"

如果arm64节点在Mac Silicon 上运行，它将显示如下。

arm64

我可以使用 Homebrew 安装 nvm 吗？

总之，我不推荐它。 nvm 的官方 README 声明不支持 Homebrew 安装。

您可能会在 Homebrew 中看到 nvm 包。但是，当出现问题时，官方nvm项目会指示您使用官方安装脚本重新安装和检查，而不是Homebrew安装。

所以最好按照下面的方式安装nvm。

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

Homebrew方便安装其他开发工具。不过，遵循nvm官方的安装方法就不会那么混乱了。

Volta 与 fnm 相比

nvm 并不是唯一的 Node 版本管理工具。如果你正在制定新的团队标准，Volta 或 fnm 也值得关注。

工具	特征	非常适合这些情况
nvm	使用最广泛的基于 shell 的 Node 版本管理器	现有的数据有很多 .nvmrc 当兼容性很重要时
Volta	修复Node、npm、yarn、pnpm等工具版本能力强	当你想以团队为基础强匹配JS工具版本时
fnm	速度很快，因为它基于 Rust .nvmrc也支持	使用方式与 nvm 类似，但当速度很重要时

对于个人开发环境，从nvm开始就足够了。如果是团队单位，无论使用什么工具，README 和 CI 设置都必须协调。

最佳实践

将 .nvmrc 提交到项目中

.nvmrc虽小但有效。特别是在前端项目或者基于Node的后端项目中，经常会因为Node 版本单一而出现安装错误。

24

将此文件放在项目的根目录中并将其提交到 Git。

在README中记下执行顺序

最好在自述文件中编写以下内容，以便任何第一次收到该项目的人都可以立即关注它。

nvm install
nvm use
npm install
npm run dev

仅仅做到这一点就能帮助您在入职过程中减少迷失。

匹配 CI 和本地 Node 版本

如果您的本地是 Node 24，但您的 CI 是 Node 20，则结果可能会有所不同。 GitHub Actions 或 Jenkins 中使用的节点版本 .nvmrc搭配起来比较安全。

旧的 Node 版本留下了原因

如果您需要继续使用 Node 14 或 16 等旧版本，最好留下一个原因。如果你整理一下是否有特定的包兼容性或运行环境限制，而不是简单地说“我以前也这样用过”，对以后升级时会有帮助。

常见错误

安装nvm后，出现命令未找到。

这是最常见的情况。并不是没有安装，而是shell设置还没有应用。

source ~/.zshrc
command -v nvm

如果这不起作用 ~/.zshrc到 NVM_DIR 检查设置是否已输入。

设置位于 .zshrc 以外的文件中。

nvm安装脚本是 ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.profile 我正在尝试自动选择以下选项之一。有时，在文件中输入的设置与您想要的不同。

如果您在 Mac 上使用 zsh，首先 ~/.zshrc看看吧。

cat ~/.zshrc

Homebrew Node 和 nvm Node 混合使用

过去 brew install node如果还有任何剩余节点安装了 which node 结果可能并不如预期。

which node
node -v

如果使用nvm Node，通常在路径中 .nvm这包括在内。

/Users/사용자명/.nvm/versions/node/v24.x.x/bin/node

只创建.nvmrc，不使用nvm

.nvmrc 创建文件不会自动更改版本。如果您尚未设置自动转换，则需要自行设置。

nvm use

VS Code 终端和常规终端的 Node 版本不同。

有时，nvm 在常规终端中工作，但在 VS Code 终端中不起作用。此时VS Code默认的shell是zsh，并且 ~/.zshrc您需要确保它正确加载。

echo $SHELL
command -v nvm
node -v

故障案例及解决方案

案例1.我安装了 nvm: command not found出来

这是最常见的情况。查看官方README和Stack Overflow示例，通常不是安装失败，而是shell设置尚未加载的问题。

首先，打开一个新终端或运行以下命令。

source ~/.zshrc
command -v nvm

如果什么也没有发生 ~/.zshrc检查是否输入了nvm加载代码。

grep NVM_DIR ~/.zshrc

如果没有设置，请添加以下内容。

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

保存并重新加载。

source ~/.zshrc

这里重要的是 which nvm看到 command -v nvm最好使用 .这是因为 nvm 是作为 shell 函数而不是常规可执行文件加载的。

案例 2. nvm 仅在 VS Code 终端中不起作用

在普通终端中 nvm这可能仅在 VS Code 终端中不起作用。在这种情况下，VS Code 打开的 shell 或配置文件设置可能与常规终端中的不同。

首先在 VS Code 终端中检查一下。

echo $SHELL
command -v nvm
node -v

在常规终端中运行相同的命令并比较结果。

echo $SHELL
command -v nvm
node -v

如果两者的结果不同，在VS Code中 Terminal: Select Default Profile运行并检查默认终端是否设置为 zsh。如果这不起作用，请打开 VS Code 终端 ~/.zshrc您需要确保您的阅读正确。

案例 3. Homebrew Node 和 nvm Node 混合

过去 brew install node如果您在安装了 Node.js 的情况下安装 nvm，则路径可能会令人困惑。此时 node -v仅仅看它是不够的；您需要查看哪些节点正在实际运行。

which node
node -v
npm -v

如果使用nvm节点，则进入正常路径 .nvm这个就进去了

/Users/사용자명/.nvm/versions/node/v24.x.x/bin/node

相反，当捕获 Homebrew 节点时，通常是 /opt/homebrew 你可以看到路径。

/opt/homebrew/bin/node

在这种情况下，您需要决定使用哪种方法。如果您打算使用 nvm 管理每个项目的版本，则在初始化终端后， nvm use首先，确保正确应用。

nvm use
which node

没有必要无条件删除Homebrew Node，但如果你不知道这两种方法是混合的， npm install这使得追踪构建错误变得困难。

案例4. .nvmrc有，但 Node 版本不会自动更改。

.nvmrc不是自动转换功能，而是表示“本项目使用此版本的 Node.js”。如果您尚未设置自动转换，则需要自行设置。

nvm install
nvm use

如果想要自动转换，需要添加zsh hook。然而，这个设置并不是每个人都需要的。有些人不喜欢每次移动终端时都会出现输出，因此最好将其保留为个人选择，而不是强制将其作为团队规则。

案例 5. 安装旧 Node 版本时出现 Mac Silicon 问题

最新的 LTS 版本通常可以在 arm64 上安装良好。问题在于旧的 Node.js 版本。根据nvm官方文档，Node.js从v16.0.0开始为Apple Silicon提供arm64 Darwin二进制文件。

如果您需要对较旧的项目使用 Node 14 或更低版本，则可能需要 Rosetta 或 x86_64 环境。首先，检查当前的架构。

uname -m
node -p "process.arch"

如果可能的话，最好将您的项目升级到 LTS 版本。如果您需要非常旧版本的 Node，请在 README 中留下原因。稍后，还会有人再次遇到同样的问题。

结论

在 Mac Silicon 上使用 nvm 本身不再那么困难了。如果您要安装最新的 Node.js LTS，您甚至不需要首先考虑 Rosetta。

事实上，经常卡住的部分是shell设置而不是安装。 nvm 如果命令没有被捕获，则不是 Node 的问题。 ~/.zshrc它通常未加载，或者设置位于不同的配置文件中。

对于个人开发环境，从nvm开始就足够了。如果这是一个团队项目 .nvmrc一起提交并设置 README 和 CI 节点版本。这个小小的清理工作将为您避免以后出现很多构建错误。

参考资料

• nvm GitHub README — https://github.com/nvm-sh/nvm
• nvm latest release — https://github.com/nvm-sh/nvm/releases/latest
• Node.js Downloads — https://nodejs.org/en/download
• Node.js Releases — https://nodejs.org/en/about/previous-releases
• Apple Support: Use zsh as the default shell on your Mac — https://support.apple.com/en-us/102360
• Homebrew Official Site — https://brew.sh/
• Volta Official Site — https://volta.sh/
• fnm GitHub README — https://github.com/Schniz/fnm