NVM Node.js 版本管理完全指南 | 多版本切換與項目配置教程

在 Node.js 開發中，不同項目可能需要不同版本的 Node.js。NVM（Node Version Manager） 是最流行的 Node.js 版本管理工具，讓你能夠在同一臺機器上輕鬆安裝、切換和管理多個 Node.js 版本。本文將詳細介紹 NVM 的完整使用方法和最佳實踐。

為什麼需要 Node.js 版本管理？

常見痛點

問題	影響	解決方案
📦 版本衝突	老項目不兼容新版 Node	為每個項目指定版本
🔧 全局汙染	不同版本的 npm 包衝突	隔離的全局包目錄
⚡ 測試需求	需要測試多版本兼容性	快速切換版本
🛠️ 權限問題	系統級安裝需要 sudo	用戶級安裝無需權限
🔄 升級困難	手動升級容易出錯	一鍵安裝/卸載

NVM vs N 對比

nvm 與 n 的區別

node 版本管理工具還有一個是 TJ大神的 n 命令，n 命令是作為一個 node 的模塊而存在，而 nvm 是一個獨立於 node/npm 的外部 shell 腳本，因此 n 命令相比 nvm 更加侷限。

由於 npm 安裝的模塊路徑均為 /usr/local/lib/node_modules，當使用 n 切換不同的 node 版本時，實際上會共用全局的 node/npm 目錄。 因此不能很好的滿足『按不同 node 版本使用不同全局 node 模塊』的需求。

詳細對比表

特性	NVM	N
類型	Shell 腳本	Node 模塊
安裝方式	獨立安裝	通過 npm 安裝
平臺支持	macOS/Linux/Windows	macOS/Linux
版本隔離	✅ 完全隔離	❌ 共享全局目錄
.nvmrc 支持	✅ 原生支持	❌ 不支持
默認版本設置	✅ 支持	✅ 支持
包遷移	✅ 內置支持	❌ 需手動處理
卸載清理	✅ 乾淨徹底	⚠️ 可能殘留
學習曲線	中等	簡單
推薦場景	專業開發	簡單需求

結論：

• 🟢 推薦使用 NVM：功能強大，生態完善
• 🟡 N 適合簡單場景：僅需快速切換版本

卸載全局安裝的 node/npm

在官網下載的 node 安裝包，運行後會自動安裝在全局目錄，使用過程中經常會遇到一些權限問題，所以推薦按照以下方法卸載全局安裝的 node/npm。

首先，打開你 Finder，按 shift+command+G，打開前往文件夾的窗口，分別輸入下列目錄進去之後刪除 node 和 node_modules 相關的文件和文件夾:

• 打開 /usr/local/lib，刪除 node 和 node_modules 相關的文件和文件夾
• 打開 /usr/local/include，刪除 node 和 node_modules 相關的文件和文件夾

如果你是使用的 brew install node 安裝的 NodeJS，那麼你還需要在終端中執行 brew uninstall node 命令來卸載

檢查你的個人主文件夾下面的所有的 local、lib 以及 include 文件夾，並且刪除所有與 node 和 node_modules 相關的文件以及文件夾

打開 /usr/local/bin 並刪除 node 可執行文件

你可能還需要在你的終端中輸入一些額外的指令：

sudo rm /usr/local/bin/npm
sudo rm /usr/local/share/man/man1/node.1
sudo rm /usr/local/lib/dtrace/node.d
sudo rm -rf ~/.npm
sudo rm -rf ~/.node-gyp
sudo rm /opt/local/bin/node
sudo rm /opt/local/include/node
sudo rm -rf /opt/local/lib/node_modules

完整卸載流程詳解

macOS 用戶

步驟 1：備份重要數據

# 備份全局 npm 包列表
npm list -g --depth=0 > ~/npm-global-packages.txt

# 備份自定義配置
cp ~/.npmrc ~/npmrc.backup 2>/dev/null || true

步驟 2：卸載 Homebrew 安裝的 Node

# 如果使用 Homebrew
brew uninstall node
brew cleanup

# 驗證卸載
which node  # 應該返回空或系統路徑

步驟 3：手動清理殘留文件

# 刪除 Node.js 相關文件
sudo rm -rf /usr/local/lib/node_modules
sudo rm -rf /usr/local/include/node
sudo rm /usr/local/bin/node
sudo rm /usr/local/bin/npm
sudo rm /usr/local/bin/npx

# 刪除配置文件
rm -rf ~/.npm
rm -rf ~/.node-gyp
rm ~/.npmrc

# 刪除手冊頁
sudo rm -rf /usr/local/share/man/man1/node*
sudo rm -rf /usr/local/share/man/man1/npm*
sudo rm -rf /usr/local/share/man/man1/npx*
sudo rm -rf /usr/local/share/man/man7/npm*

# 刪除 dtrace 文件
sudo rm -rf /usr/local/lib/dtrace/node.d

步驟 4：驗證清理結果

# 檢查是否還有殘留
which node
which npm
node --version 2>/dev/null || echo "Node.js 已卸載"

# 查找可能的殘留文件
find /usr/local -name "*node*" 2>/dev/null
find ~ -name ".npm" -o -name ".node-gyp" 2>/dev/null

Linux 用戶

# Ubuntu/Debian
sudo apt-get remove --purge nodejs npm
sudo apt-get autoremove
sudo rm -rf /usr/local/lib/node_modules
sudo rm -rf /usr/local/include/node
rm -rf ~/.npm
rm -rf ~/.node-gyp

# CentOS/RHEL
sudo yum remove nodejs npm
sudo rm -rf /usr/local/lib/node_modules
rm -rf ~/.npm

Windows 用戶

# 通過控制面板卸載
# 或使用 PowerShell
winget uninstall OpenJS.NodeJS

# 清理殘留
Remove-Item -Recurse -Force "$env:APPDATA\npm" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:APPDATA\npm-cache" -ErrorAction SilentlyContinue

安裝 nvm

brew install nvm

多平臺安裝方法

macOS（Homebrew）

# 安裝 NVM
brew install nvm

# 創建 NVM 目錄
mkdir ~/.nvm

# 配置環境變量
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"' >> ~/.zshrc

# 重新加載配置
source ~/.zshrc

# 驗證安裝
nvm --version

Intel Mac 路徑：

# Intel Mac 使用 /usr/local 而非 /opt/homebrew
echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && \. "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrc

macOS/Linux（官方腳本）

# 下載並執行安裝腳本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 或使用 wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加載配置
source ~/.bashrc  # 或 source ~/.zshrc

# 驗證安裝
nvm --version

Windows（nvm-windows）

# 使用 Scoop
scoop install nvm

# 或使用安裝包
# 下載：https://github.com/coreybutler/nvm-windows/releases

# 驗證安裝
nvm version

注意： Windows 用戶使用 nvm-windows，命令略有不同：

• nvm install → nvm install
• nvm use → nvm use
• nvm ls → nvm list

配置 NVM

創建 .nvmrc 文件（可選）：

# 設置默認 Node 版本
echo "lts/*" > ~/.nvmrc

# 或指定具體版本
echo "18.19.0" > ~/.nvmrc

配置 NVM 鏡像加速（國內用戶）：

# 編輯配置文件
nano ~/.zshrc  # 或 ~/.bashrc

# 添加以下內容
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

# 重新加載
source ~/.zshrc

安裝多版本 node/npm

安裝4.2.2版本：

nvm install 4.2.2

安裝最新的 4.2 系列的最新版本：

nvm install 4.2

列出遠程服務器上所有的可用版本：

nvm ls-remote

安裝命令詳解

基本安裝

# 安裝特定版本
nvm install 18.19.0

# 安裝最新 LTS 版本（推薦）
nvm install --lts

# 安裝最新穩定版
nvm install node

# 安裝特定大版本
nvm install 18      # 安裝 18.x 最新版
nvm install 20      # 安裝 20.x 最新版

高級安裝選項

# 從源碼編譯安裝
nvm install 18.19.0 --reinstall-packages-from=current

# 安裝時跳過二進制下載（強制編譯）
nvm install 18.19.0 --build-from-source

# 安裝時遷移全局包
nvm install 18.19.0 --reinstall-packages-from=16.14.0

# 安裝特定架構版本
nvm install 18.19.0 --arch=x64

查看可用版本

# 列出所有遠程可用版本
nvm ls-remote

# 列出 LTS 版本
nvm ls-remote --lts

# 篩選特定版本
nvm ls-remote | grep v18
nvm ls-remote | grep lts

# 查看最新版本
nvm ls-remote | tail -10

輸出示例：

       v18.19.0   (Latest LTS: Hydrogen)
       v20.11.0   (Latest LTS: Iron)
       v21.6.0
->     v22.0.0

常用版本說明

版本代號	版本號	狀態	支持週期
Argon	v4.x	EOL	已結束
Boron	v6.x	EOL	已結束
Carbon	v8.x	EOL	已結束
Dubnium	v10.x	EOL	已結束
Erbium	v12.x	EOL	已結束
Fermium	v14.x	EOL	已結束
Gallium	v16.x	EOL	已結束
Hydrogen	v18.x	Maintenance	至 2025-04
Iron	v20.x	Active LTS	至 2026-04
Jod	v22.x	Current	至 2024-10

推薦選擇：

• 🟢 生產環境：最新 LTS 版本（當前 v20.x）
• 🟡 新項目：Current 版本（當前 v22.x）
• 🔴 老項目：根據項目要求選擇

在不同版本間切換

切換到 4.2.2：

nvm use 4.2.2

切換到 4.2.x：

nvm use 4.2

切換到最新版：

nvm use node

切換命令詳解

基本切換

# 切換到特定版本
nvm use 18.19.0

# 切換到最新 18.x
nvm use 18

# 切換到最新 LTS
nvm use --lts

# 切換到最新穩定版
nvm use node

# 切換到系統 Node（如果存在）
nvm use system

自動切換（.nvmrc）

# 在項目根目錄創建 .nvmrc
echo "18.19.0" > .nvmrc

# 進入目錄後自動使用指定版本
cd my-project
nvm use  # 自動讀取 .nvmrc

# 或使用自動切換工具
# 安裝 auto-nvm
npm install -g auto-nvm

配置 Shell 自動切換：

# 添加到 ~/.zshrc 或 ~/.bashrc
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path="$(nvm_find_nvmrc)"
  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use
    fi
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

設置默認版本

# 設置默認 Node 版本
nvm alias default 18.19.0

# 設置別名為 LTS
nvm alias default lts/*

# 查看別名
nvm alias

# 刪除別名
nvm unalias default

版本切換最佳實踐

場景 1：多項目開發

# 項目 A 使用 Node 18
cd project-a
echo "18.19.0" > .nvmrc
nvm use

# 項目 B 使用 Node 20
cd ../project-b
echo "20.11.0" > .nvmrc
nvm use

場景 2：測試兼容性

# 測試代碼在不同版本下的表現
for version in 16 18 20; do
  echo "Testing with Node $version"
  nvm use $version
  npm test
done

列出已安裝實例

nvm ls

列表命令詳解

# 列出本地已安裝版本
nvm ls

# 列出遠程可用版本
nvm ls-remote

# 列出 LTS 版本
nvm ls-remote --lts

# 查看當前使用版本
nvm current

# 查看版本詳細信息
nvm version
nvm version 18.19.0

輸出示例：

->     v18.19.0
       v20.11.0
       v22.0.0
default -> 18.19.0
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v22.0.0) (default)
stable -> 22.0 (-> v22.0.0) (default)
lts/* -> lts/iron (-> v20.11.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.21.3 (-> N/A)
lts/gallium -> v16.20.2 (-> N/A)
lts/hydrogen -> v18.19.0
lts/iron -> v20.11.0

符號說明：

• -> 當前正在使用的版本
• default 默認版本
• lts/* 最新 LTS 版本
• N/A 未安裝該版本

在項目中使用不同版本的 Node

我們可以通過創建項目目錄中的 .nvmrc 文件來指定要使用的 Node 版本。之後在項目目錄中執行 nvm use 即可。

.nvmrc 文件內容只需要遵守上文提到的語義化版本規則即可

.nvmrc 文件詳解

支持的格式

# 精確版本
echo "18.19.0" > .nvmrc

# 大版本
echo "18" > .nvmrc

# 小版本
echo "18.19" > .nvmrc

# LTS 版本
echo "lts/*" > .nvmrc
echo "lts/hydrogen" > .nvmrc

# 最新版本
echo "node" > .nvmrc
echo "stable" > .nvmrc

實際項目示例

package.json 中聲明引擎要求：

{
  "name": "my-project",
  "version": "1.0.0",
  "engines": {
    "node": ">=18.0.0 <21.0.0"
  }
}

配合 .nvmrc 使用：

# 創建 .nvmrc
echo "18.19.0" > .nvmrc

# 提交到版本控制
git add .nvmrc
git commit -m "chore: add nvmrc for node version"

自動化插件

安裝 zsh-nvm 插件：

# Oh My Zsh
git clone https://github.com/lukechilds/zsh-nvm.git ~/.oh-my-zsh/custom/plugins/zsh-nvm

# 添加到 ~/.zshrc
plugins=(... zsh-nvm)

# 自動切換功能已內置

使用 direnv（更強大的方案）：

# 安裝 direnv
brew install direnv

# 配置 Shell
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# 在項目目錄創建 .envrc
echo "layout node" > .envrc
direnv allow

# 或指定版本
echo "use node 18.19.0" > .envrc
direnv allow

在多環境中使用npm

每個版本的 Node 都會自帶一個不同版本的 npm，可以用 npm -v 來查看 npm 的版本。全局安裝的 npm 包並不會在不同的 Node 環境中共享，因為這會引起兼容問題。它們被放在了不同版本的目錄下，例如 ~/.nvm/versions/node/<version>/lib/node_modules</version> 這樣的目錄。這剛好也省去我們在 Linux 中使用 sudo 的功夫了。因為這是用戶的主文件夾，並不會引起權限問題。

但問題來了，我們安裝過的 npm 包，都要重新再裝一次？幸運的是，我們有個辦法來解決我們的問題，運行下面這個命令，可以從特定版本導入到我們將要安裝的新版本 Node：

nvm install v5.0.0 --reinstall-packages-from=4.2

npm 包管理詳解

版本隔離機制

# 每個 Node 版本有獨立的 npm 和全局包
~/.nvm/versions/node/
├── v16.20.2/
│   ├── bin/
│   │   ├── node
│   │   └── npm
│   └── lib/
│       └── node_modules/
│           └── <全局包>
├── v18.19.0/
│   ├── bin/
│   │   ├── node
│   │   └── npm
│   └── lib/
│       └── node_modules/
│           └── <全局包>
└── v20.11.0/
    └── ...

優勢：

• ✅ 無權限問題（無需 sudo）
• ✅ 版本隔離，避免衝突
• ✅ 可以為不同項目使用不同全局包

遷移全局包

# 方法 1：安裝新版本時遷移
nvm install 18.19.0 --reinstall-packages-from=16.20.2

# 方法 2：手動遷移
nvm use 16.20.2
npm list -g --depth=0 > packages.txt
nvm use 18.19.0
xargs npm install -g < packages.txt

# 方法 3：使用 nvm 內置命令
nvm reinstall-packages 16.20.2

遷移過程示例：

$ nvm install 18.19.0 --reinstall-packages-from=16.20.2
Downloading and installing node v18.19.0...
Computing checksum with sha256sum
Checksums matched!
Now using node v18.19.0 (npm v10.2.3)
Reinstalling global packages from v16.20.2...
Linking global packages from v16.20.2...

管理全局包

# 查看當前版本的全局包
npm list -g --depth=0

# 安裝全局包
npm install -g typescript eslint prettier

# 卸載全局包
npm uninstall -g typescript

# 更新全局包
npm update -g

# 清理緩存
npm cache clean --force

推薦的全局包：

# 開發工具
npm install -g typescript ts-node nodemon

# 代碼質量
npm install -g eslint prettier stylelint

# 腳手架工具
npm install -g create-react-app create-next-app @vue/cli

# 實用工具
npm install -g http-server serve json-server

使用局部依賴代替全局包

最佳實踐：優先使用局部安裝

# ❌ 不推薦：全局安裝
npm install -g typescript

# ✅ 推薦：局部安裝
npm install --save-dev typescript

# 通過 npx 運行
npx tsc --version

# 或在 package.json 中添加腳本
{
  "scripts": {
    "build": "tsc",
    "lint": "eslint src/"
  }
}

優勢：

• ✅ 項目依賴明確
• ✅ 版本可控
• ✅ 團隊協作一致
• ✅ CI/CD 友好

高級用法與技巧

1. 批量操作

# 卸載所有舊版本
nvm ls | grep -v "current\|system\|default" | xargs nvm uninstall

# 保留最新版本，卸載其他
nvm uninstall $(nvm ls | grep -v "v20" | grep "v[0-9]" | head -n -1)

2. 性能優化

# 禁用顏色輸出（提升速度）
export NVM_NO_COLORS=true

# 使用更快的鏡像
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

# 預下載二進制文件
nvm ls-remote | grep "LTS" | tail -5

3. 故障排查

問題 1：nvm command not found

# 檢查環境變量
echo $NVM_DIR

# 重新加載配置
source ~/.zshrc  # 或 source ~/.bashrc

# 檢查安裝
ls -la ~/.nvm/nvm.sh

問題 2：切換版本失敗

# 檢查版本是否已安裝
nvm ls

# 重新安裝
nvm uninstall 18.19.0
nvm install 18.19.0

# 檢查權限
ls -la ~/.nvm/versions/node/

問題 3：npm 全局包丟失

# 重新鏈接
nvm reinstall-packages $(nvm version previous)

# 或重新安裝
nvm use 18.19.0
npm install -g <packages>

4. CI/CD 集成

.github/workflows/test.yml

name: Test Multiple Node Versions

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16, 18, 20]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      
      - run: npm ci
      - run: npm test

常見問題解答

Q1: NVM 和 NPM 有什麼區別？

A:

• NVM：管理 Node.js 版本本身
• NPM：Node.js 的包管理器，管理依賴包
• 兩者互補，都需要使用

Q2: 如何完全卸載 NVM？

# macOS/Linux
rm -rf ~/.nvm
# 從 ~/.zshrc 或 ~/.bashrc 中刪除 NVM 相關配置
source ~/.zshrc

# Windows
# 通過控制面板卸載 nvm-windows

Q3: .nvmrc 文件應該提交到 Git 嗎？

A: ✅ 應該提交

• 確保團隊成員使用相同版本
• CI/CD 環境可以自動使用正確版本
• 避免因版本差異導致的 bug

Q4: 如何在 Docker 中使用 NVM？

FROM ubuntu:22.04

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

ENV NVM_DIR=/root/.nvm
RUN . "$NVM_DIR/nvm.sh" && nvm install 18
RUN . "$NVM_DIR/nvm.sh" && nvm use 18

CMD ["node", "--version"]

Q5: NVM 會影響系統性能嗎？

A:

• ⚡ 影響極小（僅 Shell 啟動時加載）
• 💾 佔用磁盤空間（每個版本約 50-100MB）
• 🎯 建議只保留常用的 2-3 個版本

總結

NVM 是 Node.js 開發者的必備工具：

1. ✅ 版本管理：輕鬆安裝和切換多個 Node 版本
2. ✅ 權限友好：無需 sudo，用戶級安裝
3. ✅ 項目隔離：通過 .nvmrc 為每個項目指定版本
4. ✅ 包遷移：內置全局包遷移功能
5. ✅ 跨平臺：支持 macOS、Linux、Windows

關鍵命令速查：

nvm install <version>          # 安裝版本
nvm use <version>              # 切換版本
nvm ls                         # 列出已安裝版本
nvm ls-remote                  # 列出可用版本
nvm alias default <version>    # 設置默認版本
nvm uninstall <version>        # 卸載版本

最佳實踐：

• 📝 每個項目添加 .nvmrc 文件
• 🔄 定期更新到最新 LTS 版本
• 📦 優先使用局部依賴而非全局包
• 🗑️ 及時清理不再使用的版本

下一步學習：

• Node.js 最佳實踐
• npm/pnpm 包管理
• Docker 容器化部署

開始使用 NVM，讓你的 Node.js 開發更加高效！🚀✨