PHP APCu 擴充套件安裝與配置指南 (Windows/Linux)

什麼是 APCu？

APCu (Alternative PHP Cache - User Cache) 是 APC 專案中移除 opcode 快取功能後，專注於**使用者資料快取**的擴充套件。自 PHP 5.5 起，PHP 核心內建了 Zend OPcache 處理 opcode 快取，因此 APCu 成為補充鍵值快取的標準選擇。適用於快取資料庫查詢結果、API 回應、運算結果等，顯著降低響應延遲。

Windows 環境安裝步驟

1. 確認 PHP 版本資訊：執行 php -v 或 phpinfo()，記下：
   • PHP 版本 (如 8.2.10)
   • Thread Safety (TS / NTS)
   • 編譯器 (VC15 / VS16 等)
   • 架構 (x86 / x64)
2. 下載對應 DLL：前往 PECL APCu 頁面，選擇版本 (建議最新穩定版)，下載 php_apcu-<版本>--ts/nts-vc<編譯器>-x86/x64.zip。
3. 部署檔案：
   • 將 php_apcu.dll 複製到 PHP ext/ 目錄。
4. 修改 php.ini：

   extension=apcu
   apc.enabled=1
   apc.shm_size=128M          ; 共享記憶體大小，依伺服器 RAM 調整
   apc.ttl=3600               ; 預設存活秒數 (0=永不超時)
   apc.gc_ttl=3600            ; 垃圾回收存活秒數
   apc.entries_hint=4096      ; 預估條目數，優化哈希表大小
   apc.enable_cli=1           ; CLI 模式啟用 (測試/排程任務需求)
   

5. 重啟 Web 伺服器 (Apache/Nginx/PHP-FPM) 並驗證：
   php -m | findstr apcu 或瀏覽 phpinfo() 搜尋 apcu 區塊。

Linux (Ubuntu/Debian/CentOS) 安裝

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install php-apcu        # 系統套件版本 (可能較舊)
# 或使用 PECL 安裝最新版
sudo pecl install apcu
echo "extension=apcu.so" | sudo tee /etc/php/8.2/mods-available/apcu.ini
sudo phpenmod apcu
sudo systemctl restart php8.2-fpm

# CentOS/RHEL (Remi repo)
sudo yum install php-pecl-apcu
# 或
sudo pecl install apcu

核心 API 快速上手

<?php
// 寫入快取 (key, value, ttl秒)
apcu_store('user:1001', ['name' => 'John', 'role' => 'admin'], 3600);

// 讀取快取
$user = apcu_fetch('user:1001');
if ($user === false) {
    // 快取未命中，查詢資料庫...
    $user = $db->query("SELECT * FROM users WHERE id=1001");
    apcu_store('user:1001', $user, 3600);
}

// 刪除快取
apcu_delete('user:1001');

// 批次操作
apcu_store(['config:site_name' => 'MySite', 'config:theme' => 'dark'], 86400);
$config = apcu_fetch(['config:site_name', 'config:theme']);

// 遞增/遞減計數器 (原子操作)
$visits = apcu_inc('page:home:visits'); // 回傳新值
$stock = apcu_dec('product:999:stock'); // 扣減庫存

// 取得快取資訊
$info = apcu_cache_info(); // 含命中率、記憶體使用、條目數等
print_r($info);
?>

效能調優建議

常見問題與排除

• 無法啟動：Unable to load dynamic library 'apcu' → 確認 DLL/so 檔案架構、TS/NTS、PHP 版本完全一致；Windows 需將 php_apcu.dll 放入 ext/，Linux 需確認 extension=apcu.so 路徑正確。
• 快取命中率低 → 檢查 apcu_cache_info() 的 num_hits / num_misses，調整 TTL、增加 shm_size、檢查是否有大量短命鍵值污染快取。
• CLI 與 Web 快取不共享 → APCu 以 SAPI 為隔離單位，CLI 與 FPM/Apache 各自擁有獨立共享記憶體段，無法直接共享。跨進程共享請改用 Redis/Memcached。
• PHP 8.1+ 解構子中存取 APCu 導致 Segfault → 已知 Bug，避免在 __destruct / __wakeup 中呼叫 APCu 函式，或升級至 APCu 5.1.22+。

APCu vs Redis vs Memcached 選型指南

結語

APCu 是單機 PHP 應用極速快取的利器，安裝簡單、零網路延遲、API 極簡。合理配置 shm_size、ttl、serializer 並監控命中率，即可榨乾記憶體效能。若架構演進為多伺服器叢集，平滑遷移至 Redis 是自然選擇。