Node.js 疑難排解

本文件旨在協助使用 ServBay 本地開發環境的開發者，解決在使用 Node.js 套件時常見的問題。

找不到 Node.js/npm/pnpm/yarn 指令版本

當你在 ServBay 中使用 Node.js、npm、pnpm 或 yarn 時，若出現類似以下的錯誤訊息，就代表系統找不到你嘗試使用的特定版本 Node.js 可執行檔：

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

這通常是因為你試圖使用的特定 Node.js 版本尚未於 ServBay 內安裝，或期望使用經由 nvm 或 homebrew 等工具安裝在系統的 Node.js 版本，但因環境設定導致 ServBay 無法正確找到它們。

小提示

安裝 ServBay 後，系統會設置 ServBay 的腳本別名（Script Alias），使其優先使用 ServBay 內安裝的 Node.js 套件。若 ServBay 找不到指定版本，會依序嘗試回退到 nvm 安裝的預設版本，接著是 homebrew 安裝的版本。若這些來源都找不到指定版本，系統就會出現如上的錯誤提示。

原因分析：

1. 你要使用的 Node.js 版本未於 ServBay 應用中安裝。
2. 系統有安裝 nvm 或 homebrew，且你希望使用這些工具管理的 Node.js 版本，但因 shell 環境變數（特別是 PATH 或 NVM_BIN）設定不正確，導致 ServBay 的回退機制找不到外部安裝的 Node.js。

解決方法：

如果你已安裝 nvm 並利用它安裝了 Node.js 版本，但仍遭遇這類錯誤，常見原因是 shell 設定裡缺少或錯誤設置 NVM_BIN 這個環境變數。nvm 正確安裝時會自動配置該變數，它指向 nvm 安裝 Node.js 執行檔的位置，這對 nvm 正常運行至關重要。

你只需檢查並修正 shell 設定檔（如 ~/.zshrc、~/.bash_profile 等）中的 nvm 相關設定，確保 NVM_BIN 變數正確設置並已導出，然後重新載入設定檔（例如執行 source ~/.zshrc，或重啟終端機）。完成後，ServBay 的回退機制應該能順利找到 nvm 管理的 Node.js 版本。

若你未使用 nvm 或 homebrew，或希望直接利用 ServBay 所管理的 Node.js 版本，請確認你要用的 Node.js 版本已於 ServBay 應用「套件」界面中安裝。

使用 node-sass 等 npm 套件出現架構不支援訊息

對於使用 Apple Silicon (M1/M2/M3/M4 等 Arm64 架構) 晶片的 macOS 用戶，在安裝某些較舊或依賴原生模組的 npm 套件（如 node-sass）時，可能會遇到類似 Unsupported architecture (arm64) 的錯誤。這是因為舊版本套件僅針對 x86_64 架構提供二進位檔或編譯設定。

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

原因分析：

部分 npm 套件內含需編譯的 C++ 或其他原生代碼。這些原生代碼須針對特定 CPU 架構編譯。舊版套件往往未釋出可支援 Arm64（如 Apple Silicon）的版本或缺乏相關支援。

解決辦法：

1. 改用現代且支援 Arm64 的替代方案（推薦）

   最建議的解決方案為直接替換成現代且完整支援 Arm64 架構的替代套件。例如，把功能有限、維護度低的 node-sass 換成維護活躍、相容性佳的 sass 套件。現代前端專案與工具鏈多已全數遷移至 sass。

   npm uninstall node-sass
   npm install --save-dev sass

2. 於 ServBay 安裝 x86_64 架構 Node.js，並使用 Rosetta 2 執行（不建議）

   ServBay 支援安裝 x86_64 架構的 Node.js 套件。在 Apple Silicon Mac 上，你可以透過 macOS 內建的 Rosetta 2 相容層運行 Node.js 及其所有 x86_64 原生套件。進入 ServBay 應用「套件」界面，即可選擇安裝 x86_64 版本的 Node.js。

   

   請注意： 這種方案通常不建議作為長期解決之道，因為 Rosetta 2 進行模擬執行，會有額外效能損耗，且和原生 Arm64 環境相比有潛在相容性風險。優先考慮方案 1。

---