什麼是 NVM？管理 Node.js 版本的終極指南

NVM（Node Version Manager） 是 Node.js 的版本管理工具，能讓您在同一台電腦上安裝多個 Node.js 版本，並用一行指令自由切換。這篇文章會從「為什麼需要它」開始，帶您完成 Windows 與 macOS 的安裝、熟悉常用指令、用 .nvmrc 鎖定專案版本，並整理最常遇到的錯誤與解法。

• NVM = Node Version Manager，用來在同一台機器上安裝、管理與切換多個 Node.js 版本（含 npm）。
• 解決專案間 Node 版本不一致的問題，讓開發者能依專案需要切換 Node 版本。
• macOS / Linux 通常使用 nvm（shell script）。Windows 有社群版本 nvm-windows（不同專案 repo、細節略有差異）。

還不熟悉開發環境？

可以先看 前端開發工具總覽 與 VS Code 入門教學，再回來安裝 NVM。

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

直接從官網安裝 Node.js，整台電腦就只會有「一個」版本。但實務上很容易遇到這些狀況：

• 公司的舊專案還跑在 Node 16，新專案的建置工具卻要求 Node 20 以上。
• 套件安裝時出現 engine "node" is incompatible with this module 之類的錯誤。
• 想試用最新版 Node，又不希望把手上正在維護的專案弄壞。
• 團隊成員各自的 Node 版本不同，導致 node_modules 或 lock 檔行為不一致，出現「在我電腦上是好的」。

NVM 的做法是把每個版本各自安裝在獨立目錄，再透過切換 PATH（Windows 版是切換 symlink）決定目前的 node 指向哪一個版本，因此切換版本只要一行指令，不必反覆解除安裝、重新安裝。

Node.js 版本怎麼選

沒有特殊需求就用 LTS（Long Term Support，長期支援版）。偶數版號才會進入 LTS，維護期較長也較穩定；奇數版號屬於實驗性質的 Current 版，適合嘗鮮而不適合正式專案。

如何安裝 NVM

安裝前請先移除舊的 Node.js

如果您之前用官方安裝檔裝過 Node.js，請先把它解除安裝，否則系統原本的 node 會殘留在 PATH 中，導致 nvm use 切換後版本沒有變。

在 Windows 安裝 nvm-windows

1. 前往 nvm-windows releases。
2. 請選擇 nvm-setup.exe 下載並安裝。
3. 安裝完成後重新開啟終端機（PowerShell / CMD），輸入 nvm version 確認安裝成功。

在 macOS 安裝 nvm

1. 教學。

2. 也可直接執行官方安裝腳本：

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

3. 安裝後重開終端機（或執行 source ~/.zshrc），輸入 nvm --version 確認。

NVM 常用指令

nvm ls                 # 列出本機安裝的 node 版本以及當前使用中的版本
nvm ls available       # 列出遠端可供安裝的 node 版本
nvm install 24.18.0    # 安裝特定次版本
nvm install lts        # 安裝最新 LTS 版本
nvm use 24.18.0        # 切換至指定版本
nvm uninstall 24.18.0  # 移除該版本
nvm current            # 顯示當前版本
nvm root               # 顯示安裝位置

macOS / Linux 的指令略有不同

上表以 nvm-windows 為主。macOS 版對應指令為 nvm ls-remote（列出可安裝版本）、nvm install --lts（安裝 LTS）、nvm alias default 20（設定預設版本）。

安裝好 Node.js 之後就會一併取得 npm，接著可以參考 NPM 套件管理。

用 .nvmrc 鎖定專案的 Node 版本

在專案根目錄建立 .nvmrc，寫入該專案要使用的版本：

20.11.1

之後在專案目錄直接執行 nvm use（不加版本號），nvm 就會讀取 .nvmrc 切到對應版本。這個檔案應該一起提交進 Git，讓所有團隊成員使用相同版本。

同時也建議在 package.json 標註支援範圍，套件管理器會據此提出警告：

{
  "engines": {
    "node": ">=20.0.0"
  }
}

nvm-windows 不支援 .nvmrc

nvm-windows 目前不會自動讀取 .nvmrc，需要手動 nvm use <版本>。

NVM 常見問題

切換版本後 node -v 沒有變？

• 終端機需要重新開啟，或確認沒有其他來源的 Node（官方安裝檔、Homebrew、Scoop）殘留在 PATH。
• Windows 上若提示權限不足，請以系統管理員身分開啟終端機再執行 nvm use。

全域安裝的套件不見了？

每個 Node 版本有各自獨立的全域 node_modules，切換版本後原本 npm install -g 裝的工具不會跟著過去，需要在新版本重新安裝一次。

macOS 版可用下列指令在安裝新版時一併搬移舊版的全域套件：

nvm install 20 --reinstall-packages-from=18

每次開終端機都要重新指定版本？

• macOS：nvm alias default 20 設定預設版本。
• Windows：nvm use 20 的設定本身就是全域的，重開終端機仍會保留。

專案的 node_modules 出現奇怪錯誤？

切換 Node 大版本後，含有原生模組（node-gyp 編譯）的套件可能不相容，刪掉重裝即可：

rm -rf node_modules package-lock.json
npm install

延伸閱讀

NPM：Node.js 套件管理前端開發工具總覽VS Code：入門教學與快捷鍵免費資源：假圖、假文與 API