您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

macOS 上從源碼編譯安裝 Swoole 擴展完整實錄（含 PCRE 依賴解決）

編輯：PHP 綜合知識

前言

Swoole 是 PHP 界最強大的高性能網絡通訊引擎，支援協程、異步 IO、多進程等特性。雖然現在推薦使用 pecl install swoole 或 Docker 部署，但理解從源碼編譯安裝的完整流程，有助於解決版本匹配、依賴缺失、自定義編譯選項等疑難雜症。本文記錄在 macOS (OS X) 環境下，手動編譯安裝 Swoole 的全過程，重點講解常見的 pcre.h 缺失問題及其解決方案。

環境準備

作業系統：macOS (文中為 Mavericks 10.9，但步驟適用於更新版本)
PHP 版本：5.4.30 (CLI)，安裝路徑 /usr
工具鏈：Xcode Command Line Tools (含 clang、make、autoconf)
源碼獲取：git clone https://github.com/swoole/swoole-src.git

編譯安裝步驟

1. phpize 生成配置腳本

cd swoole-src
phpize

輸出顯示 PHP API 版本、Zend Module API 版本等資訊，確認與目標 PHP 版本一致。

2. ./configure 配置編譯選項

./configure

此步驟會檢測系統庫、PHP 頭文件、依賴庫等。文中輸出顯示多項特性檢測（sockets、openssl、curl、kqueue 等），最終生成 Makefile。

3. 編譯報錯：致命錯誤 'pcre.h' file not found

make
# ...
fatal error: 'pcre.h' file not found
#include "pcre.h"
^
1 error generated.
make: *** [swoole.lo] Error 1

原因分析：雖然 PHP 已內建 PCRE 擴展（php -m 可見 pcre），但編譯 Swoole 需要的是 PCRE 開發包（頭文件 pcre.h、靜態庫 libpcre.a），而非 PHP 的 PCRE 模組。macOS 系統預設不包含開發頭文件。

4. 解決 PCRE 依賴：兩種方式

方式一：Homebrew 安裝（推薦，簡單快捷）

brew install pcre

安裝完成後，頭文件通常位於 /usr/local/include/pcre.h 或 /usr/local/Cellar/pcre/版本/include/pcre.h。

方式二：源碼編譯 PCRE（若需特定版本或無 Homebrew）

注意：官網 svn://vcs.exim.org/pcre/code/trunk 下載的是開發版，缺少 configure 腳本，不適合直接編譯。正確做法是從 SourceForge 下載發布版：

cd /usr/local/src
wget https://sourceforge.net/projects/pcre/files/pcre/8.36/pcre-8.36.tar.gz
tar zxvf pcre-8.36.tar.gz
cd pcre-8.36
./configure --prefix=/usr/local/pcre-8.36
make && sudo make install

然後在編譯 Swoole 時指定 PCRE 路徑：

./configure --with-pcre-dir=/usr/local/pcre-8.36

5. 重新編譯 Swoole

安裝好 PCRE 開發包後，直接重新執行 make。文中編譯過程產生 6 個警告（主要是 macOS 棄用 daemon() 函數、格式字符串類型不匹配等），不影響功能，最終生成 modules/swoole.so。

6. 安裝擴展

# 普通用戶無權限寫入系統擴展目錄
make install
# cp: Permission denied

# 使用 sudo
sudo make install

輸出顯示安裝至 /usr/lib/php/extensions/no-debug-non-zts-20100525/。

7. 啟用擴展

# 查找 php.ini 位置
php --ini
# Configuration File (php.ini) Path: /etc
# Loaded Configuration File: /etc/php.ini

# 編輯 php.ini，添加
extension = swoole.so

8. 驗證安裝

php -m | grep swoole
# 輸出 swoole 表示成功

常見坑點總結

問題	原因	解決
`pcre.h not found`	缺少 PCRE 開發頭文件	`brew install pcre` 或源碼安裝指定 `--with-pcre-dir`
`phpize not found`	未安裝 php-dev / php-devel 包	macOS 通常自帶；Linux 需 `apt install php-dev` / `yum install php-devel`
`configure: error: Cannot find php-config`	PATH 中無 php-config	確保 PHP bin 目錄在 PATH 中，或用絕對路徑 `/usr/bin/phpize`
編譯警告 `daemon deprecated`	macOS 10.5+ 棄用 daemon()	屬正常警告，Swoole 內部有兼容處理，可忽略
安裝權限不足	系統擴展目錄需 root 權限	`sudo make install`

現代替代方案（推薦）

PECL：pecl install swoole 自動處理依賴、下載、編譯、安裝。
Docker：使用官方 phpswoole/swoole 鏡像，環境完全一致，零配置。
Static PHP CLI：預編譯含 Swoole 的單文件 PHP 二進制，適合分發部署。

結語

通過完整走一遍源碼編譯流程，不僅解決了 PCRE 依賴問題，也對 PHP 擴展的構建機制（phpize → configure → make → make install）有了具體認識。遇到類似 xxx.h not found 的編譯錯誤時，核心思路始終是：安裝對應庫的開發包（-dev/-devel），必要時指定 --with-xxx-dir。