使用 ServBay 為專案獨立配置 Node.js 版本指南（macOS）

ServBay 是一款專為開發者打造的強大本地 Web 開發環境，提供一站式解決方案，整合包括 Node.js 在內的多種程式語言、資料庫及 Web 伺服器。ServBay 的一大亮點，是其對多版本 Node.js 的原生支援及彈性管理能力。只需簡單的設定檔，您就能為每個專案指定所需的 Node.js 版本，無需再依賴 NVM、fnm 等外部版本管理器或 Docker 容器，極大簡化了開發工作流程，並有效避免全域環境污染及版本衝突。

本文將詳盡說明如何透過 ServBay 的 .servbay.config 檔案，實現專案級的 Node.js 版本控制。

為什麼選擇 ServBay 的 .servbay.config 來管理 Node.js 版本？

傳統的 Node.js 版本管理方式，例如使用 NVM 或手動安裝，常常帶來下列困擾：

• 全域污染與衝突： 在系統全域安裝或透過版本管理器切換全域版本，易導致不同專案之間相依性發生衝突。
• 安裝與編譯耗時： 安裝新版本或在異構架構（如 x86_64 與 arm64）間切換時，往往需重新編譯模組，費時又繁瑣。
• Docker 容器負擔高： 若僅需特定 Node.js 版本時，直接使用完整容器會顯得過於沉重。

ServBay 透過預先安裝多個主流 Node.js 版本（目前支援 v12 至 v23 所有主次版本，您可於 ServBay 應用介面的「軟體包」區塊直接查閱及管理），再結合 .servbay.config 設定檔，帶來更優雅的解決方案：

• 即時切換： 所有版本預先安裝，切換近乎即時完成。
• 專案隔離： 設定僅於專案目錄內生效，實現真正的專案級版本隔離。
• 零全域污染： 不會改動系統全域環境，系統更純淨安全。
• 與 ServBay 無縫整合： 深度融入 ServBay 開發環境，並可與其他管理包（如 PHP、資料庫、Web 伺服器等）搭配使用。

前置需求

在開始之前，請確認您已完成下列準備：

1. 已在 macOS 上順利安裝並啟動 ServBay。
2. 已於 ServBay 應用界面「軟體包」（Packages）清單中，檢查並啟用專案所需的 Node.js 版本。
3. 您擁有一個需設定特定 Node.js 版本的專案目錄。

核心原理

當您於 ServBay 整合終端環境操作時，ServBay 會偵測當前所在目錄。每當您使用 cd 命令進入目錄時，ServBay 會自當前及所有父層資料夾向上搜尋 .servbay.config 檔案。一旦發現（優先取離現有目錄最近者），即讀取該檔案設定，並依其內容動態調校終端會話的環境變數，例如調整 PATH 指向 .servbay.config 所指名的 Node.js 版本路徑。

此一機制確保不同專案目錄下的終端操作，能自動載入並套用各自指定的 Node.js 版本，完全無需手動切換。

設定步驟

為專案獨立設定 Node.js 版本非常簡單，只需兩步：

步驟一：建立並編輯 .servbay.config 檔案

請於專案根目錄（通常為含有 package.json 的目錄）新增名為 .servbay.config 的檔案。

以您偏好的文字編輯器打開，並輸入下列內容：

# 指定專案要使用的 Node.js 主版本號
# ServBay 會自動選用該主版下已安裝的最新次版本
NODE_VERSION=20

# 選用：設定 npm 或 pnpm 的映像源，加速安裝依賴套件
# 若您位於中國大陸地區，建議改用國內映像源
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# 選用：指定 npm 或 pnpm 的快取目錄
# 建議快取放在 ServBay 的暫存目錄，以免佔用主系統空間或污染用戶資料夾
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

各配置項說明：

• NODE_VERSION：**必填。**指定專案需用的 Node.js 主版本號。例如設為 20，即會自動選擇 ServBay 已安裝的 Node.js 20.x 之最新版本。請確保該版本已於 ServBay 安裝。
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY：**選填。**設定 yarn 或 npm 的套件註冊表映像源。對於網路環境較慢的情形，能大幅提升依賴安裝速度。
• NPM_CONFIG_CACHE：**選填。**指定 npm 或 pnpm 快取目錄。建議設置在 ServBay 暫存路徑（如 /Applications/ServBay/tmp/npm/cache），方便集中管理快取檔並防止雜亂。

編輯完成後，請保存並關閉 .servbay.config。

步驟二：於 ServBay 終端確認版本

1. 開啟 ServBay 主畫面。

2. 點擊「終端」（Terminal）按鈕，啟動 ServBay 整合終端。

3. 於終端中切換至您的專案資料夾：

   cd /Applications/ServBay/www/your-project-name

   （請用實際專案路徑取代 /Applications/ServBay/www/your-project-name）

4. 執行 node -v 以檢查目前啟動的 Node.js 版本：

   node -v

   結果應顯示 .servbay.config 中設定的版本號（例如 v20.x.x）。

5. 同時也可執行 npm -v（或 pnpm -v、yarn -v）確認套件管理器是否已連動目前 Node.js 版本。

自此，您在此專案目錄下執行的任何 Node.js、npm、pnpm 或 yarn 指令，都會自動採用 .servbay.config 指定的 Node.js 版本及相關套件管理器設定。

執行範例

以下以一個簡易實例說明 .servbay.config 如何於不同專案間達成 Node.js 版本自動切換。

假設您有兩個專案：project-a 需 Node.js v18，project-b 需 Node.js v20。

1. 建立專案資料夾及設定檔：

   # 於 ServBay 的 www 目錄下建立示範專案
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # 為 project-a 建立 .servbay.config，指定 Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # 為 project-b 建立 .servbay.config，指定 Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. 於 ServBay 終端驗證切換結果：

   開啟 ServBay 終端並依序執行：

   # 進入 project-a 資料夾
   cd /Applications/ServBay/www/project-a
   # 查詢 Node.js 版本
   node -v
   # 預期輸出: v18.x.x
   
   # 切換至 project-b
   cd ../project-b
   # 查詢 Node.js 版本
   node -v
   # 預期輸出: v20.x.x
   
   # 再回到 project-a
   cd ../project-a
   # 查詢 Node.js 版本
   node -v
   # 預期輸出: v18.x.x

藉由這個示範您可看到，ServBay 會根據目前所在目錄，主動載入並應用相對應的 .servbay.config 內之 NODE_VERSION 設定，達成 Node.js 版本自動、無縫切換。

下圖展示於不同專案目錄切換時，Node.js 版本如何依 .servbay.config 自動變更（圖為範例，實際畫面可能略有不同）：

注意事項

• .servbay.config 必須位於專案資料夾或其父層目錄內。ServBay 會自下而上搜尋，並採用第一個找到的設定檔（即最接近當前目錄者）。
• 請確保您於 ServBay 整合終端作業，或在已正確載入 ServBay 環境變數的外部終端裡執行相應指令。
• NODE_VERSION 必須為已於 ServBay 安裝並啟用之版本。若指定版本尚未安裝，ServBay 可能退回預設版本或發生找不到 Node.js 的情形。
• .servbay.config 的設定值只會影響目前終端會話與其子進程，不會影響系統全域環境，亦不會作用於未載入 ServBay 環境的其它程式。

常見問題解答（FAQ）

Q: 若我的專案資料夾沒有 .servbay.config 會發生什麼事？

A: 若 ServBay 無法於當前及父層目錄找到 .servbay.config 檔，將套用 ServBay 全域預設設定或 Node.js 版本（通常為 ServBay 標註為「預設」之版本）。

Q: 如何查詢 ServBay 支援哪些 Node.js 版本？

A: 請開啟 ServBay 應用，點選左側選單的「軟體包」（Packages）頁面，便可瀏覽所有可用及已安裝的軟體包清單（如不同版本 Node.js），同時可勾選啟用或停用各版本。

Q: .servbay.config 內設定會影響整個系統嗎？

A: 不會。.servbay.config 的內容僅於當前 ServBay 終端會話及其子進程中臨時生效，並不會改動您的全域環境變數，亦不會影響在 ServBay 外執行的應用，這正是 ServBay 能實現專案隔離的核心原理之一。

Q: 除了 NODE_VERSION，.servbay.config 還能設哪些 ServBay 相關設定？

A: 當然可以！.servbay.config 是 ServBay 提供的通用專案級環境變數設定機制。除 Node.js 相關設置外，您亦可設定其他環境變數，所有於專案資料夾下執行的命令都會載入這些變數。支援內容會隨 ServBay 持續更新，但「自定義環境變數」始終為其核心功能之一。

總結

透過 ServBay 的 .servbay.config 檔案，您可輕鬆高效地為每一個本地開發專案指定並獨立管理 Node.js 版本。此法遠較傳統型版本管理器或容器化策略輕巧便捷，完全可融入 ServBay 的整合開發環境，助您建立更穩定且利於團隊協作的開發流程。立即在您的專案中採用 .servbay.config，體驗 ServBay 為開發帶來的高效與便利吧！