在 ServBay 中編譯與安裝自訂 PHP 模組（macOS）

ServBay 是專為 macOS 設計的強大本機 Web 開發環境，整合多樣軟體包以滿足現代 Web 開發者的需求。其預先集成 PHP、Node.js、Python、Go、Java、資料庫（如 MySQL、PostgreSQL、MongoDB）、快取（Redis），以及 Web 伺服器（Caddy、Nginx、Apache）等多項技術堆疊。ServBay 支援每個軟體包的多版本切換，讓您能依據專案需求彈性調整開發環境。

雖然 ServBay 已內建多數常用 PHP 模組，但某些特殊開發場景下，您仍須自行編譯並安裝額外 PHP 模組，以擴展 PHP 功能或整合特定第三方服務。

本文件將提供詳細的圖文教學，說明如何於 ServBay 環境下，為特定 PHP 版本編譯與安裝自訂模組。我們以常見的 imagick 圖像處理模組與 sqlsrv Microsoft SQL Server 驅動為例，闡明完整流程，協助您順利將所需功能加到 ServBay 的 PHP 環境中。

前置準備

重要提示

在編譯任何 PHP 模組前，最關鍵的步驟就是依照 ServBay 官方文件，完成編譯環境初始化並正確設定系統環境變數。這是成功編譯 ServBay 軟體包（包括 PHP 模組）的基礎。若略過或未正確設定，此後的編譯極可能失敗，發生找不到指令、函式庫或標頭檔等錯誤。

ServBay 的初始化腳本會自動設置必需的變數，例如 PATH（指向 ServBay 內部建構工具）、SERVBAY_PACKAGE_FULL_PATH（ServBay 軟體包根路徑）、CPU_NUMBER（供多核編譯）。這些變數對後續所有編譯操作至關重要。

完整初始化 ServBay 編譯環境的說明，請務必參考：使用 ServBay 進行二次編譯。請確認您已充分理解並嚴格依照文件說明完成所有必要設定。

在繼續編譯模組前，請務必確認您已成功初始化 ServBay 編譯環境，且相關變數於目前終端機環境中已正確設置。

為什麼一定要指定 PHP 版本

ServBay 一大核心優勢即支援同時安裝/運行多個 PHP 版本，使開發者能針對不同專案靈活切換 PHP 環境。然當您需自行編譯 PHP 模組時，必須為特定 PHP 版本執行操作。這是因為用於準備編譯環境及獲取組態資訊的兩個工具 phpize 和 php-config，皆與指定的 PHP 版本高度綁定。

phpize：負責為 PHP 擴充模組建立標準化的編譯環境（例如自動化產生 configure 腳本），是 C/C++ 編譯流程常見的第一步。
php-config：提供關於特定 PHP 安裝的詳細組態，例如編譯器旗標、include 檔案目錄、函式庫目錄與擴展安裝路徑等。configure 腳本會呼叫 php-config 取得所有需要資訊，使模組能正確與對應 PHP 版本編譯與連結。

因此，運行 phpize、php-config 或相關命令時，請務必以完整路徑指定您欲編譯之 PHP 版本。例如，若想為 PHP 8.3 編譯模組，應使用 /Applications/ServBay/package/php/8.3/current/bin/phpize 及 /Applications/ServBay/package/php/8.3/current/bin/php-config。這能確保所編譯模組百分百相容目標 PHP 環境，避免出現進一步錯誤或執行期間「無法找到符號」等問題。

本文示範皆以 ServBay 所安裝之PHP 8.3 為例說明。您實際操作時，請將相關命令路徑替換成專案所用的 PHP 版本所在路徑。

編譯 PHP imagick 模組

imagick 是 PHP 極為熱門的影像處理擴充，基於強大的 ImageMagick 函式庫，可讓 PHP 執行縮放、裁剪、格式轉換、浮水印、圖像合成等各式影像處理。下面說明於 ServBay 為指定 PHP 版本編譯安裝 imagick 的完整步驟：

步驟 1：安裝 ImageMagick 依賴函式庫

imagick 必須依賴系統已安裝 ImageMagick 函式庫。macOS 推薦利用 Homebrew 套件管理器安裝。若您尚未安裝 Homebrew，請參考 Homebrew 官方網站。

開啟終端機，輸入下列指令安裝 ImageMagick 及相關開發檔：

bash

brew install imagemagick

步驟 2：取得 imagick 模組原始碼

接下來需至 PHP 擴充庫（PECL）官網下載 imagick 的原始碼壓縮檔。請至 PECL imagick 頁面，選取所需版本（多選最新穩定版），並複製下載鏈結。以目前較新版本 3.7.0 為例：

bash

wget https://pecl.php.net/get/imagick-3.7.0.tgz

步驟 3：解壓原始碼，切換目錄

下載完成後，使用 tar 解壓原始碼，並進入模組所在資料夾：

bash

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

步驟 4：準備編譯環境（執行 phpize）

進入模組原始碼資料夾後，務必用目標 PHP 版本之 phpize 來建立編譯環境（即用完整路徑）。假設目標為 PHP 8.3，且已設好 SERVBAY_PACKAGE_FULL_PATH 變數：

bash

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

成功後，phpize 會找出原始碼的 config.m4，自動產生 configure 編譯腳本與必要檔案，終端機會顯示相關訊息。

步驟 5：設定編譯選項

執行剛剛產生的 configure 腳本，進行原始碼組態。這步務必用 --with-php-config 明確指定正確 PHP 版本的 php-config 路徑，以確保所有參數皆對應正確的 PHP：

bash

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

configure 會自動檢查 ImageMagick 相關依賴，產生最終用於編譯的 Makefile。如有錯誤，通常都是依賴未安裝或路徑設錯。

步驟 6：編譯與安裝模組

組態正確後，使用 make 編譯，再用 make install 安裝模組。其中 ${CPU_NUMBER} 變數預設於 ServBay 初始化時設定，代表要開幾個執行緒加速編譯。

bash

make -j ${CPU_NUMBER}
make install

make install 會自動把產生的 imagick.so 送到對應 PHP 版本的擴充目錄（例如 /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/，實際依 PHP 版本與建構選項而異）。

步驟 7：啟用模組

模組檔安裝好之後，需在該 PHP 版本的設定檔中啟用它。ServBay 提供圖形化啟用流程：

開啟 ServBay 程式
於左側選單導覽至「語言」→ 「PHP」→ 「PHP 8.3」
於右側頁面，選 PHP 分頁，滑到最下方「額外參數」中，輸入 extension=imagick.so
點選「儲存」，PHP 會自動重啟並套用新模組

步驟 8：驗證模組是否載入

啟用模組後，請務必重啟對應 PHP 套件，讓設定生效。您可在 ServBay 管理介面點擊重啟，或用 ServBay CLI 工具（細節請查官方文件）。

重啟後，可用以下指令檢查 imagick 是否載入：

bash

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

此處指定 PHP 完整路徑，是確保呼叫到正確 ServBay PHP 版本。-m 參數會列出所有已載入模組。若模組已正確啟用，輸出裡會有 imagick。

更詳細的驗證方式，請於網站根目錄（預設 /Applications/ServBay/www）新增 PHP 檔（如 info.php），內容：

php

<?php phpinfo(); ?>

然後用瀏覽器訪問 http://localhost/info.php 或您的 ServBay 網站網址，搜尋「imagick」即可檢查是否啟用、其組態與版本資訊。

編譯 PHP sqlsrv/pdo_sqlsrv 模組

sqlsrv 和 pdo_sqlsrv 是 PHP 官方擴充，用來連接與操作 Microsoft SQL Server 資料庫。此模組依賴 Microsoft ODBC 驅動。若您在 ServBay PHP 環境需與 SQL Server 互通，請依此步驟編譯安裝：

注意：重要先決條件

在 macOS 下編譯安裝 sqlsrv，必須先安裝 Microsoft 發行的 SQL Server ODBC 驅動（msodbcsql18）與命令列工具（mssql-tools18）。這些包不隨 ServBay 附帶，需手動安裝。

強烈推薦用 Homebrew 安裝所有依賴。未安裝 Homebrew 者，請見 Homebrew 官網。

安裝命令如下，過程中需同意授權協議（以環境變數 HOMEBREW_ACCEPT_EULA=Y）：

bash

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

務必確認所有依賴已安裝且成功，安裝後預設於 /opt/homebrew/（Apple Silicon）或 /usr/local/（Intel）。編譯時需正確設定相關路徑。

提示

sqlsrv 與 pdo_sqlsrv 為兩組不同模組，需分開編譯，但流程幾乎一致，以下以 sqlsrv 示範。

步驟 1：安裝 Microsoft ODBC 驅動與工具

（如上所述，務必先以 Homebrew 裝好 msodbcsql18 與 mssql-tools18。）

步驟 2：取得 sqlsrv 模組原始碼

請至 PECL 官網下載 sqlsrv 及 pdo_sqlsrv 模組壓縮檔。官網連結：PECL sqlsrv。例如以下新發行的 5.12.0 版本：

bash

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

步驟 3：解壓原始碼並切目錄

下載好後，解壓縮，切入該模組資料夾：

bash

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# pdo_sqlsrv 亦同，下文僅以 sqlsrv 為例

步驟 4：準備編譯環境（執行 phpize）

進入原始碼資料夾後，用對應 PHP 版本的 phpize 準備環境。例如 PHP 8.3：

bash

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

步驟 5：設定編譯參數（含依賴路徑）

執行 configure 前，需以環境變數 LDFLAGS 和 CPPFLAGS 指定 Homebrew 函式庫及標頭檔目錄。這可讓 configure 找到所有必須依賴。同樣，以 --with-php-config 指定 PHP 組態路徑。

請依據 Homebrew 安裝路徑（Intel 為 /usr/local，Apple Silicon 通常 /opt/homebrew）調整範例。以下假設 Homebrew 裝於 /opt/homebrew：

bash

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # 添加 /opt/homebrew/include 確保找到全部標頭
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

LDFLAGS: 設定連結器搜索函式庫路徑。-L/opt/homebrew/lib 即 Homebrew 預設函式庫位置。
CPPFLAGS: 設定 C/C++ 預處理器搜尋標頭目錄。其中 -I/opt/homebrew/opt/unixodbc/include 指向 unixODBC 標頭。-I/opt/homebrew/include 用來找其他必要標頭。${CPPFLAGS} 與 ${LDFLAGS} 保持 ServBay 可能用到的原先參數。

步驟 6：編譯與安裝模組

組態完畢 Makefile 產生後，執行 make 編譯與 install 安裝：

bash

make -j ${CPU_NUMBER}
make install

make install 會將 sqlsrv.so、pdo_sqlsrv.so（若一起編譯）安裝至對應 PHP 擴展路徑。

步驟 7：啟用模組

模組檔生產後，請在該 PHP 版本設定檔啟用。ServBay 提供圖形介面：

開啟 ServBay 程式
左側選單至「語言」>「PHP」>「PHP 8.3」
右側頁面選「PHP」標籤，滑到最底於「額外參數」欄輸入 extension=sqlsrv.so 與 extension=pdo_sqlsrv.so
點選「儲存」，PHP 自動重啟並載入新模組

步驟 8：驗證模組載入

啟用後，務必重啟 ServBay PHP，使新設定生效。

重啟完畢後，您可執行下列指令檢查 sqlsrv、pdo_sqlsrv 是否成功載入：

bash

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

若成功，輸出會顯示 sqlsrv、pdo_sqlsrv。亦可用 phpinfo() 輸出確認模組狀態與詳細參數。

常見問題 (FAQ)

Q: 編譯過程出現 "Cannot find autoconf" 或類似錯誤？
- A: 幾乎可確定是尚未初始化 ServBay 編譯環境。請回到本文「前置準備」段落，詳閱使用 ServBay 進行二次編譯，並確認已妥善設置所有編譯相關環境變數與工具（autoconf、automake、libtool 等）。一般重跑初始化腳本並重開終端機即可。
Q: configure 步驟失敗，提示找不到某函式庫或標頭檔？
- A: 表示系統未安裝某個必要函式庫或標頭，或 configure 沒找到正確路徑。
  - 若為 imagick，請確保已安裝 ImageMagick 開發庫（brew install imagemagick）。
  - 若為 sqlsrv，請務必按前述說明以 Homebrew 安裝 Microsoft ODBC 驅動（msodbcsql18）及 mssql-tools18。並請於 configure 前，正確設置 LDFLAGS、CPPFLAGS，包含所有必要路徑（如 /opt/homebrew/lib、/opt/homebrew/opt/unixodbc/include）。
  - 請檢查 ServBay 編譯環境 PATH 是否有包含 Homebrew 路徑（若依賴是用 Homebrew 安裝），如有需要請將 Homebrew 的 bin 資料夾手動加入環境變數 PATH。
Q: make 或 make install 過程失敗？
- A: 有幾種常見原因：
  - 缺少編譯依賴程式： 請查閱終端機訊息，上面會寫清楚是哪個檔案缺失，據訊息安裝對應依賴。
  - 組態有誤： 請回查 configure 步驟，檢查各個參數有無正確指定，特別是 --with-php-config 是否指向正確的 PHP 版本。
  - 權限問題： make install 會將檔案複製到 ServBay 指定資料夾，若權限未設好可能失敗。必要時可考慮 sudo make install（使用時請謹慎）。
  - 原始碼異常： 檢查模組原始碼壓縮檔是否正確下載或有損毀。
Q: 編譯後 .so 檔已存在於擴展目錄，設定也啟用，但 php -m 與 phpinfo() 查不到模組？
- A:
  - 最常見原因： 尚未重啟 PHP 套件。請務必於更改 .ini 後，於 ServBay 管理介面或 CLI 完全重啟目標 PHP 版本。單純刷新網頁或重啟 Web 伺服器（Caddy/Nginx）無效，一定要重啟 PHP 套件本身。
  - .ini 檔語法出錯：請檢查 .ini 檔內容，例如 extension=modulename.so 拼字或格式是否有誤。
  - 擴展路徑設錯：於 php.ini 內確認 extension_dir 是否正確指向應有位置。可直接查詢 php-config --extension-dir 確認。
  - 模組檔案損毀或 PHP 版本不符：請嘗試重編一次，且確認原始碼版本相容您的 PHP。也可查閱 PHP 日誌（通常於 ServBay 安裝資料夾 logs）是否有載入失敗訊息。

結語

依本文指引循序操作，您即可於 ServBay macOS 本機開發環境順利編譯並安裝如 imagick、sqlsrv 等自訂 PHP 模組。整體流程重點包括：

正確且完整初始化 ServBay 編譯環境：這是所有後續編譯任務能順利進行的關鍵。
明確指定正確 PHP 版本路徑：執行 phpize、php-config 時，必須指出您真正要安裝模組的 ServBay PHP 版本路徑。
針對模組安裝必要外部依賴：安裝所需系統函式庫（如 ImageMagick、Microsoft ODBC），並於 ./configure 步驟透過環境變數（如 LDFLAGS、CPPFLAGS）或參數傳遞正確路徑，確保 configure 能正確檢測所有依賴。
正確啟用模組於 PHP 設定中：於目標 PHP 版本的 conf.d 資料夾新增或修改 .ini 檔，用 extension=modulename.so 指令載入。
確實重啟 ServBay PHP 套件：確保所有新設定與模組載入後能生效。

ServBay 做為全方位本機開發平台，讓您輕鬆兼容並支援各式開發需求。除上述 PHP 模組外，還預整合並支援 MySQL、PostgreSQL、MongoDB、Redis、Caddy、Nginx、Apache、Node.js、Python、Go、Java、.NET、Ruby、Rust 等多種技術。平台同時提供眾多實用功能，像是使用 ACME 申請真實 SSL 證書、簡易 CORS 設定、自動資料備份（含設定檔、網站、資料庫、SSL）、重設資料庫 root 密碼，以及專屬 ServBay User CA 與 Public CA 用於本地 HTTPS 開發等，全方位協助您打造高效率、好用且功能強大的本機開發工作流。

希望本指南能助您順利優化 ServBay PHP 環境，開發效率大增。如遇其他疑難，歡迎查閱 ServBay 官方文件或社群支援資源。

在 ServBay 中編譯與安裝自訂 PHP 模組（macOS） ​

前置準備 ​

為什麼一定要指定 PHP 版本 ​

編譯 PHP imagick 模組 ​

步驟 1：安裝 ImageMagick 依賴函式庫 ​

步驟 2：取得 imagick 模組原始碼 ​

步驟 3：解壓原始碼，切換目錄 ​

步驟 4：準備編譯環境（執行 phpize） ​

步驟 5：設定編譯選項 ​

步驟 6：編譯與安裝模組 ​

步驟 7：啟用模組 ​

步驟 8：驗證模組是否載入 ​

編譯 PHP sqlsrv/pdo_sqlsrv 模組 ​

步驟 1：安裝 Microsoft ODBC 驅動與工具 ​

步驟 2：取得 sqlsrv 模組原始碼 ​

步驟 3：解壓原始碼並切目錄 ​

步驟 4：準備編譯環境（執行 phpize） ​

步驟 5：設定編譯參數（含依賴路徑） ​

步驟 6：編譯與安裝模組 ​

步驟 7：啟用模組 ​

步驟 8：驗證模組載入 ​

常見問題 (FAQ) ​

結語 ​

在 ServBay 中編譯與安裝自訂 PHP 模組（macOS）

前置準備

為什麼一定要指定 PHP 版本

編譯 PHP imagick 模組

步驟 1：安裝 ImageMagick 依賴函式庫

步驟 2：取得 imagick 模組原始碼

步驟 3：解壓原始碼，切換目錄

步驟 4：準備編譯環境（執行 phpize）

步驟 5：設定編譯選項

步驟 6：編譯與安裝模組

步驟 7：啟用模組

步驟 8：驗證模組是否載入

編譯 PHP sqlsrv/pdo_sqlsrv 模組

步驟 1：安裝 Microsoft ODBC 驅動與工具

步驟 2：取得 sqlsrv 模組原始碼

步驟 3：解壓原始碼並切目錄

步驟 4：準備編譯環境（執行 phpize）

步驟 5：設定編譯參數（含依賴路徑）

步驟 6：編譯與安裝模組

步驟 7：啟用模組

步驟 8：驗證模組載入

常見問題 (FAQ)

結語