如何在 ServBay 中載入第三方 PHP 擴充

ServBay 是一款強大的本地 Web 開發環境，內建多種常用的 PHP 擴充。用戶一般只需在 ServBay 的套件 (Packages) -> 語言 (Languages) -> PHP 版本 -> 擴充中進行勾選啟用即可。

然而，開發者有時需要載入 ServBay 預設未包含的第三方或自訂編譯的 PHP 擴充。本文將詳細指引您如何在 ServBay 中，針對指定 PHP 版本載入這類擴充，以 ionCube Loader 為例進行示範。此流程同樣適用於其他 Zend 擴充或您自行編譯的 .so 擴充檔案。

關於 Zend 擴充的特別說明： ionCube Loader 屬於 Zend 擴充，這類擴充會與 PHP 的 Zend 引擎有更深層互動。因此，設定時應使用 zend_extension 指令，而非一般擴充使用的 extension。請務必加以區分與正確使用。

前置條件

您已於 macOS 上安裝並執行 ServBay。
您擁有管理員權限，可操作系統檔案及 ServBay 設定介面。
您熟悉使用 macOS 終端機（Terminal）。
您已確認需要載入的第三方 PHP 擴充檔案（一般為 .so 檔），且該檔需與 ServBay 中指定 PHP 版本的 PHP 版本、架構 (Intel 或 Apple Silicon) 及編譯選項（如 NTS/ZTS）完全相容。

注意：架構相容性至關重要

ServBay 針對 Intel(x86_64) 及 Apple Silicon (ARM64，如 M1/M2/M3/M4 晶片) 架構均提供原生 PHP 套件。載入 .so 擴充檔時，必須確認該 .so 檔案的編譯架構與 ServBay 對應 PHP 套件架構一致。

不同架構的檔案無法混用，架構不一致將導致 PHP 無法啟動或直接崩潰。

您可用 file 指令來查詢可執行檔或 .so 檔案的架構：

確認 ServBay 內附的 PHP 套件架構（請將 8.3 替換為您實際的 PHP 版本）：

bash

file /Applications/ServBay/package/php/8.3/current/bin/php

輸出範例如下：

/Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # 代表 Apple Silicon ARM64 架構

或是

/Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # 代表 Intel x86_64 架構

確認您下載或編譯的 .so 擴充檔案架構（請將 xdebug.so 換成您的擴充檔名）：
bash
```
file xdebug.so
```
1
範例輸出：
```
xdebug.so: Mach-O 64-bit bundle arm64 # 代表 Apple Silicon ARM64 架構
```
1
或
```
xdebug.so: Mach-O 64-bit bundle x86_64 # 代表 Intel x86_64 架構
```
1
請確保步驟 1 與步驟 2 的架構資訊完全相符。

操作步驟

步驟 1：下載第三方擴充檔案（以 ionCube Loader 為例）

前往 ionCube Loader 的官方下載頁。請依您的 macOS 架構下載合適版本。若為 macOS ARM64 (Apple Silicon M 系列晶片)，請下載 Darwin ARM64 版本。您可參考下方範例連結（請確認官網是否有新版，僅供參考）： https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
下載完畢後，您會獲得一個 .tar.gz 壓縮檔，例如 ioncube_loaders_dar_arm64.tar.gz。

步驟 2：確認目標 PHP 版本與 ServBay 擴充安裝目錄

開啟 ServBay 應用程式。
於左側導覽列點擊 套件 (Packages) 下的 語言 (Languages)。
於右側列表中，尋找您欲安裝 ionCube Loader 的 PHP 版本（如，本例用 PHP 8.3），並記下其版本號。
查找此 PHP 版本在 ServBay 中的擴充安裝目錄 (extension_dir)，即存放 .so 檔之標準路徑。ServBay PHP 擴充一般放置於指定目錄，實際路徑和安裝位置、PHP 版本及編譯選項有關。
最準確方式為終端機查詢：
開啟終端機（Terminal），執行下方指令（將 /Applications/ServBay/package/php/8.3/current/bin/php 換成您目標 PHP 版本的 php 執行路徑）：
bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir
```
1
終端機輸出會顯示 extension_dir => /path/to/extension/directory。如：
```
extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831
```
1
請記下此精確路徑，後續會用到。

步驟 3：解壓並放置 Loader 檔案

開啟終端機。
用 cd 指令切換到您下載 .tar.gz 壓縮檔的目錄（預設可能為 ~/Downloads）：
bash
```
cd ~/Downloads
```
1
解壓縮下載的檔案：
bash
```
tar -zxvf ioncube_loaders_dar_arm64.tar.gz
```
1
完成後，當前目錄會多一個 ioncube 新目錄。
進入 ioncube 目錄：
bash
```
cd ioncube
```
1
在此目錄下，找到對應您目標 PHP 版本的 .so 檔，例如 ioncube_loader_dar_8.3.so。請依您前述確認的 PHP 版本（例：8.3）選對檔案。
將此 .so 檔複製到步驟 2 查得的 PHP 擴充安裝目錄。例如若目標資料夾為 /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/，且安裝的是 PHP 8.3 之 Loader：
bash
```
cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/
```
1
- 請務必將路徑 /Applications/ServBay/.../no-debug-non-zts-20230831/ 替換為您實際用 php -i 得到的擴充目錄路徑。
- 確保您複製的是目標 PHP 版本且與 PHP 套件架構完全相符的 .so 檔（架構檢查請見前置條件章節）。

步驟 4：於 ServBay 設定 PHP

回到 ServBay 介面。
確認已選擇左側 語言 (Languages)，點擊右側列表欲設定的 PHP 版本（例：PHP 8.3）。
展開配置頁，點擊 PHP 分頁。
下拉至 Additional Parameters（附加參數）文字框。
在此框中新增下列指令，指定 ionCube Loader 檔名：
ini
```
zend_extension = ioncube_loader_dar_8.3.so
```
1
- 重要： 請將 ioncube_loader_dar_8.3.so 換成您實際複製至擴充目錄之檔名。
- 請必須使用 zend_extension（非 extension），因 ionCube Loader 屬於 Zend 擴充。
- 既然 .so 檔已放於 extension_dir，此處僅需檔名，無須填寫完整路徑。
- 若此框已有其他設定（每行一條），請換行新增本指令。
(截圖僅供參考，實際介面隨版本可能略有不同)
點擊右下角 Save 按鈕儲存設定。

步驟 5：重啟 PHP 服務

點擊 ServBay 內的 Save 後，ServBay 會自動偵測到設定變更並嘗試平滑重啟相關服務（包括 PHP）。通常無需再手動重啟。

步驟 6：驗證是否載入成功

您可透過以下兩種常見方式，檢查 ionCube Loader 是否已正確載入：

命令列驗證：
- 開啟終端機。
- 執行下列指令，列出已載入的 PHP 模組（請指向目標 PHP 版本的完整路徑）：
  bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube
```
  1
  若成功，終端機會顯示如 ionCube Loader 的結果。
- 也可執行 php -v 觀察 PHP 版本訊息，正確載入後通常會於 Zend Engine 版本下方出現 ionCube Loader 資訊：
  bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -v
```
  1
  範例結果（實際版本號依所安裝為準）：
```
PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.16, Copyright (c) Zend Technologies
    with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.
```
  1
  2
  3
  4
  請留意 with the ionCube PHP Loader ... 這一行。
透過 phpinfo() 驗證：
- 於您的網站根目錄（如 /Applications/ServBay/www/servbay.demo/ 或您設定的其他路徑）新建一個 PHP 檔，如 info.php。
- 檔案內容僅需：
  php
```
<?php
phpinfo();
?>
```
  1
  2
  3
- 於瀏覽器開啟該檔案，例如 http://servbay.demo/info.php（請以您的本地網域替換）。
- 於 phpinfo() 頁面中，用瀏覽器搜尋 "ionCube"（可用 Cmd + F 或 Ctrl + F）。如已正確載入，您將看到專屬的 ionCube Loader 資訊區塊，內容包含版本、授權等細節。

若以上驗證皆顯示 ionCube Loader 資訊，則載入成功。

常見問題與故障排解

PHP 啟動失敗或閃退： 最常見原因為擴充檔案架構與 PHP 套件架構不相符。請嚴格依前述步驟反覆確認架構。PHP 版本或編譯選項不符也可能導致失敗。
extension_dir 路徑錯誤： 請確定 .so 檔已複製到目標 PHP 版本於 ServBay 中的實際 extension_dir。請利用 php -i | grep extension_dir 查到的路徑最為準確。
設定指令有誤： 請確認在 ServBay Additional Parameters 欄內輸入的指令無誤。Zend 擴充需用 zend_extension = filename.so；一般擴充用 extension = filename.so。檔名需完全相符（含大小寫）。
檔案權限問題： 請確保 ServBay 執行用戶（多為您的 macOS 用戶）對所複製的 .so 檔及其目錄具備讀取權。若曾更動過權限請檢查。
ServBay 未自動重啟： 若發現設定未生效，可在 ServBay 介面手動停止再啟動服務，或直接關閉並重啟 ServBay。
phpinfo() 找不到載入資訊： 請確認存取的網站為由 ServBay 管理並已設定擴充的 PHP 版本環境。若環境有多個 PHP 或多組網站，請核對真的是正確環境。

總結

按照上述詳細步驟，您將可順利於 ServBay 管理的特定 PHP 版本中載入 ionCube Loader 或其他第三方 .so 格式的 PHP 擴充。重點在於準確識別目標 PHP 版本、正確尋找安裝目錄（extension_dir）、將相容的擴充檔案存放於該目錄，以及在 ServBay 設定介面 Additional Parameters 欄正確填寫指令（zend_extension 或 extension）。若安裝遇阻，請詳閱故障排解章節，尤其注意架構相容性與檔案路徑正確。

如何在 ServBay 中載入第三方 PHP 擴充 ​

前置條件 ​

操作步驟 ​

步驟 1：下載第三方擴充檔案（以 ionCube Loader 為例） ​

步驟 2：確認目標 PHP 版本與 ServBay 擴充安裝目錄 ​

步驟 3：解壓並放置 Loader 檔案 ​

步驟 4：於 ServBay 設定 PHP ​

步驟 5：重啟 PHP 服務 ​

步驟 6：驗證是否載入成功 ​

常見問題與故障排解 ​

總結 ​