LLM 知識庫

Appearance

Volta Node.js 版本管理 ​

以 Volta 在 Windows 與 WSL 建立可自動切換、可團隊共享的 Node.js 工具鏈版本管理流程。

概述 ​

在多專案並行的前端或全端開發中，Node 版本漂移是最常見的不穩定來源。傳統以 nvm 進行版本切換通常依賴手動 nvm use，容易漏切環境，造成「同一份程式在不同人電腦行為不一致」。

Volta 的核心價值是將版本切換自動化與專案化：透過 volta pin 將版本寫入 package.json，讓團隊成員在進入專案目錄時自動使用正確版本，降低環境錯誤與溝通成本。

核心內容 ​

Volta 的運作模型 ​

Volta 使用 shim 攔截 node、npm、yarn 等指令，依據當前目錄判斷應使用的工具版本。優先順序如下：

  1. 專案 package.json 的 volta 欄位（volta pin 產生）
  2. 使用者全域預設版本（volta install node@x）

這讓「專案版本隔離」與「全域預設」可以共存，不互相覆蓋。

install 與 pin 的角色差異 ​

指令作用範圍是否寫入專案
volta install node@20全域預設否
volta pin node@20目前專案是（package.json）

volta install 兼具安裝與切換全域預設，不存在獨立 volta use。

版本更新方式 ​

Volta 沒有獨立的 volta update 指令；更新即是重新執行 volta install 並指定新版本，Volta 會自動下載並切換全域預設：

powershell
volta install node@latest   # 最新穩定版
volta install node@22       # 指定主版本（自動解析最新小版本）

重新 install 後舊版本不會被刪除，仍保留在 ~/.volta/tools/，可透過 volta list all 確認。若要更新專案鎖定版本，則在專案目錄改用 volta pin：

powershell
volta pin node@22

移除工具與版本 ​

Volta 的移除能力依工具類型而有所不同：

CLI 工具（yarn、typescript 等全域套件）可直接移除：

powershell
volta uninstall yarn
volta uninstall typescript

Node.js / npm runtime 本身不支援 volta uninstall。Volta 將下載的 runtime 視為快取，需手動刪除對應資料夾：

powershell
# 查看已安裝的 Node 版本
volta list all

# 手動移除指定版本（Windows）
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Volta\tools\image\node\<版本號>"

# 例如移除 Node 18.20.4
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Volta\tools\image\node\18.20.4"

工具快取的完整目錄結構：

%LOCALAPPDATA%\Volta\tools\image\
  ├── node\       ← Node.js 各版本
  ├── npm\        ← npm 各版本
  └── packages\   ← 全域 CLI 工具

⚠️ 手動刪除前應確認沒有任何專案仍 pin 了該版本，否則進入該專案目錄時 Volta 會自動重新下載。

npm / yarn 行為差異 ​

npm 可能跟隨 Node 內建版本，也可能被 volta install npm@x 明確覆蓋；yarn 則是獨立工具，切換 Node 不會改變其版本。若需要穩定 CI 行為，建議在專案內同時 pin node 與 pin npm。

關鍵要點 ​

  • Windows 原生支援完整，建議優先用 .msi 或 winget 安裝
  • 團隊協作時應將 package.json 中的 volta 欄位納入版控
  • 全域 CLI 會綁定安裝時 Node 版本，可避免切換版本後 CLI 壞掉
  • 無獨立 update 指令，重新執行 volta install <tool>@<version> 即為更新，舊版本保留不刪除
  • volta uninstall 僅支援 CLI 工具；Node.js / npm runtime 需手動刪除 %LOCALAPPDATA%\Volta\tools\image\ 下的對應資料夾
  • Node 18 搭配 npm 10 需確認 Node 至少為 18.17.0
  • 在 WSL 專案中同樣可用 Volta，與WSL2 Terminal 美化與功能強化環境相容

實際應用 ​

典型情境是同一台電腦同時維護多個專案：A 專案鎖 node@18、B 專案鎖 node@20。使用 Volta 時只需 cd 切換目錄即可自動切換版本，不需額外心智負擔。配合終端提示（如PowerShell Terminal 美化指南）可更快辨識當前執行環境。

部署設定參考 ​

安裝與驗證 ​

powershell
winget install Volta.Volta
volta --version

全域預設版本 ​

powershell
volta install node@20
volta install npm@10

專案版本鎖定 ​

powershell
# 在專案根目錄
volta pin node@20
volta pin npm@10

更新版本 ​

powershell
# 更新全域預設
volta install node@latest
volta install npm@latest

# 更新專案鎖定版本（在專案根目錄執行）
volta pin node@22
volta pin npm@11

常用檢查 ​

powershell
volta list          # 目前使用中版本
volta list all      # 所有已安裝版本
volta which node    # 執行路徑

package.json 範例 ​

json
{
  "volta": {
    "node": "20.11.0",
    "npm": "10.2.4"
  }
}

相關概念 ​

來源 ​