nvm 安装与使用教程：轻松管理你的 Node.js 版本 – wiki基地

作者： /

轻松管理你的 Node.js 版本：nvm 安装与使用全攻略

作为前端或后端开发者，我们经常会遇到这样的情况：不同的项目需要依赖不同版本的 Node.js。一个项目可能还在使用 Node.js 14，而另一个新项目却要求 Node.js 18 或更高版本。手动切换 Node.js 版本不仅繁琐，还容易出错，甚至可能导致依赖冲突和奇怪的问题。这时，一个强大的 Node.js 版本管理器就显得尤为重要。

而 nvm (Node Version Manager) 正是这样一个专为解决 Node.js 版本管理痛点而生的工具。它能让你在同一台机器上轻松安装、切换、管理多个 Node.js 版本，让你的开发环境保持整洁有序。

本文将为你提供一份详细的 nvm 安装与使用教程，带你从零开始掌握 nvm，轻松玩转 Node.js 版本管理。

第一部分：认识 nvm – 为什么我们需要它？

在深入学习如何使用 nvm 之前，我们先来理解一下为什么 nvm 如此受欢迎，它解决了哪些实际问题。

1. 版本冲突的噩梦：

假设你正在维护两个项目：
* 项目 A 使用了某个库，该库只兼容 Node.js 14.x 版本。
* 项目 B 是一个新项目，使用了许多新特性，推荐或强制要求使用 Node.js 18.x 版本。

如果你只在系统上全局安装了一个 Node.js 版本（例如 Node.js 18），当你尝试在项目 A 中运行 npm install 或启动项目时，可能会遇到依赖安装失败、运行时错误等问题，因为你当前 Node.js 版本与项目 A 的要求不符。反之，如果你安装了 Node.js 14，则无法正常开发项目 B。

2. 频繁的手动切换：

没有版本管理器时，你可能需要：
* 卸载当前 Node.js 版本。
* 下载并安装另一个 Node.js 版本。
* 可能还需要重新全局安装一些常用的 npm 包。

这个过程耗时且容易出错，尤其是在需要在多个项目之间频繁切换时。

3. 测试不同版本：

有时，为了确保你的代码在不同 Node.js 版本下都能正常工作，或者为了排查特定版本下的 bug，你需要快速切换到不同的 Node.js 环境进行测试。手动管理会使这个过程变得异常复杂。

nvm 的优势：

nvm 的出现完美解决了这些问题：

  • 轻松安装多版本： 只需一条命令，即可下载并安装任意你需要的 Node.js 版本。
  • 快速切换： 在不同版本之间切换只需一条简单的命令，瞬间完成。
  • 设置默认版本： 可以指定一个默认的 Node.js 版本，在新开的终端窗口中自动使用。
  • 项目级版本管理： 通过 .nvmrc 文件，可以为每个项目指定特定的 Node.js 版本，进入项目目录时自动切换。
  • 独立环境： 每个 Node.js 版本安装在 nvm 的独立目录下，互相隔离，互不影响。每个版本下安装的全局 npm 包也是独立的。
  • 卸载方便： 不再需要的版本可以轻松卸载。

简而言之，nvm 让 Node.js 版本管理变得前所未有的简单和高效，是现代 Node.js 开发不可或缺的工具。

重要提示： nvm 是专为 macOS 和 Linux 系统设计的。如果你是 Windows 用户，官方的 nvm 不支持你。你需要寻找 Windows 上的替代品，最常用且功能类似的工具是 nvm-windows。本文主要介绍 macOS/Linux 上的官方 nvm。

第二部分：nvm 的安装步骤

安装 nvm 通常非常简单，只需要运行一个官方提供的安装脚本即可。安装脚本会将 nvm 克隆到你的用户目录下，并自动配置你的 shell 配置文件，以便在启动终端时加载 nvm。

前提条件：

  • 一个 macOS 或 Linux 操作系统。
  • 可以访问终端或命令行。
  • 系统已安装 curl 或 wget 命令（通常系统自带）。

安装方法 (推荐使用 curl)：

打开你的终端，运行以下命令：

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

注意： v0.39.5 是当前（撰写本文时）最新的稳定版本号，建议你去 nvm 的 GitHub 仓库 (https://github.com/nvm-sh/nvm) 查看最新的版本号，并替换命令中的版本号，以安装最新版本。通常，访问 GitHub 页面后，首页就会有最新的安装命令示例。

安装方法 (使用 wget)：

如果你习惯使用 wget，也可以运行以下命令：

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

同样，建议检查并使用最新的版本号。

安装脚本的作用：

这个安装脚本会执行以下操作：

  1. 将 nvm 仓库克隆到 ~/.nvm 目录下（这是默认位置，可以通过设置 NVM_DIR 环境变量来改变）。
  2. 尝试检测你当前使用的 shell（bash, zsh, ksh, dash 等）。

  3. 在你的 shell 配置文件（如 ~/.bashrc, ~/.zshrc, ~/.profile, 或 ~/.bash_profile 等，取决于你的系统和配置）中添加几行配置代码，用于在终端启动时加载 nvm。这些代码通常看起来像这样：

    bash
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
    [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
    * export NVM_DIR="$HOME/.nvm"：设置 nvm 的安装目录。
    * [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"：检查 nvm.sh 文件是否存在且非空，如果存在，则 source（加载并执行）它。这是 nvm 核心功能的加载。
    * [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"：加载 nvm 的 bash 补全脚本，这样你在输入 nvm 命令时可以使用 Tab 键进行命令或版本号的自动补全。

安装完成后的操作：

安装脚本运行完成后，它会提示你关闭并重新打开你的终端窗口，或者运行 source ~/.bashrc (或对应的配置文件) 命令，以便让这些新的配置生效。

强烈建议你直接关闭当前终端窗口，然后重新打开一个新的终端窗口。 这样可以确保所有环境变量和配置都被正确加载。

验证安装：

重新打开终端后，运行以下命令来验证 nvm 是否安装成功：

bash
command -v nvm

如果安装成功，这个命令应该输出 nvm。如果你看到 command not found: nvm 或者没有输出，说明安装失败或配置没有正确加载。

你还可以运行以下命令来查看 nvm 的版本号：

bash
nvm --version

如果成功输出了版本号（例如 0.39.5），那么恭喜你，nvm 已经成功安装并准备就绪了！

常见安装问题及解决：

  • command not found: nvm：
    • 原因： nvm 的配置没有被正确加载到当前的 shell 会话中。
    • 解决：
      • 确保你已经关闭并重新打开了终端窗口。
      • 检查你的 shell 配置文件（如 ~/.bashrc, ~/.zshrc 等）中是否包含了安装脚本添加的那几行 nvm 配置代码。有时候安装脚本可能检测不到正确的配置文件，你需要手动将那几行代码添加到你的主要配置文件中。
      • 如果你不确定哪个是主要配置文件，可以尝试将代码添加到 ~/.profile 或 ~/.bash_profile 中。
      • 手动 source 配置文件：source ~/.bashrc (替换成你的实际配置文件)。
  • 安装过程中出现错误：
    • 原因： 网络问题导致下载失败，或者文件权限问题。
    • 解决：
      • 检查网络连接。
      • 确保你的用户对 ~ 目录有写入权限。
      • 尝试使用不同的安装方法（curl 或 wget）。
      • 访问 nvm 的 GitHub 仓库查看是否有已知的兼容性问题或安装指南。
  • nvm 目录权限问题：
    • 原因： 极少数情况下，~/.nvm 目录或其子目录权限不正确。
    • 解决： 可以尝试删除 ~/.nvm 目录（如果之前安装失败残留）后重新安装，或者使用 chmod 命令修复权限，但这通常不是必要步骤。

第三部分：nvm 的核心使用教程

nvm 的使用主要通过一系列 nvm 开头的命令来完成。下面是 nvm 最常用和核心的命令及其使用方法。

1. 查看已安装的 Node.js 版本：

bash
nvm ls

或简写：

bash
nvm list

执行这个命令会列出你当前通过 nvm 安装的所有 Node.js 版本。

输出示例：

v14.17.6
-> v16.13.0
v18.12.0
system
default -> 16.13.0 (-> v16.13.0)
node -> stable (-> v18.12.0) (default)
iojs -> N/A (0.12.4)
unstable -> N/A (0.12.4)
lts/* -> lts/hydrogen (-> v18.12.0)
lts/argon -> v1.8.4 (-> 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.21.3 (-> N/A)
lts/gallium -> v16.20.2 (-> N/A)
lts/hydrogen -> v18.18.2 (-> N/A)
lts/iron -> v20.11.0 (-> N/A)

  • -> 符号：表示当前正在使用的 Node.js 版本。
  • system：表示系统自带的 Node.js 版本（如果安装了的话）。
  • default: 指示通过 nvm alias default <version> 命令设置的默认版本。
  • node, lts/* 等：是 nvm 内置或用户自定义的别名。

2. 查看可用的 Node.js 版本 (远程仓库)：

bash
nvm ls-remote

这个命令会列出所有可以安装的 Node.js 版本，包括 LTS (长期支持) 版本和非 LTS 版本。列表可能很长。

输出示例 (部分):

...
v14.21.3 (LTS: Fermium)
v15.0.0
v15.0.1
...
v16.0.0
...
v16.20.2 (LTS: Gallium)
...
v18.0.0
...
v18.18.2 (LTS: Hydrogen)
...
v20.0.0
...
v20.11.0 (LTS: Iron)
...

你可以根据这个列表选择你想要安装的特定版本。

3. 安装指定版本的 Node.js：

bash
nvm install <version>

将 <version> 替换为你想要安装的 Node.js 版本号。

常用参数：

  • 安装特定版本号：nvm install 18.12.0
  • 安装最新的 LTS (长期支持) 版本：nvm install lts/*
  • 安装某个特定 LTS 系列的最新版本 (例如 Hydrogen 系列)：nvm install lts/hydrogen
  • 安装最新的稳定版本：nvm install node (这是 lts/* 的别名，通常指向最新的 LTS 版本)

示例：

bash
nvm install 14.17.6 # 安装 Node.js 14.17.6
nvm install 18.12.0 # 安装 Node.js 18.12.0
nvm install lts/* # 安装最新的 LTS 版本

安装完成后，nvm 会自动将新安装的版本切换为当前使用的版本。

4. 切换 Node.js 版本：

bash
nvm use <version>

将 <version> 替换为你想要切换到的 Node.js 版本号或别名。

示例：

bash
nvm use 18.12.0 # 切换到 Node.js 18.12.0
nvm use 14.17.6 # 切换到 Node.js 14.17.6
nvm use lts/gallium # 切换到 Gallium 系列的最新 LTS 版本
nvm use system # 切换回系统自带的 Node.js 版本 (如果存在)

重要提示： nvm use <version> 命令只对当前的终端会话生效。如果你关闭终端并重新打开，或者打开一个新的终端窗口，它会使用你设置的默认版本（或者如果未设置，则不会加载任何 nvm 管理的版本，除非你在配置文件中手动指定）。

5. 设置默认 Node.js 版本：

为了避免每次打开新终端都要手动 nvm use，你可以设置一个默认版本。

bash
nvm alias default <version>

将 <version> 替换为你希望设置为默认的 Node.js 版本号或别名。

示例：

bash
nvm alias default 18.12.0 # 将 18.12.0 设置为默认版本
nvm alias default lts/* # 将最新的 LTS 版本设置为默认版本

设置完成后，新打开的终端窗口将自动加载并使用这个默认版本。

6. 查看当前正在使用的 Node.js 版本：

bash
nvm current

这个命令会输出当前终端会话正在使用的 Node.js 版本号。

7. 卸载 Node.js 版本：

如果你不再需要某个 Node.js 版本，可以使用以下命令将其卸载：

bash
nvm uninstall <version>

将 <version> 替换为你想要卸载的 Node.js 版本号。

注意： 你不能卸载当前正在使用的 Node.js 版本。如果需要卸载当前版本，请先切换到另一个版本再进行卸载。

示例：

bash
nvm uninstall 14.17.6 # 卸载 Node.js 14.17.6

第四部分：nvm 的高级使用和技巧

除了基本的安装、切换、卸载功能，nvm 还提供了一些高级功能，可以进一步提升你的开发效率。

1. 使用 .nvmrc 文件进行项目级版本管理：

这是一个非常实用的功能。你可以在项目的根目录下创建一个名为 .nvmrc 的文件，并在其中指定该项目需要使用的 Node.js 版本号或别名。

创建 .nvmrc 文件：

在项目根目录创建 .nvmrc 文件，文件内容就是你想要使用的版本号，例如：

16.13.0

或者使用别名：

lts/gallium

或者：

node

如何使用 .nvmrc：

当你进入包含 .nvmrc 文件的项目目录后，只需运行 nvm use 命令（不带任何参数）。nvm 会自动检测 .nvmrc 文件，并切换到其中指定的 Node.js 版本。如果该版本尚未安装，nvm 会提示你是否安装。

示例：

  1. 在一个项目目录中创建 .nvmrc 文件，内容为 18.12.0。
  2. 打开终端，cd 进入该项目目录。
  3. 运行 nvm use。
  4. 如果 18.12.0 未安装，nvm 会询问是否安装。如果已安装，nvm 会直接切换到 18.12.0 版本。
  5. 运行 node -v 验证当前版本是否已切换到 18.12.0。

一些 shell 配置 (如 Oh My Zsh 的 nvm 插件) 甚至可以配置成在进入目录时自动读取 .nvmrc 并切换版本，无需手动运行 nvm use。你可以搜索你的 shell 配置相关的 nvm 插件来实现自动化。

2. 在新版本中重装旧版本的全局 npm 包：

当你安装一个新的 Node.js 版本时，通常在该版本下没有之前版本中全局安装的 npm 包。如果你希望在新版本中拥有与旧版本相同的全局包，可以在安装时使用 --reinstall-packages-from 标志。

bash
nvm install <new_version> --reinstall-packages-from=<old_version>

这个命令会安装 <new_version>，然后尝试在新版本下重新安装你在 <old_version> 中全局安装的所有包。

示例：

假设你之前经常使用 Node.js 16.13.0，并且全局安装了一些工具（如 nodemon, yarn, vue-cli 等）。现在你想安装 Node.js 18.12.0 并使用这些全局工具：

bash
nvm install 18.12.0 --reinstall-packages-from=16.13.0

nvm 会安装 18.12.0，然后读取 16.13.0 版本下的全局包列表，并在 18.12.0 环境下尝试重新安装它们。

3. 管理别名：

除了默认别名 default，你还可以创建自定义别名，方便快速切换到特定版本。

bash
nvm alias <name> <version>

示例：

bash
nvm alias my-stable-node 16.13.0
nvm alias project-a 14.17.6

现在，你可以使用 nvm use my-stable-node 或 nvm use project-a 来快速切换。

要删除别名，使用：

bash
nvm unalias <name>

4. 查看某个 Node.js 版本下的全局 npm 包：

当切换到某个 Node.js 版本后，你可以使用标准的 npm 命令来查看该版本下的全局包：

bash
npm list -g --depth=0

这将列出当前 Node.js 版本下所有直接安装的全局 npm 包。

5. Shell 补全：

如果安装脚本成功为你配置了 shell 补全，你可以在终端中输入 nvm 后按两次 Tab 键，或者输入 nvm use 后按两次 Tab 键，nvm 会提示你可用的命令或已安装的版本列表，非常方便。

6. 解决权限问题 (npm install -g):

使用 nvm 安装 Node.js 版本时，npm 的全局安装目录通常会设置在 nvm 管理的当前版本目录下（例如 ~/.nvm/versions/node/v18.12.0/lib/node_modules），这个目录是你的用户有写入权限的。因此，在使用 npm install -g <package> 安装全局包时，通常不需要使用 sudo。

如果你发现使用 npm install -g 仍然需要 sudo 或遇到权限错误，这可能意味着你的 npm 配置或 nvm 安装目录权限有问题。检查 ~/.nvm 及其子目录的权限，确保你的用户有写入权限。通常情况下，标准的 nvm 安装不会引入 sudo 问题。

第五部分：常见问题及故障排除

尽管 nvm 使用起来非常方便，但在某些情况下，你可能会遇到一些小问题。以下是一些常见问题及其解决方案：

  • command not found: nvm (同安装问题)：
    • 解决： 最常见的原因是 shell 配置文件没有正确加载 nvm。确保 ~/.bashrc, ~/.zshrc (或其他你的 shell 使用的配置文件) 中包含了 nvm 的加载代码，并且在修改后 source 了配置文件或重新打开了终端。使用 echo $NVM_DIR 检查 NVM_DIR 环境变量是否设置正确 (~/.nvm)。
  • nvm use <version> 切换后，新开的终端又回去了：
    • 解决： nvm use 只影响当前会话。如果你希望新开的终端默认使用某个版本，需要使用 nvm alias default <version> 命令来设置默认版本。
  • 安装 Node.js 版本时速度很慢或失败：
    • 原因： 网络问题或下载源不稳定。
    • 解决： Node.js 的下载源通常是 https://nodejs.org/dist/。你可以尝试设置环境变量来使用国内的镜像源，例如淘宝或华为云的 Node.js 镜像。
      bash
      # 添加到你的shell配置文件 (例如 ~/.bashrc 或 ~/.zshrc)
      export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
      # 或华为云镜像
      # export NVM_NODEJS_ORG_MIRROR=https://mirrors.huaweicloud.com/nodejs/
      修改后记得 source 配置文件或重新打开终端。
  • 安装特定版本时提示找不到版本：
    • 原因： 你输入的版本号不正确，或者该版本号在 Node.js 官方仓库中不存在。
    • 解决： 使用 nvm ls-remote 命令查看所有可用的版本号，确保你输入的版本号是准确的。
  • 安装 Node.js 时编译失败 (通常出现在非常旧的版本或从源码安装时)：
    • 原因： 安装脚本默认会下载预编译的二进制文件，但如果找不到对应的二进制文件，它会尝试从源码编译。源码编译 Node.js 需要系统安装 C++ 编译器、Python 等构建工具。
    • 解决： 确保你的系统安装了必要的构建依赖。在基于 Debian/Ubuntu 的系统上，可以尝试安装 build-essential 和 libssl-dev。在基于 Red Hat/CentOS 的系统上，可能需要安装 Development Tools 和 openssl-devel。不过对于大多数常用的、非老旧的 Node.js 版本，nvm 都可以直接下载预编译的二进制文件，很少会遇到编译问题。
  • .nvmrc 文件不生效：
    • 原因： 可能是 .nvmrc 文件路径不对 (必须在项目根目录)，文件名写错，或者文件内容格式不对 (只包含版本号)。
    • 解决： 检查文件名、文件内容和文件位置。确保你在该目录下运行了 nvm use 命令 (或者你的 shell 配置支持自动读取 .nvmrc)。

第六部分：nvm 与其他版本管理工具的比较 (简述)

虽然本文专注于 nvm，但了解一下其他版本管理工具也很有帮助。

  • n： 另一个流行的 Node.js 版本管理工具，使用 npm 全局安装 (npm install -g n)。它的命令相对更简洁，但通常需要 sudo 权限来安装和管理 Node.js 版本，这有时会被认为不够安全或方便。nvm 通常安装在用户目录下，避免了 sudo 的使用。
  • fnm (Fast Node Manager)： 一个用 Rust 编写的 Node.js 版本管理器，强调速度和简单性。它也支持 .nvmrc 文件。对于追求速度或喜欢 Rust 生态的开发者来说，fnm 是一个不错的选择。
  • nvm-windows： 如前所述，这是 Windows 平台上最接近官方 nvm 功能的替代品。如果你使用 Windows，请搜索并使用 nvm-windows。

选择哪个工具取决于个人偏好和所使用的操作系统。对于 macOS 和 Linux 用户，nvm 是最老牌、最成熟、社区支持最广泛的选择。

总结

通过本文的学习，你应该已经掌握了 nvm 的安装方法以及最常用的功能。从安装、切换不同版本，到设置默认、使用 .nvmrc 进行项目级管理，再到处理全局包和常见问题，nvm 极大地简化了 Node.js 版本的管理工作。

告别手动切换版本的烦恼，拥抱 nvm 带来的便捷高效开发体验吧！现在就开始在你的终端中尝试使用 nvm，感受它为你带来的改变。祝你 Node.js 开发愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部