侃瑞科技

Node.js 與 NVM 安裝教學：在 VPS 或本機穩定管理多版本開發環境

完整 NVM 安裝與 Node.js 版本管理教學：LTS 安裝、多版本切換、.nvmrc 自動切換、Docker 與 CI 整合、全域套件管理，讓開發環境乾淨好維護。

VPSNode.jsNVM安裝JavaScriptUbuntuDebian教學開發環境版本管理.nvmrcDockerCI/CD全域套件伺服器優化

如果你要碰現代前端、Node.js 後端、Claude Code、Gemini CLI，甚至只是想在 VPS 上跑一個正常的 JavaScript 專案，Node.js 幾乎就是基本配備。但很多人第一步就用系統套件管理員裝下去，等到專案要求版本一變，整台機器開始變得很難維護。

這篇的重點不是教你把 Node.js 裝起來而已，而是教你把版本管理一起做好。因為真正麻煩的從來不是安裝，而是半年後你還能不能乾淨地升級、切版本、回退，以及讓不同專案共存。

先建立正確觀念

  • 多數開發環境比起 apt install nodejs，更適合用 NVM 管理版本
  • NVM 是 per-user、per-shell 的工具，這正是它好用也容易讓新手搞混的地方
  • 安裝完別只看 node -v，還要確認新 shell、預設版本與 npm 路徑都正常
  • 不同 AI CLI 工具對 Node.js 版本有不同要求，NVM 讓你輕鬆應對

哪些人最適合先補這篇

  • 想在 VPS 或本機管理多個 Node.js 專案的人
  • 想裝 Claude Code、Gemini CLI 或現代前端工具，但不想被版本衝突拖累的人
  • 想把 Node.js 環境從「能跑」升級成「好維護」的人

開始安裝前先確認

  • 確認你用的是 Bash 或 Zsh 之類的常見 shell
  • 如果機器上已經有系統版 Node.js，先知道它只是系統版本，不等於你之後要用的預設版本
  • 如果你在 Docker、CI 或非互動 shell 裡操作，NVM 的載入方式會跟一般 SSH session 不太一樣

詳細教學與操作步驟

Node.js 可以很多種方式安裝，但如果你在同一台機器上會碰到不只一個專案，NVM 幾乎是最省事的解法。依 nvm-sh 官方 README，安裝 NVM 後你可以用它裝最新 LTS、指定版本、設定 default，甚至搭配 .nvmrc 讓不同專案自動切換版本。

為什麼比較建議用 NVM，而不是只靠 apt？

因為系統套件管理員安裝的 Node.js 往往不是你專案想要的版本，而且切換成本高。NVM 的優勢是不用把整台機器綁死在單一版本，也比較不容易碰到全域 npm 權限混亂的問題。

更重要的是，不同 AI CLI 工具對 Node.js 版本有不同要求：

工具最低版本要求
Claude CodeNode.js 18+
Gemini CLINode.js 20+
Codex CLINode.js 18+

有了 NVM，你可以輕鬆在不同版本間切換，不用每次都重新安裝。

步驟一：安裝 NVM 工具

請先登入你的 VPS，並執行官方安裝腳本：

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

安裝完成後，請重新載入你的 shell 設定檔（或重新登入 SSH）：

source ~/.bashrc

如果你是用 Zsh，通常要改成 source ~/.zshrc。官方 README 也提醒，nvm 是 shell function，不是一般執行檔，所以用 which nvm 看不到是正常的，驗證時請用 command -v nvm。

步驟二：使用 NVM 安裝 Node.js

實務上最常見的是先裝最新 LTS，再視專案需要加裝特定版：

  1. 安裝最新的 LTS 版本：nvm install --lts
  2. 安裝特定版本（例如 20 版）：nvm install 20
  3. 確認安裝成功：node -v 與 npm -v

如果你希望新開 shell 也自動使用固定版本，可以再補一行：

nvm alias default 20

這樣下次重新登入 SSH，比較不會又掉回系統版本。

如果你同時需要多個版本（例如 Gemini CLI 要 Node 20，但某個舊專案只能用 Node 18）：

nvm install 18
nvm install 20
nvm install 22

# 設定預設版本
nvm alias default 20

# 列出所有已安裝版本
nvm ls

# 切換版本
nvm use 18
nvm use 20

步驟三：用 .nvmrc 自動管理專案版本

如果你的專案固定用某個版本，建議在 repo 裡放一個 .nvmrc。未來你自己回來維護、或 Claude Code / Gemini CLI 幫你看 repo 時，都更容易知道專案預期用哪個 Node 版本。

echo "20" > .nvmrc

進入專案後執行 nvm use，NVM 會自動讀取 .nvmrc 並切換到對應版本。

自動切換版本 — 加入 shell hook

nvm 官方 README 也有提供搭配 shell hook 的做法，讓你切進專案目錄時自動 nvm use。這對多專案開發非常實用。

Bash 使用者： 把以下內容加入 ~/.bashrc

cdnvm() {
  cd "$@" || return $?
  nvm_path="$(nvm_find_up .nvmrc | command tr -d '\n')"
  if [ -n "$nvm_path" ]; then
    local nvm_version
    nvm_version=$(cat "$nvm_path/.nvmrc")
    local locally_resolved_nvm_version
    locally_resolved_nvm_version=$(nvm ls --no-colors "$nvm_version" | command tail -1 | command tr -d '[:space:]' | command cut -d'v' -f2)
    if [ "$locally_resolved_nvm_version" != "$(nvm version)" ]; then
      nvm use "$nvm_version"
    fi
  fi
}
alias cd='cdnvm'

Zsh 使用者： 把以下內容加入 ~/.zshrc

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

步驟四：全域 npm 套件管理

用 NVM 安裝的 Node.js，全域套件是跟著版本走的。這代表當你切換版本時，全域套件不會自動跟過來。

# 查看目前版本的全域套件
npm list -g --depth=0

# 安裝全域套件（例如 AI CLI 工具）
npm install -g @anthropic-ai/claude-code
npm install -g @google/gemini-cli
npm install -g @openai/codex

# 切換版本時，重新安裝需要的全域套件
nvm install 22 --reinstall-packages-from=20

最後那個 --reinstall-packages-from 參數非常實用，它會自動把指定版本的全域套件複製過來。

步驟五：在 Docker 和 CI/CD 中使用 NVM

NVM 是設計給互動式 shell 用的，在 Docker 和 CI 環境中需要特別處理。

Dockerfile 中使用 NVM：

FROM ubuntu:22.04

# 安裝必要工具
RUN apt-get update && apt-get install -y curl

# 安裝 NVM
ENV NVM_DIR=/root/.nvm
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 安裝 Node.js
RUN . "$NVM_DIR/nvm.sh" && nvm install 20

# 設定 PATH
ENV PATH="$NVM_DIR/versions/node/v20.*/bin:$PATH"

GitHub Actions 中通常不需要 NVM：

# GitHub Actions 有內建的 setup-node
- uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'

不過如果你是在自架的 runner 上，NVM 還是很有用的。

步驟六：常見版本問題排錯

問題一：nvm command not found

# 檢查 NVM 是否有載入
command -v nvm

# 如果沒有，手動載入
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 確認 shell 設定檔有正確的 NVM 載入程式
grep -n "NVM_DIR" ~/.bashrc

問題二：新 shell 跑回舊版本

# 確認 default alias 設定
nvm alias default

# 如果沒有設，設定一下
nvm alias default 20

# 重新開 shell 驗證
exec bash  # 或 exec zsh
node -v

問題三：npm 全域套件的權限問題

# NVM 安裝的 Node.js 不需要 sudo
# 如果你看到需要 sudo 的提示，代表你可能不是用 NVM 的版本

# 確認目前 node 路徑
which node
# 正確：應該在 ~/.nvm/versions/node/... 底下
# 錯誤：如果在 /usr/bin/ 或 /usr/local/bin/，代表吃到系統版

常見問題

Q：安裝後顯示 nvm command not found？ 通常是 shell 設定檔還沒重新載入，或你目前 shell 沒吃到 NVM 的初始化程式。重開一個新終端機再測一次，常常就能排除。

Q：明明有裝 Node，為什麼新 shell 又跑回舊版本？ 代表你可能還沒設 default alias，或 shell 初始化順序有問題。先確認 nvm alias default 的設定，再檢查 shell profile。

Q：NVM 跟 fnm / volta 哪個比較好？ fnm 和 volta 都是 NVM 的替代品，速度更快（因為是用 Rust 寫的）。但 NVM 的生態系最成熟、文件最完整、社群最大。如果你沒有特殊效能需求，NVM 是最安全的選擇。

Q：可以把系統版 Node.js 和 NVM 同時用嗎？ 技術上可以，但非常不建議。PATH 的順序會讓你搞不清楚目前到底在用哪個版本，全域套件也會很混亂。建議用 NVM 後就移除系統版 Node.js。

做完後怎麼確認自己真的裝穩了

  • 執行 command -v nvm，確認 shell 真的認得 nvm
  • 開一個新的 SSH session，再跑 node -v 與 npm -v
  • 設定 nvm alias default 後重開 shell，確認不會掉回系統版 Node.js
  • 在有 .nvmrc 的專案裡跑 nvm use，確認自動切換版本正常
  • 確認 which node 路徑在 ~/.nvm/ 底下，不是系統路徑

這一題最常踩的坑

  • 用 apt 裝完就以為結束，直到第二個專案來了才發現版本根本切不動
  • 只在當前 shell 載入 NVM，重新登入後整個環境又變掉
  • 把系統版 Node.js、NVM 版 Node.js、全域 npm 套件混在一起，之後很難排錯
  • 切版本後忘了全域套件不會跟過來，AI CLI 工具突然找不到
  • 在 Docker 或 CI 中直接用 NVM，沒有處理非互動 shell 的載入問題
  • .nvmrc 寫了但沒有設 shell hook，每次進專案都要手動 nvm use

如果你要往下一步走

Node.js 版本管理整理好之後，下一步通常就是裝真正會用到的工具，例如 Claude Code、Gemini CLI、Codex CLI，或直接進入 Gemini API Node.js 開發流程。這時候你會明顯感覺到，先把 NVM 設好真的能省很多事。

如果你的 Git 與 SSH Key 還沒設好，也建議一起補齊。如果你想用 Python 開發 AI 應用，可以接著看 OpenAI API (Python) 開發環境安裝教學。

需要主機來實作？

侃瑞科技提供 cPanel 虛擬主機與 VPS，教學裡的操作開箱即用。

查看方案 →
下一篇

Git 與 SSH Key 設定教學：在 VPS 上安全拉程式、部署與接 AI 開發工具 →

LINE 諮詢