Refine 项目实战：NVM（Node Version Manager）完整安装与使用指南

Refine 项目实战：NVM（Node Version Manager）完整安装与使用指南

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine

导读

多项目并行开发时，Node.js 版本不一致往往是"测试突然失败""依赖编译报错"的隐形元凶。本指南以 Node Version Manager（nvm）为核心，完整讲解其在 Linux/macOS/Windows 上的安装方式、版本安装与切换命令、.nvmrc自动化切换、以及与 VS Code、Docker 等开发工具的集成方法。读完本文，你将能在同一台机器上自由管理任意数量的 Node.js 版本，并结合本仓库（Refine 源码仓库）的实际工程配置，理解项目级 Node 版本声明的正确姿势。

为什么需要 nvm

Node.js 自 2009 年 5 月首次发布以来，彻底改变了软件开发生态：JavaScript 不再局限于浏览器，移动端、桌面端、服务端都可以用同一种语言构建。但随着版本迭代，一个现实问题随之而来——不同的项目往往要求不同的 Node.js 版本。

一个典型的场景是：你本地运行 Node 16.17.0，而某个项目的测试代码是在 Node 14.18.1 环境下编写的。直接运行可能会遇到 V8 buffer overflow 之类的底层错误，大量测试用例失败。排查半天才发现，问题根源只是 Node 版本不一致。

如果靠手动下载、卸载、重装 Node.js 来切换版本，既耗时又容易把环境搞乱。nvm（Node Version Manager）正是为了解决这个问题而生的版本管理工具：它只负责安装、管理和切换Node 版本，不会删除任何已安装版本，需要时随时一键切换。

认识nvm use：最核心的切换命令

nvm 最常用的命令是use，用于切换当前终端会话的 Node 版本：

nvm use 14.18.0

假设当前版本是 16.0.1：

node --v 16.0.1

执行nvm use 14.18.0后，再次确认版本：

node -v 14.18.0

版本已成功切换到 14.18.0。值得注意的是，use只影响当前终端会话，关闭终端后会自动回到默认版本。

安装 nvm

Linux / macOS：curl 或 wget 一行搞定

在类 Unix 系统上，最便捷的安装方式是直接运行官方安装脚本：

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

或者使用 wget：

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

上述命令会下载install.sh脚本并立即执行。脚本内部会完成两件事：

1. 将 nvm 仓库克隆到用户主目录下的.nvm目录；
2. 将以下配置片段追加到~/.bash_profile、~/.zshrc、~/.profile或~/.bashrc之一，确保每次打开终端都能加载 nvm：

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" # This loads nvm

从脚本可见，nvm 本质上是一个 bash 脚本库：NVM_DIR指定安装目录（默认~/.nvm，若设置了XDG_CONFIG_HOME则安装到$XDG_CONFIG_HOME/nvm），随后通过 source 加载nvm.sh完成函数注册。

Windows：使用 nvm-windows

Windows 与上面的安装方式完全不同，需要使用独立的nvm-windows工具。需要特别提醒：nvm-windows 与 nvm 并非同一个项目，二者 API 相似但实现和社区不同。nvm-windows 是 Windows 平台上被推荐的 Node.js 版本管理器，从其官方发布页下载最新 release 安装包即可完成安装，升级与更多细节以该项目仓库说明为准。

验证安装

安装完成后，重新打开一个终端，运行：

nvm -v

即可看到当前 nvm 的版本号，例如：

Node Version Manager (v0.35.3) Note: <version> refers to any version-like string nvm understands. This includes: - full or partial version numbers, starting with an optional "v" (0.10, v0.1.2, v1) - default (built-in) aliases: node, stable, unstable, iojs, system - custom aliases you define with `nvm alias foo` Any options that produce colorized output should respect the `--no-colors` option.

这段输出也提示了 nvm 版本参数的灵活语法：既可以是完整版本号（14.18.1），也可以是带v前缀或只写大版本（14、v1），还可以使用内置别名node、stable、unstable、iojs、system，或自定义别名。更多校验手段可参考仓库内另一篇配套博文 How to Change Node Version，其中介绍了command -v nvm、nvm current等验证方式。

安装指定 Node 版本

安装某个具体版本：

nvm install 10.1.0

这条命令只负责把 Node.js v10.1.0 安装到机器上，不会移除已有的 v14——多个版本可以共存。安装更多版本同理：

nvm install 11.2.1 nvm install 16.2.3

安装最新版 Node：

nvm install node

node是一个内置别名，指向最新的稳定版本。如果只指定大版本号，nvm 会自动安装该大版本下的最新版本：

nvm install 10

例如当 v10 系列最新版为 10.19.0 时，上面命令安装的就是 10.19.0。

切换 Node 环境

通过use命令在已安装的版本之间切换：

nvm use 14 nvm use 12.0.1

前提是目标版本必须先安装过，否则切换会失败。

需要注意use的版本匹配规则：如果只写大版本号（如nvm use 14），nvm 会忽略 minor 和 patch 版本，直接选用机器上该大版本号下最新安装的版本。例如本地同时存在14.17.1、14.18.0、14.18.1，那么nvm use 14会切换到14.18.1。

进阶用法：自动化版本切换

用.nvmrc实现目录级自动切换

手工nvm use仍然依赖开发者的记忆，更工程化的做法是使用.nvmrc文件：在项目根目录放置一个只写版本号的文件，nvm 读取后即可一键切换到对应版本，保证团队所有成员和 CI 环境使用完全一致的 Node 版本。

# 在项目根目录创建 .nvmrc 文件 echo "14.18.1" > .nvmrc # 切换到 .nvmrc 中指定的 Node 版本 nvm use

两步即可完成：第一步在项目根目录创建.nvmrc并写入目标版本号；第二步不带参数执行nvm use，nvm 会自动读取.nvmrc并切换。

这个实践在本仓库中也有真实对应物：Refine 仓库根目录的 package.json 通过engines字段声明了运行前提：

"engines": { "node": ">=18", "pnpm": ">=9" }, "packageManager": "pnpm@9.4.0+sha256.b6fd0bfda555e7e584ad7e56b30c68b01d5a04f9ee93989f4b93ca8473c49c74"

engines定义了仓库对 Node.js 与包管理器的版本下限，配合.nvmrc使用，即可做到"仓库声明版本 → nvm 自动切换到该版本 → 安装依赖"的标准化流程，避免因本机 Node 版本差异导致的构建或测试不一致。

与开发工具结合：VS Code 与 Docker

将 nvm 集成进日常开发工具，可以保证 IDE 终端与容器环境都使用正确的 Node 版本：

1. Visual Studio Code：修改 VS Code 设置，让集成终端以登录 shell 启动并加载 nvm 环境变量。例如在settings.json中：

{ "terminal.integrated.shellArgs.linux": ["-l"], "terminal.integrated.env.linux": { "NVM_DIR": "$HOME/.nvm", "PATH": "$NVM_DIR/versions/node/$(nvm version)/bin:$PATH" } }

这里通过-l（login shell）参数让终端启动时自动 source nvm 配置，同时把当前 nvm 版本对应的bin目录注入PATH，确保node/npm指向 nvm 托管的版本。

2. Docker：在容器镜像中安装 nvm 并按项目声明的 Node 版本构建，或在 Dockerfile 中显式指定与项目一致的 Node 基础镜像，避免容器内外的 Node 版本漂移。

在 Refine 仓库的文档中同样可以找到 nvm 路径与工具链配合的实证：CLI 包文档 在描述工具链检查时给出的示例路径即为~/.nvm/versions/node/v16.14.0/bin/node与~/.nvm/versions/node/v16.14.0/bin/npm，这说明 nvm 统一把各版本 Node 安装到~/.nvm/versions/node/<version>/目录下，工具链按该路径定位可执行文件即可实现版本隔离。

其他常用命令

nvm list：列出已安装版本

nvm list

示例输出：

v14.17.1 v14.18.1 v16.9.0 -> v16.17 system default -> node (-> v16.17.0) node -> stable (-> v16.17.0) (default) stable -> 16.17 (-> v16.17.0) (default) iojs -> N/A (default) unstable -> N/A (default) lts/* -> lts/gallium (-> v16.17.0) lts/argon -> v4.9.1 (-> N/A) lts/boron -> v6.17.1 (-> N/A) lts/carbon -> v8.17.0 (-> N/A) lts/dubnium -> v10.24.1 (-> N/A) lts/erbium -> v12.22.12 (-> N/A) lts/fermium -> v14.20.0 (-> N/A) lts/gallium -> v16.17.0

输出会列出所有已安装版本、当前版本（用->箭头标记）、默认别名（default），以及所有 LTS（长期支持）版本映射。配套博文 How to Change Node Version 还补充了nvm ls-remote（列出所有可安装的远端版本）与nvm current（显示当前会话生效版本）两个实用命令。

nvm uninstall：卸载指定版本

与install对应的逆操作：

nvm uninstall 13.10.1

该命令会把本机已安装的 Node.js 13.10.1 完整移除。

nvm run：临时用指定版本执行脚本

不切换当前版本，直接用某个 Node 版本运行脚本：

nvm run 6.10.3 app.js

内部逻辑是：先用 6.10.3 执行app.js，执行完毕后自动切回原来的版本。适合临时验证脚本在某个旧版本下的行为，无需破坏当前环境。

NVM 最佳实践

保持 NVM 与 Node 版本常新

安全、性能和新特性都要求定期更新 NVM 与 Node 版本：

• 定期升级 NVM 本体；
• 新项目一律使用最新稳定版 Node；
• 定期检查既有项目的 Node 版本，满足兼容与安全要求。

# 更新 NVM 内置 npm 相关工具 nvm install-latest-npm # 安装最新版 Node nvm install node # 升级既有版本并迁移全局包 nvm install 14.18.1 --reinstall-packages-from=14.17.0

其中--reinstall-packages-from是非常实用的迁移参数：升级到新版本的同时，把旧版本下安装的全局 npm 包原样重装到新版本中。

针对不同环境利用 NVM

开发、测试、生产环境往往需要不同的 Node 版本，NVM 让单机管理多套环境成为可能：

• 在每个项目目录放置.nvmrc声明所需 Node 版本；
• 配置基于任务的自动切换脚本；
• 在多个 Node 版本上分别运行测试，验证应用在各环境下的兼容性。

# 在项目根目录创建 .nvmrc 指定 Node 版本 echo "14.18.1" > .nvmrc # 切换到 .nvmrc 指定的版本 nvm use

仓库内另一篇教程 headless-blog-strapi-refine 展示了这类环境约束的真实案例：Strapi v4 不支持 Node 22+，因此教程明确建议用 nvm 切换到 Node 20：nvm install 20 && nvm use 20。这正是"不同工具链绑定不同 Node 版本"的典型实战。

管理全局包

不同 Node 版本拥有各自独立的全局 npm 包，做好全局包管理可以避免冲突并保持环境整洁：

• 为每个 Node 版本分别安装所需的全局包，实现环境相互隔离；
• 升级 Node 时使用--reinstall-packages-from迁移全局包；
• 定期审计并清理无用的全局包。

# 升级 Node 时重装全局包 nvm install 14.18.1 --reinstall-packages-from=14.17.0 # 列出当前 Node 版本下的全局包 npm list -g --depth=0 # 移除某个不再使用的全局包 npm uninstall -g package-name

结语

围绕"多版本 Node 共存与切换"这一核心痛点，nvm 提供了一套轻量而完整的解决方案：通过install/use/uninstall/run/list等命令管理版本生命周期；通过.nvmrc把版本声明固化到项目里，实现团队与 CI 的一致性；再通过与 VS Code、Docker 的集成，把正确的 Node 版本带到日常开发与容器环境中。配合--reinstall-packages-from等迁移特性，即使频繁升级 Node 也不会丢失全局工具链。

正如本仓库 package.json 的engines声明所示，一个规范的 Node 项目应当同时做到"仓库声明版本 + 本地 nvm 管理版本"，这样才能从根源上消除"我机器上跑得好好的，你那边怎么就报错"的版本类问题。

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine