PHP APCu 緩存完整指南：安裝配置、核心 API、性能調優與避坑

APCu 簡介

APCu (Alternative PHP Cache - User Cache) 是 APC 移除 opcode 緩存後的用戶數據緩存分支。專注於進程內共享內存鍵值存儲，適合單機、多進程（PHP-FPM worker）場景。不支援分佈式，集群環境請用 Redis/Memcached。

安裝步驟

Linux (PECL)

# PHP 7+
pecl install apcu
# PHP 8+
pecl install apcu-5.1.22  # 指定兼容版本

# 編輯 php.ini
extension=apcu.so
apc.enabled=1
apc.shm_size=128M          # 共享內存大小，根據業務調整
apc.ttl=3600               # 條目默認 TTL（秒），0=永不過期
apc.gc_ttl=3600            # 垃圾回收間隔
apc.entries_hint=10000     # 預估條目數，優化哈希表大小
apc.serializer=php         # 序列化器：php/igbinary/msgpack
apc.enable_cli=1           # CLI 模式啟用（調試用）

Windows

1. 下載對應 PHP 版本、VC 編譯版、TS/NTS 的 php_apcu.dll（官方發布頁）。
2. 放入 ext/ 目錄，php.ini 添加 extension=apcu，配置同 Linux。

驗證安裝

php -m | grep apcu
php -r "var_dump(apcu_cache_info());"

核心 API 速查

封裝類示例（PSR-16 兼容）

<?php
namespace App\Cache;

use Psr\SimpleCache\CacheInterface;

class ApcuCache implements CacheInterface {
    public function get($key, $default = null) {
        $val = apcu_fetch($this->prefixKey($key), $success);
        return $success ? $val : $default;
    }
    public function set($key, $value, $ttl = null): bool {
        return apcu_store($this->prefixKey($key), $value, $ttl ?? 0);
    }
    public function delete($key): bool {
        return apcu_delete($this->prefixKey($key));
    }
    public function clear(): bool {
        return apcu_clear_cache();
    }
    public function has($key): bool {
        return apcu_exists($this->prefixKey($key));
    }
    // ... 實現 getMultiple, setMultiple, deleteMultiple
    private function prefixKey(string $key): string {
        return 'app:' . $key; // 防止鍵衝突
    }
}

性能調優關鍵參數

1. apc.shm_size：監控 apcu_cache_info()['mem_size'] 與 'num_entries'，保持內存使用率 < 80%。
2. apc.ttl：0=永久（需手動清理），>0 自動過期。高頻熱點數據設 0，配合業務邏輯主動更新。
3. apc.entries_hint：預估峰值條目數 * 1.5，減少哈希衝突重哈希開銷。
4. apc.serializer：安裝 igbinary 或 msgpack 擴展，序列化速度提升 2-5 倍、體積縮小 30-50%。
5. apc.preload_path：PHP 啟動時預熱加載目錄下 .php 文件返回的數組，適合配置表、字典數據。

監控與管理

官方提供 apc.php（解壓安裝包或從 GitHub 獲取），配置用戶名密碼後部署，可視化查看：

• 緩存命中率（目標 > 95%）
• 內存碎片率
• 熱門 Key 排行
• 手動清理/刪除條目

常見避坑指南

適用場景總結

• ✅ 單機多進程（PHP-FPM）熱點配置、字典表、Session 存儲（小流量）。
• ✅ 計數器、限流器（apcu_inc/dec 原子操作）。
• ✅ 跨請求臨時數據交換（如驗證碼、CSRF Token）。
• ❌ 集群環境、大對象存儲、持久化需求、跨進程（CLI↔FPM）共享 → 改用 Redis。