在 ServBay 編譯與安裝自訂 PHP 模組

ServBay 是一款適用於 macOS 和 Windows 的強大本地網頁開發環境，整合多種軟體包，滿足現代 Web 開發者需求。其內建多版本 PHP、Node.js、Python、Go、Java，以及資料庫（如 MySQL、PostgreSQL、MongoDB）、快取（Redis）和網頁伺服器（Caddy、Nginx、Apache）等多元技術。ServBay 為每一套軟體包提供多版本支援，讓你能依專案需要彈性切換環境。

雖然 ServBay 已包含許多常用的 PHP 模組，但特定開發場景下，你可能需要編譯及安裝額外 PHP 模組，以擴展 PHP 功能或整合特定第三方服務。

本篇將詳盡說明如何在 ServBay 環境下，為你的 PHP 版本編譯及安裝自訂模組。我們將以常見的 imagick 圖像處理模組與 sqlsrv 微軟 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 擴充模組的編譯環境。它會讀取 config.m4 檔案，並生成標準的 configure 腳本，是 C/C++ 軟體編譯的常見第一步。
• php-config：此腳本提供指定 PHP 版本的詳細設定資訊，包括編譯器參數、標頭檔案目錄、函式庫目錄、擴充安裝目錄等。configure 腳本會呼叫 php-config 以取得這些資料，確保模組可正確建構並鏈結至目標 PHP 版本。

因此，使用 phpize、php-config 或其他與 PHP 建構相關的指令時，必須透過完整路徑明確指向目標 PHP 版本。

路徑範例

若你想為 ServBay 安裝的 PHP 8.3 編譯模組：

macOS:

• phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
• php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

• phpize: C:\ServBay\package\php\8.3\current\bin\phpize
• php-config: C:\ServBay\package\php\8.3\current\bin\php-config

選對版本能確保編譯出的模組與目標 PHP 環境完全兼容，避免編譯失敗和執行時出現「找不到符號」等問題。

本文範例以 ServBay 安裝的 PHP 8.3 版本說明。實際操作時，請將命令路徑替換成你要編譯模組的 ServBay PHP 版本實際安裝路徑。

編譯 PHP imagick 模組

imagick 模組是 PHP 中非常知名的擴充，基於強大的 ImageMagick 指令工具，提供多元圖像處理能力。利用 imagick，你能在 PHP 實現縮放、裁剪、格式轉換、加水印、合成等複雜影像操作。以下是於 ServBay 為特定 PHP 版本編譯並安裝 imagick 的完整步驟：

步驟 1：安裝 ImageMagick 依賴

imagick PHP 模組需先安裝系統中的 ImageMagick 函式庫。

macOS

建議使用 Homebrew 套件管理器安裝。如果未安裝 Homebrew，請見 Homebrew 官方網站 取得教學。

打開終端機，輸入下列指令安裝 ImageMagick 和其開發函式庫：

brew install imagemagick

Windows

Windows 使用者需手動下載安裝 ImageMagick，請前往 ImageMagick 官方下載頁 挑選合適版本。

安裝時請務必選擇包含開發函式庫的版本，並將安裝路徑加入系統環境變數。

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

到 PHP 擴充庫（PECL）官方網站下載 imagick 模組原始碼。請見 PECL imagick 頁面 尋找所需版本（通常選最新穩定版），並取得下載連結。下例以新版 3.7.0 為例：

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

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

下載完成後，用 tar 指令解壓，然後 cd 進入模組原始碼目錄：

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

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

進入模組目錄後，使用指定 PHP 版本的 phpize 工具準備編譯環境。請一定要用目標 PHP 版本的完整路徑。如設定了 SERVBAY_PACKAGE_FULL_PATH 環境變數，且目標 PHP 為 8.3：

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

phpize 執行成功後會檢查 config.m4，並生成 configure 腳本及其他需要的建構檔。終端機會顯示相關資訊，確認環境已備妥。

步驟 5：設定編譯選項

執行新生成的 configure 腳本，以指定編譯選項。在此步驟要透過 --with-php-config 參數給定目標 PHP 版本的 php-config 路徑，讓 configure 能取得正確 PHP 設定，如編譯器位置、標頭檔目錄、函式庫目錄等。

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

此步驟會檢查 ImageMagick 的函式庫及標頭檔，並根據 PHP 配置生成 Makefile。如有錯誤多因依賴未安裝或路徑不正確。

步驟 6：編譯並安裝模組

設定成功生成 Makefile 後，用 make 編譯，再用 make install 安裝編譯好的模組至 PHP 擴充目錄。${CPU_NUMBER} 變數（由 ServBay 環境初始化時設）用於加速多核心編譯：

make -j ${CPU_NUMBER}
make install

make install 會根據 php-config 設定，將編譯好的擴充檔案複製至指定 PHP 版本的標準擴充安裝目錄：

• macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
• Windows: C:\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：確認模組載入

啟用模組後，請重啟 ServBay 中 PHP 軟體包以讓設定生效。可於 ServBay 管理主畫面找到對應 PHP 版本軟體包並點選重啟；或者利用 ServBay 命令列工具（相關命令請見官方文件）。

重啟 PHP 後，可於命令列驗證 imagick 模組是否載入：

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

這裡用 $SERVBAY_PACKAGE_FULL_PATH/php/8.3/current/bin/php 指令確保呼叫指定版本 PHP 執行檔。-m 參數會列出全部已載入模組。若成功載入，你將於輸出中看到 imagick 字樣。

更詳細的驗證方式，是於網頁根目錄新建一個 PHP 檔（如 info.php），內容如下： <?php phpinfo(); ?>。網頁根目錄預設位置：

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

再以瀏覽器造訪 http://localhost/info.php 或你設的 ServBay 網站網域。於 phpinfo() 頁面搜尋「imagick」，即可確認啟用狀態、配置信息及版本。

編譯 PHP sqlsrv/pdo_sqlsrv 模組

sqlsrv 及 pdo_sqlsrv 是官方 PHP 擴充，可連接並操作 Microsoft SQL Server 資料庫，依賴 Microsoft 提供的 ODBC 驅動。若需在 ServBay PHP 中連接 SQL Server，須編譯並安裝此模組。以下為於 ServBay 編譯、安裝 sqlsrv/pdo_sqlsrv 的步驟：

注意：重要先決條件

編譯安裝 sqlsrv 前，你必須先安裝 Microsoft 提供的 SQL Server ODBC 驅動與相關工具。這些軟體並非 ServBay 內建，需你手動安裝。

macOS

建議用 Homebrew 套件管理器安裝。若尚未安裝，可見 Homebrew 官方網站。

安裝 Microsoft ODBC 驅動與工具的 Homebrew 指令如下，可能需同意授權條款（設定 HOMEBREW_ACCEPT_EULA=Y）：

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 Mac）或 /usr/local/（Intel Mac）。編譯時請正確引用這些路徑。

Windows

Windows 使用者請至官方網站下載安裝 ODBC Driver for SQL Server：

• 前往 Microsoft ODBC Driver for SQL Server
• 下載並安裝適用版本
• 確認驅動已妥善安裝且可於系統中尋得

請務必於編譯 sqlsrv 前完成相關依賴安裝。

提示

sqlsrv 與 pdo_sqlsrv 為兩個獨立模組，各需分別編譯，但步驟大同小異，下例以 sqlsrv 為例。

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

（如前述，此步驟為必要先決，請確定已透過 Homebrew 裝好 msodbcsql18 與 mssql-tools18。）

步驟 2：下載 sqlsrv 模組原始碼

請至 PECL 官方網站下載 sqlsrv 與 pdo_sqlsrv 模組原始碼。見 PECL sqlsrv 頁面 取得所需版本。下例以新版 5.12.0 為例：

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：解壓原始碼並進入目錄

下載後，解壓進入原始碼目錄：

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# pdo_sqlsrv 同理，下列步驟僅以 sqlsrv 為例

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

於目錄內使用指定 PHP 版本的 phpize 工具。假設 PHP 8.3，且已設定 SERVBAY_PACKAGE_FULL_PATH：

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

步驟 5：設定編譯選項（包含依賴路徑）

執行 configure 腳本，並在執行前以環境變數 LDFLAGS 與 CPPFLAGS 指定 Homebrew 函式庫與標頭檔搜尋路徑，協助 configure 找到所需依賴。同時 --with-php-config 必須給定目標 PHP 版本路徑。

請依 Homebrew 安裝路徑調整下列指令（Intel Mac 常為 /usr/local，Apple Silicon Mac 常為 /opt/homebrew）。範例如下：

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # 確保完整找到標頭檔
./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 指向 Homebrew unixODBC 標頭檔目錄，-I/opt/homebrew/include 完整補足所有標頭檔。${CPPFLAGS} 與 ${LDFLAGS} 保留 ServBay 可能內建的其他參數。

步驟 6：編譯並安裝模組

設定成功並生成 Makefile 後，使用下列指令編譯並安裝：

make -j ${CPU_NUMBER}
make install

make install 會將編譯出來的 sqlsrv.so 與（如有）pdo_sqlsrv.so 複製到 ServBay 目標 PHP 版本的擴充目錄。

步驟 7：啟用模組

安裝完成後，需於 PHP 版本設定檔啟用。ServBay 提供圖形介面：

• 開啟 ServBay 程式
• 左側選單至 語言 - PHP - PHP 8.3
• 於右側選擇 PHP 標籤，下拉至「額外參數」欄，輸入 extension=sqlsrv.so 與 extension=pdo_sqlsrv.so
• 點選儲存，PHP 會自動重啟並載入新模組

步驟 8：確認模組載入

啟用模組後，務必重啟 ServBay PHP 軟體包讓設定生效。

重啟後，狀態確認方式如下：

${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 進行二次編譯 文件，完成 ServBay 編譯環境設置。確定關鍵建構工具（如 autoconf, automake, libtool 等）已安裝且能被系統環境引用。多數時候，執行 ServBay 編譯環境初始化腳本並重啟終端機即可解決。
• Q: configure 腳本執行失敗，顯示找不到某個函式庫或標頭檔？
  • A: 意味模組依賴的某個系統函式庫或標頭沒安裝，或已安裝但找不到。
    • 如 imagick，請確定已安裝 ImageMagick 開發庫，可用 Homebrew：brew install imagemagick。
    • 如 sqlsrv，務必檢查是否已依前述先決用 Homebrew 安裝 Microsoft ODBC 驅動（msodbcsql18）與 mssql-tools18。執行 ./configure 前，確認 LDFLAGS 與 CPPFLAGS 是否設對，包含 Homebrew 依賴的函式庫與標頭檔路徑（如 /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include）。
    • 檢查 ServBay 編譯環境設置是否包含 Homebrew 路徑（如依賴自 Homebrew 安裝），或須手動將 Homebrew 的 bin 路徑加入 ServBay 編譯環境的 PATH。
• Q: make 或 make install 失敗？
  • A: 編譯或安裝失敗可能原因：
    • 缺少編譯依賴: 觀察錯誤訊息告訴你缺了哪個檔案或函式庫，按提示補裝。
    • 配置錯誤: 回到 configure，確認參數正確，特別是 --with-php-config 是否指向正確 ServBay PHP 版本安裝路徑。
    • 權限不足: make install 會將檔案複製到 ServBay 擴充目錄，如權限或路徑設置不當會出錯。嘗試用 sudo make install（請謹慎並了解風險）。
    • 原始檔異常: 設法確認所下載模組原始碼完整無損壞。
• Q: 模組 .so 檔已生成並存放至擴充目錄，也於 .ini 設定啟用，但 php -m 或 phpinfo() 卻無法看見模組？
  • A:
    • 最常見原因： 尚未重啟 ServBay PHP 軟體包。請確認在更動 .ini 後，已透過 ServBay 管理面板或命令列工具完全重啟目標 PHP 版本。僅重刷網頁或重啟 Web 伺服器（如 Caddy/Nginx）不夠，務必重啟 PHP 軟體包本人。
    • .ini 語法錯誤：核查你新增的 .ini ，內容拼寫或格式正確（如 extension=模組名稱.so）。
    • 擴充目錄路徑設定錯誤：確認 php.ini 內 extension_dir 是否正確指向 ServBay PHP 擴充目錄。可用 php-config --extension-dir 查所需路徑。
    • 模組檔案損毀或與 PHP 版本不兼容：重新編譯一次，確保步驟無誤。檢查原始碼版本是否相符你的 PHP 版本。檢查 ServBay 安裝目錄下 logs 文件夾內 PHP 日誌，有無匹配的錯誤訊息。

總結

依據本文逐步教學，你能成功在 ServBay 本地開發環境編譯安裝自訂 PHP 模組如 imagick 與 sqlsrv。全流程關鍵在於：

1. 正確完整初始化 ServBay 編譯環境：所有編譯操作能否正常的根本。
2. 準確指定目標 PHP 版本路徑：不論 phpize 或 php-config，都要用完整路徑對應你要編譯模組的 ServBay PHP 版本。
3. 徹底解決模組外部依賴：依模組需求安裝所需系統函式庫及工具（如 ImageMagick、Microsoft ODBC），並於 ./configure 時用環境變數（如 LDFLAGS、CPPFLAGS）或設定參數指定路徑，確保 configure 能找到全部依賴。
4. 正確啟用模組：於目標 PHP 版本的 conf.d 目錄建立或編輯 .ini 檔，利用 extension=模組名.so 指令載入。
5. 重啟 ServBay PHP 軟體包：讓新模組配置真正生效。

ServBay 作為全方位在地開發環境，提供極高彈性支援各種開發需求。除本文 PHP 模組編譯外，ServBay 還預先整合 MySQL、PostgreSQL、MongoDB、Redis、Caddy、Nginx、Apache、Node.js、Python、Go、Java、.NET、Ruby、Rust 等多元技術。更附有 ACME 申請 SSL 真實證書、直覺 CORS 設定、自動化資料備份（含設定、網站、資料庫、SSL）、重設資料庫 root 密碼，以及 ServBay User CA、ServBay Public CA 支援本地 HTTPS 開發等眾多實用功能，助你打造高效完整的開發流程。

希望本指南能幫助你順利為 ServBay PHP 環境加入所需功能，提升 Web 開發效率。如遇其他問題，建議查閱 ServBay 官方文件或社群支援資源。