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

PHP Memcached 擴展安裝指南：區分 memcache vs memcached、PECL/源碼/靜態編譯三種方式

編輯：PHP 綜合知識

關鍵澄清： PHP 有兩個不同的 Memcached 客戶端擴展，名稱極易混淆：

memcache (舊、輕量、功能少、不支援一致性哈希、不支援 SASL、已停止維護) — pecl install memcache
memcached (新、基於 libmemcached、功能完整、支援一致性哈希/Ketama、SASL、壓縮、Binary Protocol、**強烈推薦**) — pecl install memcached

本文以推薦的 memcached 擴展為主，說明三種安裝方式。

前置依賴：libmemcached

memcached 擴展依賴 C 庫 libmemcached，必須先安裝：


# CentOS/RHEL/AlmaLinux/Rocky
dnf install -y libmemcached-devel cyrus-sasl-devel zlib-devel

# Ubuntu/Debian
apt-get install -y libmemcached-dev libsasl2-dev zlib1g-dev

# macOS (Homebrew)
brew install libmemcached

注意：若需支援壓縮 (igbinary/msgpack/zstd)，需額外安裝對應開發庫並編譯 libmemcached 時啟用。

方式一：PECL 自動安裝 (最簡單、推薦)


# 安裝 memcached 擴展 (非 memcache)
pecl install memcached

# 過程中會詢問：
# "Enable memcached session handler support?" -> yes
# "Enable memcached igbinary serialization support?" -> yes (若已安裝 igbinary)
# "Enable memcached msgpack serialization support?" -> yes (若已安裝 msgpack)
# "Enable memcached json serialization support?" -> yes
# "Enable memcached sasl support?" -> yes (若需 SASL 認證)

# 安裝完成後，PECL 會提示：
# "You should add 'extension=memcached.so' to php.ini"

驗證：php -m | grep memcached 或 php --ri memcached。

方式二：phpize 手動編譯 (指定版本、自定義路徑)


# 1. 下載指定版本源碼 (例如 3.2.0)
wget https://pecl.php.net/get/memcached-3.2.0.tgz
tar -zxvf memcached-3.2.0.tgz
cd memcached-3.2.0

# 2. phpize 生成 configure (需對應 PHP 版本的 phpize)
/usr/local/php/bin/phpize

# 3. 配置 (指定 php-config、libmemcached 路徑)
./configure \
  --with-php-config=/usr/local/php/bin/php-config \
  --with-libmemcached-dir=/usr/local/libmemcached \
  --enable-memcached-session \
  --enable-memcached-igbinary \
  --enable-memcached-msgpack \
  --enable-memcached-json \
  --enable-memcached-sasl

# 4. 編譯安裝
make -j$(nproc) && make install

# 5. 輸出路徑會顯示 memcached.so 位置，加入 php.ini
echo "extension=memcached.so" >> /usr/local/php/etc/php.ini

方式三：PHP 源碼靜態編譯 (極少使用、效能提升微乎其微)

將擴展源碼放入 PHP 源碼樹 ext/ 目錄，重新構建 PHP 核心。


# 1. 進入 PHP 源碼目錄
cd /usr/src/php-8.2.0

# 2. 將擴展源碼放入 ext/memcached
cp -r /path/to/memcached-3.2.0 ext/memcached

# 3. 重新生成配置腳本 (需 autoconf 2.68+)
rm configure
./buildconf --force

# 4. 配置 PHP 核心時啟用 memcached
./configure \
  --prefix=/usr/local/php \
  --with-config-file-path=/usr/local/php/etc \
  --enable-mbstring \
  --with-openssl \
  --with-curl \
  --with-zlib \
  --with-mysqli=mysqlnd \
  --with-pdo-mysql=mysqlnd \
  --enable-fpm \
  --with-memcached=shared  # 或 --enable-memcached=static 靜態編入核心
  # 其他參數...

# 5. 編譯安裝 PHP
make -j$(nproc) && make install

缺點：升級擴展需重編整個 PHP、構建時間長、除錯困難、無法獨立更新。**現代生產環境極不推薦**，除非極端嵌入式場景。

驗證與配置優化

<?php
// 驗證載入
if (!extension_loaded('memcached')) {
    die("memcached 擴展未載入");
}

$m = new Memcached();
$m->addServer('127.0.0.1', 11211);

// 關鍵配置建議
$m->setOption(Memcached::OPT_BINARY_PROTOCOL, true);      // 二進制協議，效能更好
$m->setOption(Memcached::OPT_TCP_NODELAY, true);          // 關閉 Nagle 算法，降低延遲
$m->setOption(Memcached::OPT_CONNECT_TIMEOUT, 1000);      // 連接超時 1秒 (毫秒)
$m->setOption(Memcached::OPT_RETRY_TIMEOUT, 1);           // 重試間隔 1秒
$m->setOption(Memcached::OPT_DISTRIBUTION, Memcached::DISTRIBUTION_CONSISTENT); // 一致性哈希
$m->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true); // 相容 Ketama 算法
$m->setOption(Memcached::OPT_HASH, Memcached::HASH_MURMUR); // 高效哈希
$m->setOption(Memcached::OPT_COMPRESSION, true);          // 啟用壓縮 (大值)
$m->setOption(Memcached::OPT_COMPRESSION_THRESHOLD, 2000); // 超過 2KB 壓縮
$m->setOption(Memcached::OPT_SERIALIZER, Memcached::SERIALIZER_IGBINARY); // 高效序列化 (需安裝 igbinary)

// Session 存儲配置 (php.ini)
/*
session.save_handler = memcached
session.save_path = "127.0.0.1:11211"
; 多台: "10.0.0.1:11211, 10.0.0.2:11211"
memcached.sess_binary_protocol = 1
memcached.sess_consistent_hash = 1
memcached.sess_locking = 1
memcached.sess_lock_wait = 150000
memcached.sess_lock_max_wait = 0
*/
?>

常見問題排查

現象	原因	解決
`Class 'Memcached' not found`	擴展未載入或 php.ini 路徑錯誤	`php --ini` 確認載入的 ini，檢查 `extension=memcached.so`、重啟 php-fpm
`libmemcached not found` 編譯失敗	缺少開發包或路徑錯誤	安裝 `libmemcached-devel`，指定 `--with-libmemcached-dir`
SASL 認證失敗	未編譯 SASL 支援或伺服器未啟用	編譯加 `--enable-memcached-sasl`，確認 libmemcached 編譯支援 SASL
Session 丟失/鎖死	鎖機制配置不當、網絡抖動	調整 `sess_lock_wait`、`sess_lock_max_wait`、啟用一致性哈希
資料無法儲存大值	超過 memcached 預設 1MB 限制	啟動 memcached 伺服器時加 `-I 4m` (或更大)，客戶端啟用壓縮

選型建議： 新專案**直接使用 memcached 擴展 + libmemcached**，配合 igbinary 序列化、一致性哈希、二進制協議。舊專案若在用 memcache，規劃遷移路徑 (API 差異較大，需修改代碼)。安裝方式優先 PECL，其次 phpize，避免靜態編譯。