Yii2集成Redis缓存关键在三方面：单节点或集群配置、phpredis扩展匹配、配置项位置正确；任一出错会导致cache->set()静默失败或抛RedisException。
Yii 框架集成 Redis 缓存，关键不在“能不能用”，而在于你用的是单节点还是集群、PHP 扩展是否匹配、配置项是否写错位置——这三个点任一出错，cache->set() 就会静默失败或抛出 RedisException。
确认 phpredis 扩展已启用且版本达标
Yii2 的 yii\redis\Cache 依赖 phpredis（不是 memcache 那种老扩展），且要求 Redis 服务端 ≥2.6.12。很多线上环境装了 redis 扩展但实际是 phpiredis 的旧别名或未启用。
- 运行
php -m | grep redis，输出必须含redis（小写），不含Redis或phpiredis - 检查
phpinfo()页面中 “redis” 模块的 “Version” 字段，应为 5.x 或 6.x（对应 PHP 7.4+/8.x） - 若用 Docker，确保
Dockerfile中执行了docker-php-ext-install redis，而非仅apt install php-redis - 常见错误现象：
Class 'yii\redis\Cache' not found→ 实际是redis扩展没加载，不是类路径问题
单节点 Redis 缓存配置要点
这是最常用场景，但 hostname、port、database 必须写在 redis 子数组里，而不是直接挂在 cache 下；漏掉 keyPrefix 在多应用共用 Redis 时会导致键污染。
-
'class' => 'yii\redis\Cache'必须明确指定，不能省略 -
'redis' => ['hostname' => '127.0.0.1', 'port' => 6379, 'password' => '', 'database' => 0]—— 注意password为空字符串而非null，否则连接可能被拒绝 -
'keyPrefix' => 'myapp_v2_'建议强制设置，避免和后台任务、其他 Yii 应用缓存键冲突 - 不要在
config/web.php里重复定义redis组件：缓存组件内嵌的redis是独立连接实例，不复用全局redis组件
Redis 集群模式下必须避开的配置陷阱
Yii2 不支持原生 Redis Cluster 协议（如 redis-cli --cluster 创建的集群），它靠 yii\redis\Connection 类 + 多节点列表模拟分片，所以配置稍有偏差就会连不上任意节点或无法写入。
-
'redis' => ['class' => 'yii\redis\Connection']—— 这行不能少，且class必须是yii\redis\Connection，不是yii\redis\Cluster（该类不存在） - 删掉
'hostname'和'port'，改用'clusters' => ['192.168.1.10:6379', '192.168.1.11:6379']，格式必须是host:port字符串数组 - 所有节点必须已运行
cluster-enabled yes并完成CLUSTER MEET握手，Yii2 不做集群初始化，只做客户端路由 - 调用
$cache->get('key')时若返回false且无异常，大概率是某个节点网络不通或槽位未分配满（CLUSTER INFO显示cluster_state:fail）
Memcached 与 Redis 切换时的兼容性雷区
虽然都实现 yii\caching\Cache 接口，但底层行为差异极大：Memcached 不支持原子增减、无事务、过期时间精度低；Redis 支持但需注意扩展绑定。
- 别混用扩展：
yii\caching\MemCache必须配memcached扩展（不是memcache），否则set($key, $value, 3600)会静默丢弃过期时间 -
yii\redis\Cache不支持add()方法（非原子），要用set()+get()手动判断，否则并发下可能覆盖 - 批量操作如
multiSet()在 Redis 下走 pipeline，在 Memcached 下是逐条请求，性能差距明显，压测前务必验证 - 缓存键长度限制不同：Redis 默认 512MB（实际受内存限制），Memcached 硬性限制 250 字节，超长键会截断或报错
最易被忽略的是 keyPrefix 和扩展加载状态——它们不出现在任何错误堆栈里，但会让缓存读写全部失效，且现象是“有时生效有时不”，排查时建议先用 redis-cli -p 6379 keys "myapp_v2_*" 直接查键是否存在。
