Node.js 版本管理：macOS、Linux、WSL 与 Windows

📅 2020-12-23 📂 工具 🏷️ Node.js, nvm, nvm-windows, macOS, 开发环境
6 分钟阅读 · 1,541 字

Node.js 项目可能要求不同运行时版本。版本管理器用于按项目/终端切换 Node，不会替代仓库对版本、包管理器和 lockfile 的约定。先读 README、engines、.nvmrc/.node-version、packageManager 和 CI 配置，再选择管理器；不要仅因为另一项目使用 nvm 就在当前电脑再装一套。

1. 先盘点当前 Node 来源

node --version
npm --version
command -v node
command -v npm
which -a node

macOS/Linux 中，command -v 是 POSIX shell 常见命令；Windows PowerShell 使用 Get-Command node -All。PATH 可能同时包含系统安装、Homebrew、nvm、Volta、fnm 或 IDE 自带路径。若结果指向意料之外的位置，先修正 PATH 顺序与 shell 配置，不要立刻卸载或删除目录。

2. POSIX nvm 适用平台

上游 nvm-sh/nvm 是按用户、按 shell 加载的 POSIX shell 脚本，适用于 macOS、Linux 和 WSL；它不是原生 Windows PowerShell 程序。若使用 WSL，应在 WSL Linux 家目录安装并在 WSL 项目目录中运行，不要把 Windows 与 WSL 的 node_modules/全局包目录混用。

macOS 需要可用的 Git/Xcode Command Line Tools。安装前先从上游仓库核对当前稳定版本；若按官方脚本安装，下载固定版本脚本到本地审阅后再执行，而不是对来历不明的地址运行 curl | bash：

curl -fsSLo /tmp/nvm-install.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh
less /tmp/nvm-install.sh
bash /tmp/nvm-install.sh

版本号是示例快照，执行前要确认上游当前 release、下载校验与组织策略；审阅后再运行脚本。官方安装器通常把 nvm 放入 ~/.nvm，并尝试配置正确的 shell profile。zsh 用户检查 ~/.zshrc 是否包含 NVM 初始化；登录 shell、交互 shell 与 VS Code 集成终端读取的文件可能不同。重新打开终端后运行 command -v nvm，不能只看安装器的 success 输出。

3. 使用项目版本文件

先让仓库维护者选择版本，并提交精确、可复现的 .nvmrc 内容，例如：

24.10.0

这里的版本只作格式示例，项目应选择仍受支持且经过 CI 验证的 Node release。进入仓库后先检查版本文件，再按需安装和切换：

cat .nvmrc
nvm install
nvm use
node --version
npm --version

如果仓库没有 .nvmrc，不要自行编造版本；参考 engines、锁定的包管理器、CI matrix 和项目文档。需要安装 LTS 时用 nvm install --lts 并核对实际版本。切换后确认 node --version 与项目要求一致，再安装依赖。可用 nvm alias default <version> 设置新终端默认版本；不要把个人默认值写成团队版本承诺。

可选的目录自动切换应谨慎配置：目录进入/退出钩子会修改当前 shell 的 PATH，可能影响启动速度、嵌套终端和 GUI。先掌握显式 nvm use，再依据 nvm 官方 zsh/bash 文档实现自动切换。

4. Node/npm 全局包和权限

nvm 管理的每个 Node 版本有自己的 npm 与全局包目录。切换 Node 后，旧版本的 eslint、typescript 等全局命令可能消失，这是版本隔离的正常结果。项目 CLI 优先作为开发依赖安装并通过 package script 调用；确实需要个人全局 CLI 时，按版本迁移并记录来源：

nvm current
npm prefix -g
npm ls -g --depth=0

不要在 nvm 环境下使用 sudo npm install -g，也不要把 npm global prefix 固定到另一个 Node 管理器的目录。认证和 registry token 按 registry scope 配置，不写进 shell history、项目 .npmrc 或公开文档。

5. Windows 选择独立实现

原生 Windows PowerShell 不支持 nvm-sh/nvm。常见选择是 nvm-windows 或其他 Windows Node 版本管理器；它们与 POSIX nvm 是不同项目，配置、命令、shim/链接模式和升级方式各异。nvm-windows 当前已有 v2 代际，旧版 nvm-noinstall.zip、手工挪动 settings.txt 或旧镜像配置不应再当成通用安装步骤。

从官方项目页面进入其当前安装与迁移文档，确认安装器签名、版本代际、Node 下载来源和是否需要管理员权限。不同版本/模式的权限要求可能不同；不要同时装独立 Node MSI 和多个管理器争用同一个 node.exe shim。安装或迁移后在新 PowerShell 窗口运行官方文档对应的版本/list/use 命令，再用 Get-Command node -All 验证实际路径。

6. 常见故障排查

  1. nvm: command not found：检查安装目录、shell profile 是否被当前终端读取；zsh 检查 .zshrc，随后新开终端验证；
  2. node 版本没变化：运行 which -a node 或 PowerShell Get-Command node -All，找出 PATH 前面的旧安装；
  3. npm 全局命令丢失：确认当前 Node 版本与 npm prefix -g，不要拷贝另一个版本的 node_modules；
  4. 镜像下载失败：先检查官方 release、代理、证书与网络策略，不要把已退役域名或 HTTP 地址写入长期配置；
  5. IDE 与系统终端版本不同：检查 GUI 启动时继承的 PATH、登录 shell 和 VS Code Terminal Profile，而非反复重装 Node。

7. 换机和团队约定

  • 一个工作环境只保留一套主 Node 版本管理器；若有例外，文档写清 PATH 与目录边界；
  • 仓库提交 .nvmrc/.node-version 和 packageManager，并在 CI 对同一版本做验证；
  • 选择受支持的 Node release，定期由维护者升级，不把 latest 当成可复现版本；
  • 新电脑先安装 Git 与一种版本管理器，再按项目版本安装 Node；全局包逐个审查，不复制整个用户目录；
  • 更换管理器前记录 which -a node、全局包和 registry 配置，迁移后验证项目 build/test 再移除旧路径。

官方资料：nvm-sh/nvm 安装和使用、nvm-windows、nvm-windows 文档、Node.js 发布计划。不同系统实现不能互换命令；下载地址、版本和权限要求以各自官方文档为准。

Live Notes

读者弹幕

留言提交后会先进入审核，审核通过后对其他读者公开。