nvm-sh/nvm 源码：https://github.com/nvm-sh/nvm # Node 版本管理器 [测试][3] [nvm 版本][4] CII 最佳实践（https://bestpractices.dev/projects/684） ## 目录 - 简介 - 关于 - 安装与更新 - 安装与更新脚本 - 附加说明 - 在 Docker 中安装 - 在 Docker 中为 CICD 任务安装 - Linux 上的故障排除 - macOS 上的故障排除 - Ansible - 验证安装 - 重要说明 - Git 安装 - 手动安装 - 手动升级 - 使用方法 - 长期支持 - 安装时迁移全局包 - 在已安装版本之间迁移全局包 - 离线安装 - 安装时从文件读取默认全局包 - io.js - 系统自带的 Node 版本 - 列出版本 - 设置自定义颜色 - 持久化自定义颜色 - 抑制彩色输出 - 恢复 PATH - 设置默认 node 版本 - 使用 node 二进制文件的镜像 - 向镜像传递 Authorization 请求头 - .nvmrc - 更深入的 Shell 集成 - 在包含 .nvmrc 文件的目录中自动调用 nvm use - bash - zsh - fish - 运行测试 - 环境变量 - Bash 补全 - 使用方法 - 兼容性问题 - 在 Alpine Linux 上安装 nvm - Alpine Linux 3.13+ - Alpine Linux 3.5 - 3.12 - 卸载 / 移除 - 手动卸载 - Docker 开发环境 - 问题 - macOS 故障排除 - WSL 故障排除 - 维护者 - 项目支持 - 企业支持 - 许可证 - 版权声明 ## 简介 nvm 允许你通过命令行快速安装和使用不同版本的 node（https://nodejs.org）。 示例： sh $ nvm install 24 Now using node v24.14.0 (npm v11.9.0) $ node -v v24.14.0 $ nvm use 22 Now using node v22.22.1 (npm v10.9.4) $ node -v v22.22.1 $ nvm use 20 Now using node v20.20.1 (npm v10.8.2) $ node -v v20.20.1 就是这么简单！ ## 关于 nvm 是 node.js（https://nodejs.org/en/）的版本管理器，设计为按用户安装，并按 shell 调用。 nvm 适用于任何符合 POSIX 标准的 shell（sh、dash（https://git.kernel.org/pub/scm/utils/dash/dash.git）、ksh（https://github.com/ksh93/ksh）、zsh（https://www.zsh.org）、bash（https://www.gnu.org/software/bash/）），尤其是在以下平台：unix、macOS（https://www.apple.com/macos/）和 Windows WSL（https://github.com/nvm-sh/nvm#important-notes）。 ## 安装与更新 ### 安装与更新脚本 要安装或更新 nvm，你应该运行[安装脚本][2]。 为此，你可以手动下载并运行该脚本，或者使用以下 cURL（https://curl.se）或 Wget（https://www.gnu.org/software/wget/）命令： sh curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash sh wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash 运行上述任一命令都会下载并执行一个脚本。该脚本会将 nvm 仓库克隆到 ~/.nvm，并尝试将下面片段中的 source 行添加到正确的配置文件（~/.bashrc、~/.bash_profile、~/.zshrc 或 ~/.profile）中。 如果你发现安装脚本更新了错误的配置文件，请将 $PROFILE 环境变量设置为配置文件的路径，然后重新运行安装脚本。 sh 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 #### 附加说明 - 如果存在环境变量 $XDG_CONFIG_HOME，则会将 nvm 文件放置在该目录下。 - 你可以在上述脚本末尾添加 --no-use 来延迟使用 nvm，直到你手动 use 它： sh 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" --no-use # This loads nvm, without auto-using the default version - 你可以使用 NVM_SOURCE、NVM_DIR、PROFILE 和 NODE_VERSION 变量自定义安装源、目录、配置文件和版本。例如：curl ... | NVM_DIR="path/to/nvm"。确保 NVM_DIR 不以斜杠结尾。 - 安装程序可以使用 git（https://git-scm.com/）、curl 或 wget 来下载 nvm，具体取决于哪个可用。 - 你可以通过设置 PROFILE=/dev/null 来指示安装程序不要修改你的 shell 配置（例如，如果你已经通过 zsh nvm 插件（https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/nvm）获得了补全功能）。以下是实现该操作的一行命令示例：PROFILE=/dev/null bash -c 'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash' #### 在 Docker 中安装 当 bash 以非交互式 shell 调用时（例如在 Docker（https://www.docker.com）容器中），常规的配置文件都不会被加载。为了像平常一样使用 nvm、node 和 npm（https://www.npmjs.com），你可以改为指定特殊的 BASH_ENV 变量，bash 在非交互式调用时会加载该变量。 Dockerfile # Use bash for the shell SHELL ["/bin/bash", "-o", "pipefail", "-c"] # Create a script file sourced by both interactive and non-interactive bash shells ENV BASH_ENV "${HOME}/.bash_env" RUN touch "${BASH_ENV}" RUN echo '. "${BASH_ENV}"' >> ~/.bashrc # Download and install nvm RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | PROFILE="${BASH_ENV}" bash RUN echo node > .nvmrc RUN nvm install ##### 在 Docker 中为 CICD 任务安装 更健壮的方式，适用于 CI/CD 任务。可以在交互式和非交互式容器中运行。参见 https://github.com/nvm-sh/nvm/issues/3531。 Dockerfile FROM ubuntu:latest ARG NODE_VERSION=20 # install curl RUN apt update && apt install curl -y # install nvm RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash # set env ENV NVM_DIR=/root/.nvm # install node RUN bash -c "source $NVM_DIR/nvm.sh && nvm install $NODE_VERSION" # set ENTRYPOINT for reloading nvm-environment ENTRYPOINT ["bash", "-c", "source $NVM_DIR/nvm.sh && exec \"$@\"", "--"] # set cmd to bash CMD ["/bin/bash"] 此示例默认安装 nodejs 20.x.y 版本。你也可以通过 docker build 参数轻松覆盖版本，例如： docker build -t nvmimage --build-arg NODE_VERSION=19 . 镜像创建完成后，你可以以交互方式启动容器并运行命令，例如： docker run --rm -it nvmimage root@0a6b5a237c14:/# nvm -v 0.40.6 root@0a6b5a237c14:/# node -v v19.9.0 root@0a6b5a237c14:/# npm -v 9.6.3 非交互式示例： user@host:/tmp/test $ docker run --rm -it nvmimage node -v v19.9.0 user@host:/tmp/test $ docker run --rm -it nvmimage npm -v 9.6.3 #### Linux 上的故障排除 在 Linux（https://www.kernel.org/）上，运行安装脚本后，如果你得到 nvm: command not found，或者输入 command -v nvm 后终端没有任何反馈，只需关闭当前终端，打开一个新终端，然后再次验证。 或者，你可以在命令行中对不同 shell 运行以下命令： bash：source ~/.bashrc zsh：source ~/.zshrc ksh：. ~/.profile 这些命令应该会让 nvm 命令生效。 #### macOS 上的故障排除 自 OS X 10.9 起，/usr/bin/git 已由 Xcode（https://developer.apple.com/xcode/）命令行工具预置，这意味着我们无法正确检测 Git 是否已安装。你需要在运行安装脚本之前手动安装 Xcode 命令行工具，否则脚本会失败。（参见 #1782（https://github.com/nvm-sh/nvm/issues/1782）） 如果运行安装脚本后得到 nvm: command not found，原因可能是以下之一： - 自 macOS 10.15 起，默认 shell 是 zsh，nvm 会查找 .zshrc 进行更新，但默认情况下该文件并不存在。使用 touch ~/.zshrc 创建一个，然后重新运行安装脚本。 - 如果你使用 bash（之前的默认 shell），你的系统可能没有 .bash_profile 或 .bashrc 文件，而命令需要写入这些文件。使用 touch ~/.bash_profile 或 touch ~/.bashrc 创建其中一个文件，然后重新运行安装脚本。之后运行 . ~/.bash_profile 或 . ~/.bashrc 以加载 nvm 命令。 - 你之前使用过 bash，但当前安装了 zsh。你需要手动将这些行添加到 ~/.zshrc 中，然后运行 . ~/.zshrc。 - 你可能需要重启终端实例或运行 . ~/.nvm/nvm.sh。重启终端/打开新标签页或窗口，或者运行 source 命令，都会加载该命令和新的配置。 - 如果上述方法无效，你可能需要重启终端实例。尝试在终端中打开一个新的标签页或窗口并重试。 如果上述方法仍不能解决问题，你可以尝试以下方法： - 如果你使用 bash，可能是你的 .bash_profile（或 ~/.profile）没有正确加载你的 ~/.bashrc。你可以通过向其添加 source ~/.bashrc 或按照下一步操作来修复。 - 尝试将安装部分中的片段（用于查找正确的 nvm 目录并加载 nvm）添加到你的常用配置文件（~/.bash_profile、~/.zshrc、~/.profile 或 ~/.bashrc）中。 - 有关此问题的更多信息和可能的解决方法，请参考这里（https://github.com/nvm-sh/nvm/issues/576） 注意 对于搭载 Apple Silicon 芯片的 Mac，node 自 v16.0.0 起开始提供 arm64 架构的 Darwin 包，并且自 v14.17.0 起支持从源码编译时的实验性 arm64 支持。如果你在使用 nvm 安装 node 时遇到问题，建议更新到这些版本或更高版本。 #### Ansible 你可以使用一个任务： yaml - name: Install nvm ansible.builtin.shell: > curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash args: creates: "{{ ansible_env.HOME }}/.nvm/nvm.sh" ### 验证安装 要验证 nvm 是否已安装，请执行： sh command -v nvm 如果安装成功，应该输出 nvm。 请注意，which nvm 不会起作用，因为 nvm 是一个被 source 的 shell 函数，而不是可执行的二进制文件。 注意： 在 Linux 上，运行安装脚本后，如果你得到 nvm: command not found，或者输入 command -v nvm 后终端没有任何反馈，只需关闭当前终端，打开一个新终端，然后再次验证。 ### 重要说明 如果你运行的系统没有预编译的二进制包可用，这意味着你将需要从源码安装 node 或 io.js（https://iojs.org），你需要确保系统装有 C++ 编译器。对于 OS X，Xcode 可以胜任；对于基于 Debian（https://www.debian.org）/Ubuntu（https://ubuntu.com）的 GNU/Linux，build-essential 和 libssl-dev 包可以胜任。 注意： nvm 在某些情况下也支持 Windows。它应该可以通过 WSL（适用于 Linux 的 Windows 子系统）工作，具体取决于 WSL 的版本。它也应该能通过 Git Bash（https://gitforwindows.org/）（MSYS（https://www.msys2.org/））或 Cygwin（https://cygwin.com）工作。 否则，对于 Windows，有几个替代方案，但这些方案既不受我们支持，也非我们开发： - nvm-windows（https://github.com/coreybutler/nvm-windows） - nodist（https://github.com/marcelklehr/nodist） - nvs（https://github.com/jasongin/nvs） 注意： nvm 也不支持 [Fish]（参见 #303（https://github.com/nvm-sh/nvm/issues/303））。存在一些替代方案，但这些方案既不受我们支持，也非我们开发： - bass（https://github.com/edc/bass）允许你在 fish shell 中使用为 Bash 编写的工具 - fast-nvm-fish（https://github.com/brigand/fast-nvm-fish）仅适用于版本号（不适用于别名），但不会显著减慢你的 shell 启动速度 - plugin-nvm（https://github.com/derekstavis/plugin-nvm）是 Oh My Fish（https://github.com/oh-my-fish/oh-my-fish）的插件，使 nvm 及其补全在 fish shell 中可用 - nvm.fish（https://github.com/jorgebucaran/nvm.fish）- 专为 Fish 打造、让你爱不释手的 Node.js 版本管理器 - fish-nvm（https://github.com/FabioAntunes/fish-nvm）- 为 fish 封装的 nvm，延迟加载 nvm，直到实际使用时才加载。 注意： 我们在 FreeBSD（https://www.freebsd.org）上仍然存在一些问题，因为没有官方的 FreeBSD 预编译二进制文件，而且从源码构建可能需要补丁（https://www.freshports.org/www/node/files/patch-deps_v8_src_base_platform_platform-posix.cc）；参见问题单： - [#900] [Bug] node on FreeBSD may need to be patched - nodejs/node#3716（https://github.com/nodejs/node/issues/3716） 注意： 在 OS X 上，如果你没有安装 Xcode 并且不想下载约 4.3GB 的文件，你可以安装 Command Line Tools。你可以看看这篇博客文章，了解如何做到： - How to Install Command Line Tools in OS X Mavericks & Yosemite (Without Xcode)（https://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/） 注意： 在 OS X 上，如果你已经安装了一个“系统”级别的 node，并希望全局安装模块，请记住以下几点： - 使用 nvm 时，你不需要 sudo 来通过 npm -g 全局安装模块，因此不要执行 sudo npm install -g grunt，而应执行 npm install -g grunt - 如果你有 ~/.npmrc 文件，请确保其中不包含任何 prefix 设置（这与 nvm 不兼容） - 你可以（但也许不应该？）保留之前“系统”级别的 node 安装，但 nvm 只对你的用户帐户（用于安装 nvm 的帐户）可用。这可能会导致版本不匹配，因为其他用户将使用 /usr/local/lib/node_modules/*，而你的用户帐户使用 ~/.nvm/versions/node/vX.X.X/lib/node_modules/*。 不支持 Homebrew（https://brew.sh）安装。如果你在使用 homebrew 安装的 nvm 时遇到问题，请在提交问题之前执行 brew uninstall，然后按照下面的说明进行安装。 注意： 如果你使用 zsh，你可以轻松地将 nvm 安装为 zsh 插件。安装 zsh-nvm（https://github.com/lukechilds/zsh-nvm）并运行 nvm upgrade 进行升级（你可以设置（https://github.com/lukechilds/zsh-nvm#auto-use）NVM_AUTO_USE=true 使其自动检测并使用 .nvmrc 文件）。 注意： v1.7 之前的 Git 版本可能无法通过 https 协议从 GitHub（https://github.com）克隆 nvm 源码，并且 v1.6 之前的 git 行为也有所不同，v1.17.10（https://github.com/git/git/commit/5a7d5b683f869d3e3884a89775241afa515da9e7）之前的 git 无法克隆标签，因此最低要求的 git 版本是 v1.7.10。如果你对我们这里提到的问题感兴趣，请参考 GitHub 的 HTTPS 克隆错误（https://help.github.com/a