PHP 5.4.x 與 Memcache 擴展不兼容問題根因分析與源碼編譯解決方案

問題現場

# 環境：PHP 5.4.8 (編譯 API 20100525)
# 操作：pecl install memcache
# 結果：重啟 php-fpm 報錯
Gracefully shutting down php-fpm . done
Starting php-fpm [25-Oct-2012 12:04:02] NOTICE:
PHP Warning:  PHP Startup: memcache: Unable to initialize module
Module compiled with module API=20090626
PHP    compiled with module API=20100525
These options need to match

根因深度剖析

Zend Module API 版本機制

• PHP 核心編譯時生成 Module API ID (如 20100525)，內嵌於二進制
• 擴展編譯時同樣嵌入當時 PHP 核心的 Module API ID
• 運行時 PHP 核心檢查擴展的 API ID 是否與自身一致，**不一致拒絕載入**

為什麼 PECL 安裝會失敗？

1. pecl install memcache 下載的是**預編譯二進制包** (若可用) 或下載源碼**在當前環境編譯**
2. 若當前系統存在多個 PHP 版本 (如系統自帶 PHP 5.3 + 手動編譯 PHP 5.4)，pecl 命令可能關聯到舊版 PHP 的 php-config/phpize
3. 導致擴展使用舊版 API (20090626) 編譯，與新版 PHP (20100525) 不匹配

解決方案：源碼編譯綁定正確 PHP 版本

步驟 1：卸載失敗的擴展

sudo pecl uninstall memcache
# 並刪除殘留的 memcache.so (通常在 /usr/lib/php5/20090626/ 或 php.ini 指定的 extension_dir)

步驟 2：下載源碼並指定 php-config 路徑編譯

# 1. 獲取源碼 (任選一)
wget https://pecl.php.net/get/memcache-3.0.8.tgz  # 穩定版
tar -zxf memcache-3.0.8.tgz
cd memcache-3.0.8

# 或直接 git clone 最新開發版
# git clone https://github.com/websupport-sk/pecl-memcache.git

# 2. 關鍵：使用目標 PHP 版本的 phpize 和 php-config
/usr/local/php/bin/phpize          # 必須是目標 PHP 的 phpize
./configure --enable-memcache \
  --with-php-config=/usr/local/php/bin/php-config  # 綁定目標 PHP

# 3. 編譯安裝
make
sudo make install
# 輸出提示安裝路徑，如 /usr/local/php/lib/php/extensions/no-debug-non-zts-20100525/memcache.so

步驟 3：配置 php.ini 載入新編譯的擴展

# 確認 extension_dir 指向上述安裝目錄
extension_dir = "/usr/local/php/lib/php/extensions/no-debug-non-zts-20100525"
extension = memcache.so

步驟 4：重啟 PHP-FPM 驗證

sudo systemctl restart php-fpm
php -m | grep memcache
# 輸出 memcache 表示成功

驗證測試腳本

<?php
$mem = new Memcache;
$mem->connect('127.0.0.1', 11211);
$mem->set('feiyan', 'blog');
var_dump($mem->get('feiyan'));  // string(4) "blog"
?>

Memcached 服務端啟動參數 (配套參考)

# 基礎啟動
memcached -d -m 256 -p 11211 -u nobody -l 127.0.0.1

# 生產建議
memcached -d -m 1024 -p 11211 -u memcached -l 10.0.0.50 -c 2048 -P /var/run/memcached.pid
# -m 1024: 1GB 記憶體
# -u memcached: 專用低權限用戶
# -l 10.0.0.50: 僅綁定內網 IP
# -c 2048: 最大並發連線
# -P: PID 檔便於管理

避坑指南：PECL 多 PHP 版本環境最佳實踐

延伸：memcache vs memcached (兩個不同擴展)

建議： 新專案優先使用 memcached 擴展 (libmemcached-based)，功能更完整、效能更優、社區活躍。遷移時注意類名與方法差異 (如 getResultCode()、getAllKeys() 等)。

總結

PHP 版本升級導致 PECL 擴展 API 不匹配是經典問題。核心解法：**源碼編譯 + 顯式指定 --with-php-config 綁定目標 PHP**。建立標準化構建流程，將擴展編譯納入 CI/CD，從源頭杜絕環境不一致導致的生產故障。