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

ServBay 是一款強大的本機 Web 開發環境工具，專為 macOS 設計，支援多種程式語言與資料庫。本文將詳細介紹如何在 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 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 或 Public CA），大幅便利開發與測試工作。
   • PHP Version (PHP 版本)： 下拉選單中選擇希望此網站採用的 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. 網站伺服器與資料庫整合

ServBay 高度彈性，讓你能根據專案需求選擇不同網站伺服器與資料庫：

• 網站伺服器支援： 於 ServBay 1.7.0 及以上版本，你可輕鬆切換網站所用網站伺服器，支援 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 構建工具）與網站 PHP 版本一致。
測試未來 PHP 版本	於測試專案根目錄設定 PHP_VERSION=8.5	新增測試網站並選用 PHP 8.5	提前驗證專案是否支援新 PHP 版本。
執行 Composer 指令	確認目前（或上層）目錄的 .servbay.config 有正確指定 PHP 版本	不適用 (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 命令指向哪個版本；網站設定則決定網站伺服器（Apache/Nginx/Caddy）透過 PHP-FPM 呼叫何種 PHP 版本來處理 Web 請求。兩者之間不會發生直接衝突。你可以針對同一專案，在命令列用一個 PHP 版本（如執行 Composer 或 Artisan 指令），網站環境用另一個 PHP 版本（如實際運行網站），但通常不建議這麼做。為了確保開發與正式環境一致，建議最好保持兩者版本一樣。

總結

ServBay 結合 .servbay.config 檔案與直覺的圖形介面，為開發者帶來強大靈活的 PHP 版本管理能力。無論你需維護倚賴舊 PHP 版本的專案，還是用新版本開發新應用，ServBay 都能讓你輕鬆因應。合理運用這些功能，可讓你的本機開發更貼近生產環境，大幅提升開發效率及專案穩定性。