nvm:一个 shell 函数,怎么把 Node 多版本管理玩明白的#

仓库 nvm-sh/nvm ↗,87K stars,作者 Tim Caswell(创建者)+ Peter Dave Hello(现任 maintainer),MIT 协议。整个项目最让我意外的不是它”流行”,而是流行了 10 年还是 5642 行 nvm.sh 一个文件。它做的事情看起来朴素到反直觉:不装 daemon、不动 PATH 全局段、不修改 node 本身,只是在你 shell 里挂一个函数,每次 use 就把 PATH 切一段。 下面这些内容是我通读 nvm.sh 后的笔记,按”为什么这样设计 -> 源码怎么实现 -> 哪些坑”重新组织一遍。

0. 先把数字摆出来#

• 单文件 nvm.sh:5642 行,188KB,纯 POSIX shell(bash/zsh/dash/sh/ksh 全兼容)
• 配套:install.sh 536 行(首次安装),nvm-exec 21 行(包装脚本),bash_completion 110 行(补全)
• 内部函数 60+ 个,全部 nvm_ 前缀
• 测试:test/fast + test/slow + test/sourcing + test/install_script + test/installation_node + test/installation_iojs,用 urchin ↗ shell test framework
• CI 跑 5 个 shell × 6 套测试矩阵
• 仓库自带 AGENTS.md(17K)给 AI agent 看 —— 这是我见过对 agent 最友好的基础设施项目

1. 它要解决的真问题#

Node 多版本管理的痛点其实很朴素:

• 系统装一个 node,项目 A 要 16,项目 B 要 18,项目 C 要 20 —— 不可能来回 apt install / 卸载
• 不同 Linux 发行版、macOS、Windows(WSL)的 node 路径不一样
• 同一台机器,有人用 yarn classic,有人用 pnpm,不同 node 配不同 npm
• 项目根目录要能”声明它要哪个 node”—— 业界标准就是 .nvmrc

听起来简单。但你仔细想一下,这个”切版本”的本质是:让 shell 在执行 node / npm 时,找到的二进制指向不同目录。

要实现这一点,业界有三条路:

nvm 选了第三条路,而且只改了 shell 当前会话的 PATH,不动全局。这个选择决定了它整套架构的方向。

(图 0:nvm 整体架构。nvm() 是 nvm.sh 3869 行的那个主调度函数,所有子命令 use / install / ls / exec / run / alias / current 都从它分出去;再下面 60+ 个 nvm_ 内部函数按”版本解析 / PATH 切换 / 下载校验 / 二进制安装 / LTS 远程”五类职责分组。)

2. nvm() 主函数:不是路由,是 shell 兼容器#

很多人以为 nvm() 就是一个 case $COMMAND in use|install|...) 路由。但看 nvm.sh:3869 那个真正的主函数,会发现它前面 30 行做的是另一件事——shell 兼容性铺垫。这是我读到一半最想拍桌子的地方。

nvm() {
  if [ "$#" -lt 1 ]; then
    nvm --help
    return
  fi

  local DEFAULT_IFS
  DEFAULT_IFS=" $(nvm_echo t | command tr t \\t)
"
  if [ "${-#*e}" != "$-" ]; then
    set +e
    ...
    nvm "$@"
    EXIT_CODE="$?"
    set -e
    return "$EXIT_CODE"
  elif [ "${-#*a}" != "$-" ]; then
    set +a
    ...
  elif [ -n "${BASH-}" ] && [ "${-#*E}" != "$-" ]; then
    set +E
    ...
  elif [ "${IFS}" != "${DEFAULT_IFS}" ]; then
    local IFS
    IFS="${DEFAULT_IFS}"
    nvm "$@"
    return "$?"
  fi
  ...
}

这几段在做一件很微妙的事:当你用 set -e / set -a / set -E 调用 nvm 时,内部命令失败不会 abort 整个函数,退出码被保留并原样回传。${-#*e} 这个写法是 POSIX 检测当前 shell 选项的标准 idiom,意思是”如果 $- 去掉第一个 e 之后不等于 $-,说明有 e”。

IFS 那段更狠:某些用户会把 IFS 改掉(比如 IFS=$(printf "\n.") 用来按行切)。nvm 内部依赖 IFS=默认值 来解析参数,所以检测到 IFS 被改,先临时重置再递归调用自己。

这个设计为什么重要?因为 nvm 是被 source 进来的,跟用户的 shell 选项/IFS 同生共死。如果不处理 set -e,用户写 set -e && nvm use 18 第一次失败就把整个 shell 退出了,直接崩溃。

换句话说,nvm() 的头 30 行不是逻辑,是”和用户 shell 握手”。这个工程取舍,值得所有”通过 source 注入到用户 shell”的工具(rbenv、pyenv、asdf 都该学)。

然后才是真正的 case 路由:

local COMMAND
COMMAND="${1-}"
shift

case $COMMAND in
  "cache")  ... ;;
  "debug")  ... ;;
  "install" | "i")  ... ;;
  "uninstall")      ... ;;
  "deactivate")      ... ;;
  "use")             ... ;;
  "run")             ... ;;
  "exec")            ... ;;
  "ls" | "list")     ... ;;
  "current")         ... ;;
  "which")           ... ;;
  "alias")           ... ;;
  "unload")          ... ;;
  *)  nvm_err "unimplemented command: $COMMAND"; return 127 ;;
esac

11 个分支,就是 11 个大子命令。unload 是”把自己从 shell 里卸掉”,比较狠,等会单独说。

3. nvm use:这套系统的”灵魂”操作#

nvm use 18.16.0 是用户用得最多的命令。它做的事情看起来只有一行:让你下一次敲 node 时拿到 18.16.0。但底层要管 PATH、MANPATH、bash hash cache、NVM_BIN / NVM_INC、.nvmrc 自动感知、—lts 解析、—save 写回、跨 shell 兼容……

源码在 nvm.sh:4735,我把它拆成 5 个阶段画了一张图:

(图 1:nvm use 的 5 个阶段。重点看下面 nvm_change_path 的 3 个分支,这是 nvm 最被低估的一段代码。)

3.1 阶段 1:参数解析#

跟 install 一样是 while-case 模式,但 use 的参数少得多:--silent / --delete-prefix / --lts / --lts=<name> / --save / -w / 必填的版本号(或省略 → 读 .nvmrc)。

值得看的小细节:-w 和 --save 是一回事,-w 是 nvm use --save 的简写。这个简写在 nvm install 里也存在(见 nvm.sh:4265)。在 nvm 整个项目里 -w 都只指”写回 .nvmrc”,不跟 npm 的 -w(workspaces) 冲突。

3.2 阶段 2:版本解析 — 整个 nvm 复杂度最高的一段#

nvm_resolve_alias(nvm.sh:1695)和 nvm_version(nvm.sh:960)加起来 100+ 行,处理这些情况:

• 输入是 lts/hydrogen、lts/* → 走 LTS 路径
• 输入是 default、node、stable、unstable、system、iojs → 内置 alias
• 输入是 18、v18.16.0、18.16.0 → 加 v 前缀,匹配本地已装版本
• 输入是 lts/argon 之类的老 LTS 名 → 反向查 alias 目录
• 输入是 .nvmrc 文件名 → nvm_find_nvmrc 沿父目录找(沿到 / 停)
• 都没命中 → return 3,提示 nvm ls-remote

这套逻辑之所以复杂,是因为版本解析不是数据库查询,是一连串的”试试看”。每一层 fallback 都有副作用(比如打 .nvmrc 内容、查文件系统、读 alias 目录),所以代码看起来不像决策树,更像 try-catch 链。

3.3 阶段 3:校验存在 — 3 个特殊路径#

nvm_ensure_version_installed(nvm.sh:922)只做一件事:看 version 在 $NVM_DIR/versions/node/ 下有没有目录。但有 3 个特殊情况需要单独拦:

• system → 不存在本地,直接放过
• N/A → 解析失败,提示用户装
• ∞ → alias 循环了,这个我等会专门讲

3.4 阶段 4:真正的”切换” — nvm_change_path#

这是整个 nvm 最被低估的一段代码,在 nvm.sh:1259。我把它单独画在图 1 的下半部。

nvm_change_path() {
  if [ -z "${1-}" ]; then
    nvm_echo "${3-}${2-}"
    return
  fi
  local NVM_DIR_RE
  NVM_DIR_RE="$(nvm_echo "${NVM_DIR}" | command sed 's/[][\.*^$+?(){}|]/\\&/g')"
  if ! nvm_echo "${1-}" | nvm_grep -Eq "${NVM_DIR_RE}/[^/]*${2-}" \
    && ! nvm_echo "${1-}" | nvm_grep -Eq "${NVM_DIR_RE}/versions/[^/]*/[^/]*${2-}"; then
    nvm_echo "${3-}${2-}:${1-}"
  elif nvm_echo "${1-}" | nvm_grep -Eq "(^|:)(/usr(/local)?)?${2-}:.*${NVM_DIR_RE}/[^/]*${2-}" \
    || nvm_echo "${1-}" | nvm_grep -Eq "(^|:)(/usr(/local)?)?${2-}:.*${NVM_DIR_RE}/versions/[^/]*/[^/]*${2-}"; then
    nvm_echo "${3-}${2-}:${1-}"
  else
    local NVM_DIR_SED
    NVM_DIR_SED="$(nvm_echo "${NVM_DIR_RE}" | command sed 's/#/\\#/g')"
    local NEW_DIR_SED
    NEW_DIR_SED="$(nvm_echo "${3-}" | command sed 's/[\&#]/\\&/g')"
    nvm_echo "${1-}" | command sed -E \
      -e "s#${NVM_DIR_SED}/[^/]*${2-}[^:]*#${NEW_DIR_SED}${2-}#" \
      -e "s#${NVM_DIR_SED}/versions/[^/]*/[^/]*${2-}[^:]*#${NEW_DIR_SED}${2-}#"
  fi
}

3 个分支:

1. PATH 里根本没有 nvm 段 → 直接前置新的 NVM_DIR/bin
2. nvm 段存在但系统段(/usr/bin、/usr/local/bin)在它前面 → 还是前置(避免 #1652 那个边界 case:Mac Homebrew 用户的 /usr/local/bin 抢在 nvm 之前,导致 node 拿到系统版本)
3. nvm 段正常存在 → sed 替换那一段,保留其他顺序

第 3 个分支是 nvm 跟 fnm/volta 最大的差异点:它不修改文件系统,只修改 shell 里的字符串变量。你 nvm use 18 之后 cd 到别处再 nvm use 20,PATH 里的 nvm 段就被 sed 改写到 20 的位置,一切在内存里完成。

这里有个反直觉的细节:nvm_change_path 接 3 个参数—— 原 PATH / 要切的后缀(/bin 或 /share/man) / 新版本完整路径。它对 PATH 和 MANPATH 用的是同一段代码。nvm use 内部会调它两次,一次切 bin,一次切 share/man,保证 man 文档也跟到新版本。

3.5 阶段 5:hash -r — 这个 5 个字符的值最高#

nvm_hash_reset() {
  if [ -n "${BASH_VERSION-}" ] && [ "${-#*h}" = "$-" ]; then
    return 0
  fi
  if [ -n "${KSH_VERSION-}" ] && ! ( \hash -r ) >/dev/null 2>&1; then
    return 0
  fi
  \hash -r
}

bash 的 hash 表是惰性缓存的:第一次敲 node,bash 找到 PATH 里的 node,把位置存到 hash 表;第二次再敲,直接用 hash 表,不看 PATH。这意味着 nvm use 改完 PATH 不 hash -r,你的 node 仍然跑老版本。

hash -r 5 个字符清空这个表,后面所有命令重新查 PATH。

但 hash -r 不是所有 shell 都支持:

• bash:支持
• zsh:有 rehash,等价
• ksh93:hash 不接受 -r,用了就 fatal
• dash / POSIX sh:压根没 hash 这个内建

nvm 怎么处理?先看 BASH_VERSION + set +h 模式(-#*h 检测 h 标志),跳过;再看 ksh 是不是支持 -r,不支持就探针包在子 shell 里,屏蔽 fatal。这个探测代码本身就是跨 shell 工程化的范本。

nvm-exec 那个 21 行的 wrapper 也用同一套机制,只是为了不把 shell 整个污染(每次 nvm exec 子进程跑完即焚,不影响当前 shell 的 hash 表)。

4. nvm install:把”下载+校验+编译”做成可重试管道#

nvm install 比 use 长得多—— nvm.sh:4150 开始,接近 400 行。但它本质是 8 个阶段的流水线,每一步都有明确的成功/失败回退策略。

(图 2:nvm install 的 8 个阶段。下方三个决策点:binary vs source、mirror 解析、download slug 拼接。失败时 binary → source fallback,但 checksum 失败不回退。)

4.1 阶段 1-3:拿到确切的”要装的版本”#

provided_version 可以是 18、v18.16.0、lts/*、lts/hydrogen、node(latest)。每种都要先解析成确切的 vX.Y.Z。

nvm_remote_version(nvm.sh:1004)是这段的入口。它内部调 nvm_remote_versions(nvm.sh:1042)下载 https://nodejs.org/dist/index.tab —— 这个 index.tab 是 Node 官方维护的纯文本版本表,大概 200+ 行,长这样:

v20.10.0  2023-11-22  v8  v9  v8.4.0   ...   release
v20.11.0  2024-01-09  ...                                release
v20.11.1  2024-02-14  ...                                security

每行 10 列,固定宽度空格分隔。awk '{ print $1, $10, "*" }' 就能拿到 (version, lts_name, current_marker)。这比抓 HTML 省事 100 倍 —— Node 维护者懂 Unix 哲学。

4.2 阶段 4-5:mirror + checksum#

nvm_get_mirror(nvm.sh:2814)返回下载源:

nvm_get_mirror() {
  local NVM_MIRROR
  NVM_MIRROR=''
  case "${1}-${2}" in
    node-std) NVM_MIRROR="${NVM_NODEJS_ORG_MIRROR:-https://nodejs.org/dist}" ;;
    iojs-std) NVM_MIRROR="${NVM_IOJS_ORG_MIRROR:-https://iojs.org/dist}" ;;
    *) return 1 ;;
  esac
  ...
}

但重点在后面的 URL 校验:

if ! nvm_echo "${NVM_MIRROR}" | command awk '{ if ($0 !~ /^https?:\/\/[]a-zA-Z0-9._~:\/@%[-]+$/) exit 1 }'; then
    nvm_err '$NVM_NODEJS_ORG_MIRROR and $NVM_IOJS_ORG_MIRROR may only contain a URL'
    return 2
fi

这条正则严格只允许 RFC 3986 unreserved + 必要标点(: @ % [ ] - _ . ~ /)。明确拒绝 ? & * ( ) ` ' ; 这些 shell 元字符。

为什么这么严?因为 nvm 会直接把 mirror URL 拼到下载路径里,比如 ${MIRROR}/v18.16.0/node-v18.16.0-linux-x64.tar.xz。如果用户把 mirror 设成 https://evil.com/?inject=;rm -rf /,后续 sed 拼接会被 shell 解释。

这就是”用户配置做严格白名单”在 shell 工具里的标准做法。我之前拆的 TencentCloud Lighthouse 安全基线 ↗ 里有同样的思路:任何会被拼接/eval 的字符串,先过白名单。

checksum 这块(阶段 5)更精彩。nvm_get_checksum_binary(nvm.sh:2090)按这个顺序探测系统里有什么:

sha256sum → shasum → sha256 → gsha256sum → openssl → bssl → sha1sum → sha1

7 个备选,涵盖 GNU coreutils、BSD、macOS FreeBSD、Alpine busybox。openssl 几乎所有 Linux 都有,所以兜底稳。

4.3 阶段 6-7:download + extract#

nvm_download_artifact(nvm.sh:3062)是这段的核心。关键在 download slug 的拼接(nvm.sh:2962):

nvm_get_download_slug() {
  case "${1}" in node|iojs) FLAVOR="${1}";; ...
  case "${2}" in binary|source) KIND="${2}"; ...
  local NVM_OS; NVM_OS="$(nvm_get_os)"
  local NVM_ARCH; NVM_ARCH="$(nvm_get_arch)"

  if ! nvm_is_merged_node_version "${VERSION}"; then
    if [ "${NVM_ARCH}" = 'armv6l' ] || [ "${NVM_ARCH}" = 'armv7l' ]; then
      NVM_ARCH="arm-pi"
    fi
  fi
  if nvm_version_greater '16.0.0' "${VERSION}" && [ "_${NVM_OS}" = '_darwin' ] && [ "${NVM_ARCH}" = 'arm64' ]; then
    NVM_ARCH=x64
  fi

  if [ "${KIND}" = 'binary' ]; then
    nvm_echo "${FLAVOR}-${VERSION}-${NVM_OS}-${NVM_ARCH}"
  elif [ "${KIND}" = 'source' ]; then
    nvm_echo "${FLAVOR}-${VERSION}"
  fi
}

输出像 node-v18.16.0-linux-x64 或 node-v18.16.0-darwin-arm64 或 node-v18.16.0-linux-arm-pi(树莓派)。

两个特殊处理:

• Mac M1 + Node < 16:arm64 二进制不存在,回退 x64(用 Rosetta 跑)
• armv6l / armv7l(树莓派):slug 改成 arm-pi,因为 Node 官方的 armv6l/armv7l 早就合并了

4.4 阶段 8:install 完事的副作用#

reinstall-packages-from=vX → 装完新版本后,跑一份 npm install -g 把老版本的全局包在新版本上重装。 --latest-npm → 装完后 npm install -g npm@latest。 --alias=xxx / --default → 调 nvm_make_alias(nvm.sh:1534)在 $NVM_DIR/alias/ 下写一个文件,内容就是版本号。 --save / -w → 写 .nvmrc。

5. alias 系统:30 行 shell 搞定”循环引用检测”#

alias 是 nvm 看起来”小”、实际”最妙”的部分。我把它单独画了一张图:

(图 3:nvm alias 解析的完整链路。注意 while-true 循环体里只有 3 件事:读并切 token、SEEN 集合查重、推进状态;循环退出后还有 4 类后处理。)

源码在 nvm.sh:1695:

nvm_resolve_alias() {
  if [ -z "${1-}" ]; then return 1; fi
  local PATTERN="${1-}"
  local ALIAS="${PATTERN}"
  local ALIAS_TEMP
  local ALIAS_OUTPUT

  local SEEN_ALIASES
  SEEN_ALIASES="
${ALIAS}
"
  while true; do
    ALIAS_OUTPUT="$(nvm_alias "${ALIAS}" 2>/dev/null)" || ALIAS_OUTPUT=''
    ALIAS_TEMP="${ALIAS_OUTPUT%% *}"
    if [ -z "${ALIAS_TEMP}" ]; then break; fi
    case "${SEEN_ALIASES}" in
      *"
${ALIAS_TEMP}
"*)  ALIAS="∞"; break ;;
    esac
    SEEN_ALIASES="${SEEN_ALIASES}${ALIAS_TEMP}
"
    ALIAS="${ALIAS_TEMP}"
  done
  ...
}

设计得相当克制:

• SEEN_ALIASES 是一个多行字符串,每个 alias 名占一行(以换行开头、换行结尾)
• 循环每次:读 alias 文件 → 取第一个 token(用 %% * 切空格)→ 看 token 是否在 SEEN 里
• 在 → 把 ALIAS 设成 ∞,退出循环 → 调用方 return 8
• 不在 → 把 token 追加到 SEEN,ALIAS 推进到 token,继续循环

30 行不到的代码,处理了所有 alias 嵌套、循环、forwarding 场景。比 Lua 那种图算法清爽多了。

LTS 的处理是另一条路。nvm_ls_remote_index_tab(nvm.sh:2019)解析 index.tab 时,顺手把 LTS name 都做成 alias:

command awk '{
  if ($10 ~ /^\-?$/) { next }
  if (tolower($10) !~ /^[a-z0-9][a-z0-9._-]*$/) { next }
  if ($10 && !a[tolower($10)]++) {
    ...
    nvm_make_alias "lts/" tolower($10) version
  }
}'

nvm use --lts 时,先把 lts/* 解析成 lts/hydrogen(最新 LTS),再走上面的循环解析。整套机制自洽。

6. nvm-exec:21 行的”无副作用”执行器#

nvm-exec(21 行)是另一个让我眼前一亮的文件:

#!/usr/bin/env bash
DIR="$(command cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
unset NVM_CD_FLAGS
\. "$DIR/nvm.sh" --no-use

if [ -n "$NODE_VERSION" ]; then
  nvm use "$NODE_VERSION" > /dev/null || exit 127
else
  { NVM_RC_VERSION="$(nvm_rc_version 3>&1 1>&4)"; } 4>&1 && nvm_ensure_version_installed "$NVM_RC_VERSION";
  if ! nvm use >/dev/null 2>&1; then
    nvm_err 'nvm-exec: unable to select a node version'
    nvm_err '  Set `NODE_VERSION` (e.g. `NODE_VERSION=default`), or add an `.nvmrc` file.'
    exit 127
  fi
fi
exec "$@"

几个细节值得说:

• \. "$DIR/nvm.sh" --no-use —— 用 .(POSIX source)而不是 source(bashism)。--no-use 标志告诉 nvm.sh 不要在 source 阶段自动跑 nvm use,避免污染调用方 shell
• nvm_rc_version 3>&1 1>&4 —— 双重 fd 重定向,把 .nvmrc 读取过程产生的”Found ‘/foo/.nvmrc’ with version <18>“信息流到 stderr(原始 fd 1),版本号留 stdout(临时 fd 3),调用方可以静默地拿到版本号而看不到噪音
• 末尾 exec "$@" —— exec 替换当前进程,不 fork 子进程。node 跑起来 PID 就是 nvm-exec 的 PID,信号传递、退出码、stdin/stdout 全保留

这是”在子 shell 跑指定版本 Node”的最简实现。Docker 容器里 NODE_VERSION=18 node app.js 这种就是它的工作场景。

7. install.sh:第一次接触 nvm 的人会走过的代码#

install.sh(536 行)做的事情其实不多:

1. 检测 shell 必须是 bash(BASH_VERSION 非空,ZSH_VERSION 为空),否则报错退出
2. 算默认 install dir:$XDG_CONFIG_HOME/nvm 或 $HOME/.nvm
3. 三种安装方式:git clone / script download / 用户自定义 mirror
4. 检测或创建 $NVM_DIR 目录
5. 检测 shell profile(~/.bashrc、~/.zshrc、~/.bash_profile、~/.zprofile),在末尾追加 source 行
6. 装 bash completion

但里面有几个工程细节挺到位:

• NVM_INSTALL_GITHUB_REPO 允许用户改仓库,改了就大声警告”你可能被中间人攻击了”
• 装完自动 nvm --version 一次,确认能跑
• 提供 --no-update / --no-promo / -y 等非交互选项,适合 CI / Dockerfile

8. 跨 shell 兼容:nvm 最难维护的部分#

nvm 支持 5 个 shell:bash / zsh / dash / sh / ksh。每个 shell 的 quirks 都得在代码里挡。

随手列几个我读到的:

• local 是 bash/ksh 扩展,dash 不支持 —— nvm 用 local 但限制在函数体顶部声明(local VAR; VAR=val 两行,ksh 才会正确拿到 caller 的值)
• ${var%%pattern} 参数扩展 dash 和 bash 都支持,ksh 不全支持 —— nvm 关键路径用 awk 兜底
• IFS=... 在 zsh 里要 setopt local_options shwordsplit 才按 word 切 —— nvm 在涉及 word splitting 的地方都加 nvm_is_zsh && setopt local_options shwordsplit
• bash hash set +h 模式(nvm 直接跳过 hash -r);ksh93 hash -r fatal(用子 shell 探针)
• hash 在 zsh 不存在,要用 rehash —— 但 nvm 整个项目用 \hash -r(\ 是 builtin 强制),所以 zsh 用户 source 后会报错,这个问题在 #774 长期挂着

我读完最大的感慨是:nvm 用了 10 年还在打这些 shell 兼容的补丁,说明 shell 工具的跨平台从来不是”写一次到处跑”。任何想写”能 source 到任意 shell”的工具作者,都应该把 nvm.sh 全文读一遍当教科书。

9. 测试架构:5 个 shell × 6 套测试矩阵#

test/ 目录下 6 套测试:

package.json 里的 test script 很妙:

"test": "shell=$(basename -- $(ps -o comm= $(ps -o ppid= -p $PPID)) | sed 's/^-//'); make test-$shell"

ps -o comm= $(ps -o ppid= -p $PPID) —— 通过 PPID 拿父进程,再拿父进程的 comm,推断当前 shell 是 bash 还是 zsh 还是 dash,然后跑对应的 make target。

这意味着:用户在自己当前 shell 里跑 npm test,会用当前 shell 跑测试,而不是默认 shell。在 zsh 用户的机器上就不会用 bash 跑 zsh 才有的测试用例。

CI 在 .github/workflows/tests.yml 里走 matrix:shells × test_suites 全组合,任何一对失败都报警。

10. 那些”看起来脏但其实对”的设计#

读 nvm 还会遇到一些反主流的设计选择,我觉得值得点出来:

10.1 不用 set -e、不用 set -u#

nvm.sh 全文不依赖 strict mode。它自己写:

if [ -n "${BASH_VERSION-}" ] && [ "${-#*E}" != "$-" ]; then
  set +E
  ...
  nvm "$@"
  EXIT_CODE="$?"
  set -E
  return "$EXIT_CODE"
fi

这是主动配合用户的 shell 选项,不把 nvm 自己的”严格”强加给用户。我自己写 shell 工具时也倾向这个思路:不要假设用户开 strict mode。

10.2 nvm_echo 替代 echo#

所有输出统一走 nvm_echo,内部用 command printf %s\\n。echo 在不同 shell 解释 \n 不一样(POSIX echo 不强制支持 -e),printf 行为一致。

10.3 大段 heredoc + awk#

nvm_ls_remote 解析 index.tab 全部用 awk 内嵌,不引入 jq 之类的依赖。代价是 awk 代码不易读,收益是零外部依赖。

10.4 alias 存为文件,不用 SQLite/JSON#

$NVM_DIR/alias/<name> 就是个文本文件,内容就是版本号。nvm_make_alias:

nvm_echo "${VERSION}" | tee "$(nvm_alias_path)/${ALIAS}" >/dev/null

nvm_ls 列出所有 alias 就是 ls -1 $NVM_DIR/alias/。比数据库透明 100 倍,人类可以直接 cat / 编辑 / git track。

10.5 nvm unload 这个”自毁”功能#

nvm() {
  unset -f nvm
  unset -f nvm_iojs_prefix nvm_node_prefix nvm_ls_remote ...
  unset NVM_DIR NVM_BIN NVM_INC NVM_CD_FLAGS
  echo "nvm unloaded"
}

用户 source nvm 后想完全撤掉,nvm unload 一键清。这种”提供退出路径”的设计在 source 注入式工具里是稀缺品——rbenv、pyenv 都没给这么干净的退出。

11. 跟同类工具的对比#

读到这你可能想问,nvm 跟 fnm / volta 比怎么样?一句话总结:

nvm 的最大优势是:它不引入新概念,你的 PATH 仍然是你熟悉的 PATH,出问题你能 echo $PATH 看到自己做了什么。fnm / volta 写 symlink/shim 之后,你的 which node 指向 ~/.fnm/node-versions/... 或者 ~/.volta/tools/image/...,调试时反而要绕一层。

nvm 的最大劣势:大项目(几十个 node 版本)source 一次要扫所有 alias 目录,首次启动慢;每次 nvm use 都要改 PATH 字符串,频繁切会感知到延迟。fnm 用 symlink 几乎无感。

12. 复用价值最高的 5 条#

从 nvm 源码里抽出 5 条我觉得”放之四海而皆准”的设计原则:

1. source 注入式工具必须做 shell 握手 —— 检测 set -e / set -a / IFS / -h / -E,主动配合,不要假设用户没开 strict mode
2. PATH 操作走 sed 字符串替换,不动文件系统 —— nvm_change_path 的 3 分支策略,比 symlink 简单 10 倍、调试时透明 100 倍
3. 用户配置做严格白名单 —— nvm_get_mirror 那个 RFC 3986 正则,凡是会被 sed/eval 拼接的字符串都该过这一关
4. alias 用纯文本文件而不是数据库 —— $NVM_DIR/alias/<name> 一个文件存一行,人类可读、可 git 跟踪、可手工修
5. 跨 shell 工具必须主动探测 builtin 行为 —— hash -r 在 ksh 致命就包子 shell 探针,local 在 ksh 行为怪就拆两行,setopt shwordsplit 在 zsh 才需要就 nvm_is_zsh 探测

13. 写在最后#

读 nvm 之前,我对”版本管理工具”的认知停留在”装个 daemon + 改环境变量”。

读完之后我才意识到:nvm 用 5642 行 shell 实现了”完整可控的版本切换”这件事,本质上是因为它选择了一个非常受限的解空间——只改 shell 自己的状态,不动文件系统、不装二进制、不开 daemon。这个限制反而逼出了一套极简、极透明、极好调试的设计。

如果你写过 shell 工具但没读过 nvm,强烈建议翻一下 nvm.sh 的 3869-4500 行(nvm() 主函数 + install 分支),大概 600 行,就能把”跨 shell 兼容性 + 命令路由 + 参数解析 + 进度显示 + 副作用管理”这一整套基础设施学到手。

14. 仓库信息(可一键复现)#

# 仓库
https://github.com/nvm-sh/nvm
git clone https://github.com/nvm-sh/nvm.git
# 当前版本 v0.40.8(2026-10 还在维护,12 年没断更)

# 关键文件
nvm.sh          # 5642 行,主逻辑
install.sh      # 536 行,首次安装
nvm-exec        # 21 行,无副作用执行器
bash_completion # 110 行,bash/zsh 补全
AGENTS.md       # 17K,AI agent 友好指南
test/           # 6 套测试 + urchin 框架

# 一些实用的核数调试
bash -c "source nvm.sh && nvm --version"
NVM_DEBUG=1 bash -c "source nvm.sh && nvm use 18"   # 看详细错误
bash --noprofile --norc -c 'source ./nvm.sh --no-use; nvm ls-remote'   # 干净环境跑

参考:

• nvm README ↗ —— 58KB,使用文档典范
• nvm DESIGN NOTES ↗ —— 设计动机
• Tim Caswell 2012 起源演讲 ↗ —— 12 年前的思路
• Node 官方 dist/index.tab ↗ —— nvm 远程版本的来源