使用 .servbay.config 檔案進行專案級環境設定

概述

ServBay 是一款強大的本地 Web 開發環境工具，允許開發者針對不同專案各自配置獨立的運行環境。這項功能的核心，在於支援於每個專案目錄中建立名為 .servbay.config 的檔案。

透過 .servbay.config 檔案，你可以輕鬆為特定專案指定所需的 PHP、Node.js、Python、Go、Java 等語言版本，並設定 Node.js 套件管理器（如 NPM、Yarn）的鏡像倉庫地址與快取目錄等。此種專案級細緻控管極大提升了開發效率與便利性，確保每個專案都能在其需求的特定環境下穩定運作，避免版本衝突。

.servbay.config 檔案的運作原理

當 ServBay 啟動或重新載入網站時，會檢查網站根目錄下是否存在 .servbay.config 檔案。若有此檔案，ServBay 將讀取其中的設定並套用於該網站的運行環境。這些專案級的設定將覆蓋 ServBay 全域設定中對應的項目。若 .servbay.config 不存在，或其中部份設定未指定，ServBay 會採用全域預設值。

此機制讓你能無痛切換不同專案，因為每個專案自帶專屬的環境設定。

如何建立與設定 .servbay.config

建立與設定 .servbay.config 檔案相當簡單。

檔案位置

在你的專案根目錄下建立名為 .servbay.config 的檔案。專案根目錄通常位於 ServBay 的網站儲存路徑下，例如 /Applications/ServBay/www/你的專案名稱/。

設定語法

.servbay.config 檔案以簡易的 KEY=VALUE 格式撰寫，每行設定一個項目。你可以用 # 號加註說明，以增進閱讀性。

設定選項範例

以下為一份 .servbay.config 檔案範例，展示如何設定多種環境版本與套件管理設定：

# .servbay.config 範例檔案

# 指定 PHP 執行版本。請確保此版本已於 ServBay 安裝。
PHP_VERSION=8.5

# 指定 Node.js 執行版本。請確保此版本已於 ServBay 安裝。
NODE_VERSION=20

# 設定 Yarn 的鏡像倉庫地址，加速依賴下載。
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/

# 設定 NPM 的鏡像倉庫地址，加速依賴下載。
NPM_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/

# 指定 NPM 的本地快取目錄。注意：此路徑相對於 ServBay 安裝目錄。
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

# 指定 Yarn 的本地快取目錄。注意：此路徑相對於 ServBay 安裝目錄。
YARN_CONFIG_CACHE=/Applications/ServBay/tmp/yarn/cache

# 指定 Ruby 執行版本。請確保此版本已於 ServBay 安裝。
RUBY_VERSION=2.7

# 指定 Java（OpenJDK） 執行版本。請確保此版本已於 ServBay 安裝。
JAVA_VERSION=21

# 指定 Python 執行版本。請確保此版本已於 ServBay 安裝。
PYTHON_VERSION=3.11

# 指定 .NET 執行版本。請確保此版本已於 ServBay 安裝。
DOTNET_VERSION=5.0

# 指定 Go 執行版本。請確保此版本已於 ServBay 安裝。
GO_VERSION=1.12

# 設定 Go 模組代理伺服器，加速模組下載。
GOPROXY=https://goproxy.cn,direct

請注意： 範例中的版本號（如 PHP_VERSION=8.5、NODE_VERSION=20 等）僅供參考。在實際運作時，請依你的專案需求及 ServBay 已安裝且支援的版本填寫正確數值。若指定版本未安裝，ServBay 可能會使用預設版本或顯示錯誤提示。

支援的設定項目類型

依上述範例，.servbay.config 檔案主要支援下列類型的設定：

1. 環境版本指定：

   • PHP_VERSION：指定 PHP 版本。
   • NODE_VERSION：指定 Node.js 版本。
   • RUBY_VERSION：指定 Ruby 版本。
   • JAVA_VERSION：指定 Java (OpenJDK) 版本。
   • PYTHON_VERSION：指定 Python 版本。
   • DOTNET_VERSION：指定 .NET 版本。
   • GO_VERSION：指定 Go 版本。
   • (請參閱 ServBay 官方文件或應用程式介面，瞭解所有支援的環境型別及對應變數名稱。)

2. 套件管理器設定（Node.js）：

   • YARN_CONFIG_REGISTRY：Yarn 鏡像倉庫位址。
   • NPM_CONFIG_REGISTRY：NPM 鏡像倉庫位址。
   • NPM_CONFIG_CACHE：NPM 本地快取目錄路徑。
   • YARN_CONFIG_CACHE：Yarn 本地快取目錄路徑。

3. Go 模組代理設定：

   • GOPROXY：Go 模組代理伺服器地址。

上述設定項目讓你能替每個專案建立獨立環境，確保互不干擾。

實務應用與驗證

設定好 .servbay.config 後，請確保 ServBay 已經加載你的專案（即於 ServBay 應用「網站」列表中可見）。ServBay 會於網站加載或重新加載時，自動讀取設定檔。

你可以以下方式驗證設定是否生效：

1. 查看 ServBay 應用介面： ServBay 可能於網站詳情或相關頁面顯示目前專案所採用的環境版本。

2. 透過終端機驗證： 使用 ServBay 提供的終端（Terminal）功能，並切換到你的專案根目錄。執行下列版本查詢指令，例如：

   • 檢查 PHP 版本：php -v
   • 檢查 Node.js 版本：node -v
   • 檢查 Yarn 版本：yarn -v
   • 檢查 NPM 版本：npm -v
   • 檢查 Python 版本：python -V 或 python3 -V
   • 檢查 Go 版本：go version
   • 檢查 Java 版本：java -version
   • 檢查 .NET 版本：dotnet --version
   • 檢查 Ruby 版本：ruby -v 比對指令輸出的版本是否與 .servbay.config 內指定一致。

3. 透過網頁驗證（適用於 PHP）： 在專案根目錄建立一個簡單的 PHP 檔（如 info.php），內容為 <?php phpinfo(); ?>。於瀏覽器存取該檔（例如 http://your-project.servbay.demo/info.php），查看 phpinfo 顯示的 PHP 版本是否正確。

下圖可能展示了 ServBay 應用介面中反映專案級設定生效的畫面：

（請依實際 ServBay 應用輸出為準，以瞭解設定生效後的具體運作表現。）

注意事項

• .servbay.config 檔案名稱必須完全正確，不能有錯字。
• 檔案必須放於專案根目錄下。
• 檔案中指定的版本，必須為 ServBay 已安裝且支援的版本。
• 設定項目間請以換行區隔，每行一個 KEY=VALUE 組。
• 語法錯誤可能導致整份設定被忽略，或部分設定無效。
• .servbay.config 內的設定會覆蓋 ServBay 全域設定，僅適用於當前專案。

常見問題（FAQ）

Q: 如果我的專案根目錄沒有 .servbay.config 檔案怎麼辦？

A: 若無此檔，ServBay 會使用你於應用介面設定的全域環境來運行專案。

Q: 在 .servbay.config 內指定了尚未安裝的 ServBay 版本會如何？

A: ServBay 會顯示錯誤提示，具體行為依版本及設定而異。為確保設定生效，請先於 ServBay 應用安裝所需環境版本。

Q: 修改 .servbay.config 後需要重啟 ServBay 嗎？

A: 一般只需於 ServBay 應用中重新加載，或停止／啟動受影響的網站即可，無需完全退出 ServBay 應用。

Q: .servbay.config 內的設定會影響其他專案嗎？

A: 不會。.servbay.config 屬於專案級設定，只會影響其所屬 ServBay 網站目錄。

小結

ServBay 透過 .servbay.config 檔案，為開發者帶來強大的專案級環境管理能力。不論是維護依賴特定舊版環境的舊有專案，或開發需採用新技術棧的新專案，都能透過簡單的設定靈活切換與環境隔離，大幅提升本地開發的彈性與效率。善用這個特性，讓你的開發流程更加順暢高效！