ServBay PHP 版本管理：命令列與網站環境設定指南

ServBay 是一款強大的本地 Web 開發環境工具，支援 macOS 與 Windows，多種程式語言及資料庫皆可運行。本文將詳細介紹如何在 ServBay 中彈性管理不同專案的 PHP 版本，不論是命令列下執行腳本，或為特定網站提供服務。熟練掌握 ServBay 的 PHP 版本管理機制，將大幅提升你的開發效率，確保專案環境隔離與穩定性。

一、命令列環境：以 .servbay.config 管理專案級 PHP 版本

在專案根目錄建立 .servbay.config 設定檔，開發者可為每個專案指定獨立命令列 PHP 版本。ServBay 會根據目前終端機所在目錄，自動載入對應的 PHP 環境，達成專案間的版本隔離，避免全域設定衝突。

1. .servbay.config 的用途與運作原理

• 專案級版本控管： ServBay 允許同時安裝並運行多個 PHP 版本，由 PHP 5.6 至最新穩定版與開發版。利用 .servbay.config，你可精確指定每個專案所需 PHP 版本。
• 非侵入式切換： 當在終端機使用 cd 進入包含 .servbay.config 檔案的專案目錄時，ServBay 會自動偵測該檔案，並暫時修改目前終端機會議的環境變數（主要是 PATH），使 php、composer 等指令均指向指定版本的 PHP 執行檔。離開該目錄後，環境即恢復為 ServBay 全域預設值，此種方式對系統環境無任何副作用。

2. 設定方法

請於你的專案根目錄建立 .servbay.config 檔案，並添加如下內容以指定 PHP 版本：

# 指定本專案使用的 PHP 版本（範例：採用 PHP 8.3）
PHP_VERSION=8.3

# 若本專案亦需特定 Node.js 版本，可一併指定（範例：使用 Node.js 20）
# NODE_VERSION=20

• PHP_VERSION 的值須為 ServBay 中已安裝之 PHP 版本標識，通常是主版本號或主次版本號（如 7.4, 8.1, 8.3, 8.5 等）。請確認指定版本已於 ServBay 中安裝並啟用。
• NODE_VERSION 設定方式相同，用於指定本專案所需 Node.js 版本。

效果驗證：

進入含 .servbay.config 檔案的專案目錄後開啟終端機，執行以下指令進行驗證：

$ pwd # 確認目前目錄為你的專案根目錄
$ php -v  # 檢查輸出的 PHP 版本是否為你設定之版本（如：PHP 8.3.x）
$ composer install  # 依賴解析與安裝將依據目前啟用的 PHP 版本進行

若你修改 .servbay.config 後仍未切換版本，建議關閉並重新打開終端機視窗，或使用 cd . 指令強制 ServBay 重新載入設定。

3. 注意事項與進階技巧

• 版本相容性： 如果執行專案指令時遇到如 "Class not found"、"Call to undefined function" 等錯誤，請先檢查專案依賴（如 composer.json）所需 PHP 版本範圍，且確認指定之 PHP 版本是否與專案及其依賴相容。部分舊專案可能仰賴已於新版 PHP 移除之功能或擴充（例如 PHP 7.2 已移除 mcrypt 擴充）。
• 全域預設值： 若目前目錄或上層目錄沒有 .servbay.config 檔案，ServBay 將採用你於圖形介面「設定」中指定的全域預設 PHP 版本。
• 多服務協同： .servbay.config 不僅可控管 PHP 版本，亦可指定 Node.js 版本（透過 NODE_VERSION）。這對於採用 PHP 為後端、Node.js 為前端建構工具（如 Webpack, Vite）之專案尤為實用。

4. 運作範例

以下展示如何於不同專案目錄使用 .servbay.config 自動切換 PHP 版本：

圖片說明：於 ServBay，切換至不同含自訂 .servbay.config 的目錄，執行 php -v 指令，終端機自動切換至檔案指定 PHP 版本。

二、網站環境：透過 ServBay 圖形介面管理 PHP 版本

ServBay 提供直覺式圖形介面，讓你為每個網站自訂 PHP 版本。網站環境的 PHP 版本與命令列環境獨立，你可依據實際網站需求自由選擇。

1. 設定流程

1. 開啟 ServBay 圖形介面： 啟動 ServBay 應用程式。
2. 進入網站管理： 點選主介面左側導覽列內的 網站 (Websites) 分頁。
3. 新增或編輯網站：
   • 點選左下角 + 按鈕，可新增新網站設定。
   • 亦可選擇既有網站設定進行編輯。
4. 配置網站屬性：
   • 根目錄 (Root Directory)： 指定網站檔案儲存路徑。建議採用 ServBay 預設網站路徑 /Applications/ServBay/www/ 下之子目錄，例如：/Applications/ServBay/www/your-website-name/public（像是 Laravel 或 Symfony 專案）。
   • 域名 (Domain)： 設定本地開發網站存取域名，如 your-website-name.servbay.demo。ServBay 為這些自訂域名自動設定本地 DNS 解析與 HTTPS 憑證（利用 ServBay User CA 或 ServBay Public CA），大幅提升開發與測試便利性。
   • PHP 版本 (PHP Version)： 於下拉選單挑選期望該網站使用之 PHP 版本。ServBay 會列出所有已安裝並啟用的 PHP 版本供選擇（如 7.4, 8.1, 8.3, 8.5 等）。
5. 儲存設定： 完成所有配置後，點選儲存按鈕。ServBay 將自動套用變更，可能需重新載入或重啟相關的 Web 伺服器與 PHP-FPM 程序。

2. 技術細節及優勢

• 服務隔離： ServBay 為每個網站配置的 PHP 版本通常以獨立的 PHP-FPM 程序池運行。此設計確保不同網站 PHP 環境完全隔離，某網站錯誤或記憶體洩漏不會影響其他網站。
• 效能最佳化： ServBay 所有套件（包括各版本 PHP）皆針對 ARM64 (Apple Silicon) 及 X86_64 架構特別最佳化，確保不同硬體平台均能發揮良好效能。
• 錯誤排除：
  • 查閱 PHP 錯誤日誌：網站運作中 PHP 錯誤通常記錄於 /Applications/ServBay/var/log/php/php_error.log。
  • 檢查 PHP-FPM 程序狀態：可利用 ServBay 命令列工具 servbayctl 查詢指定 PHP 版本運行狀態，例如 servbayctl status php 8.3。

3. Web 伺服器與資料庫整合

ServBay 極為彈性，能根據專案需求自選 Web 伺服器與資料庫：

• Web 伺服器支援： 於 ServBay 1.7.0 及以上版本，能輕鬆切換網站所用 Web 伺服器，支援 Apache、Nginx 與 Caddy。這些伺服器可無縫整合 ServBay 管理之 PHP-FPM 程序。
• 資料庫串接： ServBay 支援安裝及管理多版本 MySQL、MariaDB、PostgreSQL、MongoDB 與 Redis 等資料庫套件。你可於網站設定或專案程式碼中，連接 ServBay 運行之指定資料庫實例，彈性應付需要指定資料庫版本或類型的專案（如某些 Laravel 專案更適用 MariaDB 11.x）。

三、跨環境協作與最佳實踐

理解命令列環境與網站環境 PHP 版本管理的獨立性及其配置方法，有助於你在不同開發情境做出最佳選擇：

情境	命令列環境設定（.servbay.config）	網站環境設定（ServBay GUI）	備註
維護舊系統	專案根目錄設定 PHP_VERSION=5.6	網站設定中選用 PHP 5.6	確保舊專案所需 PHP 版本及擴充均已於 ServBay 安裝。
新專案開發（如 Laravel 11）	設定 PHP_VERSION=8.3（或更新），可同時指定 NODE_VERSION=20	新增網站，根目錄指向專案 public 資料夾，選用 PHP 8.3+，配置開發域名並啟用 HTTPS	保持命令列工具（Composer, Artisan, Node 前端建構）與 Web 環境 PHP 版本一致。
未來 PHP 版本測試	測試專案根目錄設定 PHP_VERSION=8.5	新增測試網站並選擇 PHP 8.5	用於預先測試專案對新版 PHP 的相容性。
執行 Composer 指令	確保當前目錄或上層目錄 .servbay.config 已指定正確 PHP 版本	N/A（Composer 主要於命令列執行）	Composer 會採用目前終端機所啟用之 PHP 版本。

注意事項

• CLI 與 Web 環境差異： 即使採用同版本 PHP，命令列（CLI）與網站（PHP-FPM）環境的預設設定與載入之擴充模組可能有所不同。例如，opcache 擴充通常於 PHP-FPM 模式預設啟用以提升效能，但在 CLI 模式下可能預設停用。若發現行為差異，請分別檢查 php.ini 檔（ServBay 中不同 PHP 版本均有獨立 php.ini），以及已載入之擴充模組。
• 更新 ServBay Runtime： 請確保 ServBay 應用程式及其 Runtime 隨時維持最新版。ServBay 團隊持續推送更新，包括最新 PHP 版本與安全修補。更新 ServBay 一般會自動升級 Runtime，獲得最新功能與改進。

常見問題解答 (FAQ)

Q: 命令列與網站環境的 PHP 版本衝突怎麼辦？

A: 命令列環境（經 .servbay.config 控制）與網站環境（經 ServBay GUI 控制）為獨立機制。.servbay.config 僅影響你目前終端機會議中的 php 指令連結至哪個版本；網站設定則決定 Web 伺服器（如 Apache/Nginx/Caddy）透過 PHP-FPM 呼叫哪個 PHP 版本處理網頁請求。兩者間不會直接衝突。你可以針對同一專案於命令列使用一個 PHP 版本（如用於 Composer 或 Artisan 指令），網站端則用不同版本（如實際網站運行環境），惟一般不建議此做法，為確保開發與正式環境一致，建議兩者盡量保持同一版本。

總結

ServBay 透過 .servbay.config 設定檔與直覺式圖形介面，讓開發者能夠強大且彈性地管理 PHP 版本。不論你需維護舊版 PHP 遺留專案，還是以最新 PHP 開發新應用，ServBay 都能助你迎刃而解。善用這些功能，能確保本地開發環境貼近正式環境，提升效率與專案穩定性。