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 版本:
bash
# 指定本專案使用的 PHP 版本(範例:採用 PHP 8.3)
PHP_VERSION=8.3
# 若本專案亦需特定 Node.js 版本,可一併指定(範例:使用 Node.js 20)
# NODE_VERSION=20
1
2
3
4
5
2
3
4
5
PHP_VERSION
的值須為 ServBay 中已安裝之 PHP 版本標識,通常是主版本號或主次版本號(如7.4
,8.1
,8.3
,8.5
等)。請確認指定版本已於 ServBay 中安裝並啟用。NODE_VERSION
設定方式相同,用於指定本專案所需 Node.js 版本。
效果驗證:
進入含 .servbay.config
檔案的專案目錄後開啟終端機,執行以下指令進行驗證:
bash
$ pwd # 確認目前目錄為你的專案根目錄
$ php -v # 檢查輸出的 PHP 版本是否為你設定之版本(如:PHP 8.3.x)
$ composer install # 依賴解析與安裝將依據目前啟用的 PHP 版本進行
1
2
3
2
3
若你修改 .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. 設定流程
- 開啟 ServBay 圖形介面: 啟動 ServBay 應用程式。
- 進入網站管理: 點選主介面左側導覽列內的 網站 (Websites) 分頁。
- 新增或編輯網站:
- 點選左下角 + 按鈕,可新增新網站設定。
- 亦可選擇既有網站設定進行編輯。
- 配置網站屬性:
- 根目錄 (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 等)。
- 根目錄 (Root Directory): 指定網站檔案儲存路徑。建議採用 ServBay 預設網站路徑
- 儲存設定: 完成所有配置後,點選儲存按鈕。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
。
- 查閱 PHP 錯誤日誌:網站運作中 PHP 錯誤通常記錄於
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 都能助你迎刃而解。善用這些功能,能確保本地開發環境貼近正式環境,提升效率與專案穩定性。