nvm 怎麼排除 Node.js 版本混亂？從 .nvmrc、PATH 到乾淨重建的四步診斷

專題編輯：Derek Chou｜AI 技術與架構編輯 · 文件核對 2026.11.09

先判斷出錯的是哪一層

AI 協助產生的安裝說明常會把 node、npm 和 nvm 混在同一段指令裡。出問題時若直接刪除整個 node_modules、重新安裝所有工具，原來的差異也可能一起消失，團隊卻仍不知道下次該如何交接。

比較有效的診斷順序是先確認執行者，再看套件與程式。Node.js 執行 JavaScript；npm 讀取專案設定、安裝依賴及啟動 scripts；nvm 則在目前 Shell 中選擇要使用的 Node.js 安裝。選對 Node，不表示已安裝專案依賴，更不表示應用測試通過。

這張表是排查方法，不是某套工具的保證。若不確定 Runtime 指的是什麼，可參考執行環境與 Runtime 指南。

適用環境與本次演練範圍

本篇使用 nvm-sh/nvm，適合依其官方說明配置的 macOS/Linux Shell。Windows 原生的 nvm-windows 是另一個專案；在 PowerShell 或 CMD 裡，不能直接套用以下 Bash 載入方式。WSL 也應以其 Linux 環境的工具與路徑分開管理。nvm 官方說明

本次於 2026 年 11 月 9 日，以 macOS、nvm 0.40.3、已安裝的 Node.js 22.23.4、npm 10.9.9 驗證切換與測試。操作放在子 Shell，沒有修改系統預設 Node、nvm alias、Shell 啟動檔或既有專案，也沒有重新下載 Node。這次紀錄證明的是「選用已存在的正確版本並重建示範專案」。

下載本篇範例專案，解壓後會看到 .nvmrc、package.json、lockfile 和測試檔。它是一個沒有第三方依賴的本機報價 API，適合用來辨別工具鏈問題；不包含正式公司資料。

步驟一：記錄現況，確認 nvm 確實被載入

開啟專案目錄的終端機，先執行：

command -v nvm
command -v node
node --version
npm --version
node -p 'process.execPath'

command -v nvm 應能辨識 nvm；它通常是由 Shell 載入的函式，不能只用「哪裡有一個叫 nvm 的執行檔」來判斷是否安裝成功。process.execPath 則指出目前 Node 程序的實際路徑，可以和終端機顯示的版本互相核對。

如果 nvm 找不到，但確定已按官方方式安裝，先檢查目前 Shell 是否載入了安裝位置。以下只適用於使用預設位置的既有安裝，可在測試用 Bash 子 Shell 內載入：

bash
source "$HOME/.nvm/nvm.sh" --no-use
nvm --version

若檔案不存在，不要繼續執行，也不要猜一段網路安裝命令；先依nvm 官方安裝及疑難排解文件確認實際安裝位置。本篇沒有執行全新安裝，不能把載入成功當成安裝流程已驗收。

步驟二：讀 .nvmrc，再選版本

本範例的 .nvmrc 只有一行精確版本 22.23.4。在專案根目錄執行：

cat .nvmrc
nvm ls
nvm use
nvm current
nvm which
node --version

預期 nvm 選到 v22.23.4，最後兩個路徑與版本檢查也相符。本次在既有安裝環境中實際得到這個結果。若顯示指定版本尚未安裝，先確認該版本是否仍符合公司的維護政策與下載來源，再於自己的受控開發環境執行 nvm install。安裝和選用是兩個動作；本次沒有把前者記為已測試。

.nvmrc 也能使用較寬的版本表示法，例如一個主版本號或 LTS 別名；但「目前解析到哪個修補版」可能隨時間變動。交接實驗若要精確重跑，可以先寫完整版本，再由團隊定期更新。不要因此長期留在停止維護的版本。

另有兩個容易誤判的地方。第一，單純建立 .nvmrc 不會自動替所有終端機切換版本；需要明確執行 nvm use，或另外設定並驗證 Shell 整合。第二，nvm 會從目前位置向上尋找 .nvmrc，因此在錯誤目錄執行，可能取得不同專案的設定。每次先確認目錄，比看見一個成功訊息更可靠。

步驟三：選對 Node 後，重建依賴與跑測試

接著執行：

npm ci --ignore-scripts --no-audit --no-fund
npm test
npm run verify:gate

本次 5 個測試均通過；故意把臨時副本的金額邊界改壞時，同一組測試會失敗，證明不是只印出成功文字。原本的程式與 lockfile 保持不變。--no-audit 表示這一步未進行漏洞稽核，不是安全認證。

若 npm ci 因 lockfile 不一致而拒絕執行，處理的是專案依賴契約，不是 nvm 功能。先確認兩份檔案來自同一提交，再由負責人決定是否要更新依賴。不要一邊刪除 lockfile、一邊說環境已可重現。npm ci 的行為

若 Node 版本相同仍有差異，接著比較 npm 版本、OS、CPU 架構及必要建置工具。帶原生擴充的套件可能與平台或 Node ABI 有關；單靠 nvm 並不能把 macOS 和 Linux 變成相同環境。本範例沒有第三方原生模組，不能用它的成功結果替大型專案背書。

步驟四：離開測試 Shell，留下可交接紀錄

若前面另開 Bash 子 Shell，最後輸入 exit 返回原終端機。不要為了單一專案測試就改 nvm default alias，也不用修改所有人的 Shell 啟動檔。子 Shell 中的選用結果不應被誤寫成「整台電腦已永久改版」。

交接紀錄可以保持精簡：

專案提交：填入實際 Git commit
OS/CPU：填入實際環境
.nvmrc：22.23.4
Node：v22.23.4
npm：10.9.9
安裝：npm ci 成功
測試：5 個案例通過
負例：錯誤邊界確實被拒絕
限制：未驗證其他 OS／版本，未部署正式環境

這份記錄把「版本意圖」與「實際使用版本」分開，別人就能比對差在哪裡。原始測試輸出可留在專案的 QA 紀錄，不必把使用者路徑、公司資料或環境變數全部公開。

讓本機、CI 和正式環境各自對齊

本機使用 nvm，不代表 CI 一定也要安裝 nvm。GitHub Actions 的 setup-node 可以讀 .nvmrc，讓雲端工作用同一份版本宣告；容器或託管平台則要核對各自的映像或 Runtime 設定。setup-node 官方說明

package.json 的 engines 可以記錄支援範圍，.nvmrc 記錄本次建議選用版本，lockfile 記錄依賴解析結果。三者不是互相替代的檔案。若團隊宣稱支援多個 Node 主版本，就應對每個宣告版本建立測試，而非只在一台筆電成功一次。

對長期系統，較實用的做法是把版本升級列為可審查的變更：查官方維護狀態、評估套件相容性、在分支更新版本、執行測試，再保留能回到前一版的程式與設定。nvm 讓切換容易，但不會替組織決定應承擔多久的過期版本風險。

常見問題

為什麼 nvm use 成功，編輯器裡仍用錯版本？ 編輯器終端機、背景程序與外部終端機可能是不同程序，啟動時繼承的 PATH 也不同。請在真正執行命令的環境裡查 process.execPath，再重新啟動需要更新環境的程序。

切換版本會把專案檔案刪掉嗎？ nvm use 的工作是改變目前 Shell 選用的 Node 路徑，不是刪除專案。若接著執行 npm ci，該安裝命令會依自己的規則清理並重建 node_modules，需分清動作來源。

需要把全域套件全部搬過去嗎？ 先判斷工具是否應成為專案依賴。交接流程若依賴某人全域安裝的工具，就應把工具版本與取得方式明確化，避免讓它成為隱藏前提。

來源與素材說明

主要依據：nvm 官方 README、Node.js 維護版本表、npm ci及GitHub setup-node。官方能力與本次實測範圍分別記錄，未把文件閱讀當成跨平台實測。

封面為使用者提供、由 AI 生成與編排的原創概念圖，並非操作截圖。本文由 AI 協助修訂與查核，未宣稱具名人工審核；Derek Chou 為 TARAISG AI 編輯計畫的專題角色。

封面出現的版本號用於說明切換概念，並非目前受支援版本清單；版本支援狀態請依官方維護表確認。

內容提供：TARAISG。本文由 AI 協助整理與查核；專題編輯為天地人 AI 編輯計畫的策展角色，未宣稱經具名人工或專家審核。