安裝 Node.js

Node.js 用來執行 Saavo 的開發伺服器、建置指令和測試，npm 則用來安裝專案的相依套件。Saavo 需要 Node.js 22.13.0 或更新版本，建議使用 Node.js 24 LTS。

本文使用 fnm 管理 Node.js。相較於直接安裝固定版本，fnm 更方便升級、切換及清理版本，也能避免不同專案需要不同 Node.js 版本時互相影響。

先檢查現有版本

開啟終端機，執行：

node -v
npm -v
fnm --version

• node -v 輸出的版本為 22.13.0 或更新版本，而且 npm -v 也能正常輸出版本號碼：現有環境已符合需求，不必為了使用 fnm 而重新安裝 Node.js。
• Node.js 版本低於 22.13.0，或找不到指令：繼續安裝 fnm 和 Node.js 24。
• 只有 fnm 指令不存在：代表目前的 Node.js 可能透過其他方式安裝。只要版本符合需求，就可以繼續使用。

安裝 fnm

依作業系統選擇一種方式。

Windows

開啟 PowerShell 或 Windows Terminal：

winget install --id Schniz.fnm -e

也可以使用 scoop install fnm、choco install fnm，或從 fnm Releases 下載符合處理器架構的版本。擇一安裝即可，不要重複安裝。

目前 WinGet 中的 fnm 是可攜式套件，安裝時會註冊 fnm 指令。完成後，關閉所有終端機視窗，重新開啟 PowerShell 並執行：

fnm --version

能顯示版本號碼就代表安裝完成，不需要手動將 fnm 加入 PATH，也不必為了讓系統辨識 fnm 指令而修改 $PROFILE。

macOS

使用 Homebrew 安裝：

brew install fnm

Homebrew 會安裝 fnm 指令，但不會替你修改 Bash 或 Zsh 的啟動檔案。後面仍需完成 Shell 初始化。

Linux

使用官方安裝指令碼前，系統必須已安裝 curl 和 unzip：

curl -fsSL https://fnm.vercel.app/install | bash

官方安裝指令碼會根據 $SHELL 自動修改 ~/.bashrc、~/.zshrc 或 Fish 設定。執行後依終端機提示重新開啟終端機，或執行 source 指令即可，不要重複加入同一段設定。只有在指令碼無法辨識 Shell，或安裝時使用 --skip-shell 的情況下，才需要手動設定。

確認 Shell 初始化

這裡需要區分兩件事：

• 執行 fnm --version，只是在確認終端機能找到 fnm 程式。
• 執行 node、切換 Node.js 版本，以及讀取 .nvmrc，都需要目前的 Shell 執行 fnm env。

Windows 透過 WinGet 安裝後，第一項通常已自動完成，第二項仍需要初始化 Shell。macOS 使用 Homebrew 安裝時也需要初始化。Linux 的官方安裝指令碼通常已自動寫入設定，請先檢查對應檔案，缺少時再加入，避免重複寫入。

將符合目前 Shell 的初始化指令放在設定檔末尾：

# 加入 $PROFILE
fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

如果 PowerShell 還沒有設定檔，可以先建立並開啟：

if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }
notepad $PROFILE

儲存後，關閉所有終端機視窗再重新開啟。這時除了確認 fnm 指令存在，也要確認 Shell 已載入 fnm 環境：

fnm --version
fnm current

尚未安裝 Node.js 時，fnm current 沒有可顯示的版本是正常現象。下一步安裝並啟用 Node.js 後，再用 node -v 做最後確認。

安裝 Node.js 24 LTS

執行：

fnm install 24
fnm default 24
fnm use 24

這三個指令分別用來安裝 Node.js 24、將它設為新終端機的預設版本，以及立即切換目前終端機使用的版本。fnm 也會提供該版本內附的 npm，不需要另外安裝。

驗證 Node.js 和 npm

重新開啟終端機，再執行：

fnm --version
node -v
npm -v

node -v 應輸出 v24.x，npm -v 應輸出版本號碼。次要版本號碼會隨 Node.js 24 的維護更新而改變，不必與截圖完全相同。

Windows 提示無法載入 npm.ps1

如果 node -v 正常，但在 PowerShell 執行 npm -v 時出現以下錯誤：

npm.ps1 cannot be loaded because running scripts is disabled on this system
PSSecurityException

這不代表 npm 安裝失敗。Node.js 已內附 npm，只是 PowerShell 執行 npm 時找到了 npm.ps1，而目前的執行原則不允許執行 PowerShell 指令碼。錯誤路徑中出現 fnm_multishells 也是正常的，這是 fnm 提供目前終端機所用 Node.js 版本的入口。

先執行以下指令，確認 npm 已經安裝：

npm.cmd -v

如果能輸出版本號碼，就不需要重新安裝 Node.js 或 npm。暫時使用時，可以在 PowerShell 中明確呼叫 npm.cmd 和 npx.cmd：

npm.cmd install
npx.cmd wrangler --version

如果這是自己的開發電腦，可以先查看各個範圍的執行原則：

Get-ExecutionPolicy -List

接著只為目前的使用者啟用 RemoteSigned：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

確認修改後，關閉 PowerShell 再重新開啟，執行 npm -v 和 npx -v。不要為了方便而將整台電腦的原則改成 Unrestricted，也不要永久使用 Bypass。

常見問題

• 安裝後仍提示找不到 fnm：關閉所有終端機視窗後再開啟。如果仍然無效，檢查 fnm 是否已加入 PATH。
• fnm 可以執行，但 node 仍然不存在：通常是 Shell 初始化指令沒有生效。請檢查 $PROFILE、~/.bashrc 或 ~/.zshrc，再重新開啟終端機。
• 開啟新的終端機後，又變回舊版本：執行 fnm default 24，並確認 Shell 設定中保留了 fnm env --use-on-cd。
• 電腦安裝了多個 Node.js：在 Windows 執行 where.exe node，macOS 或 Linux 執行 which -a node，檢查舊安裝的路徑是否排在 fnm 前面。