根本原因是Redis扩展未启用或长连接配置不当：需确认phpinfo中Redis Support已启用、TP配置开启persistent=true并设prefix防污染，Swoole等常驻框架须改用连接池，且必须手动ping检测连接存活。
绝大多数 ThinkPHP 项目 Redis 连接失败，根本不是代码写错了，而是 PHP 扩展没装、配置没生效、或长连接用错了地方。
Redis 扩展没启用，Class 'Redis' 直接报错
这是最底层的拦路虎。ThinkPHP 的 cache 驱动依赖 phpredis 扩展，不是 Predis；Predis 是纯 PHP 实现，但 TP 默认不走它，除非你手动指定驱动。
- 运行
php -m | grep redis，输出里必须有redis（不是redis.so文件名，是模块名） - 如果没看到，说明扩展没加载：检查
php.ini是否写了extension=redis.so（Linux）或extension=php_redis.dll（Windows），且路径正确 -
phpinfo()页面里搜 “redis”，确认 “Redis Support” 显示 enabled，且版本不低于 5.3.0（TP6 要求） - 重启 PHP-FPM 或 Apache/Nginx，否则改了配置也白搭
pconnect() 在 PHP-FPM 下生效，但在 Swoole 中会泄漏
ThinkPHP 默认用 connect()，每次请求新建连接；设 'persistent' => true 才会触发 pconnect()。但这事得分场景看：
- 在传统 PHP-FPM 模式下：
'persistent' => true确实能复用连接，减少握手开销，但必须配'prefix' => 'tp_'，否则多个请求共用一个连接 ID，SELECT 1切库可能互相污染 - 在 Swoole/ Hyperf 等常驻进程框架下：
persistent反而危险——连接不会随请求结束释放，越积越多，最终耗尽 Redis 客户端连接数（maxclients） - 此时该用连接池，比如
topthink/think-redisv3+ 的pool配置，或直接集成co\Redis协程客户端
连接参数对不上，Connection refused 或超时卡死
错误信息里带 Connection refused，90% 是服务端没监听你连的那个地址+端口；卡住几秒才报错，大概率是防火墙或 timeout 参数没设。
Redis Skill - 高性能缓存管理
下载
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
立即学习“PHP免费学习笔记（深入）”；
- 先本地验证：
redis-cli -h 127.0.0.1 -p 6379 ping必须返回PONG；若失败，检查redis.conf的bind和protected-mode - 远程连接务必用内网 IP（如
192.168.10.5），别用0.0.0.0或公网 IP，再配合安全组只放行内网段 - 在 TP 配置里显式加
'timeout' => 2和'read_timeout' => 2，避免网络抖动拖垮整个 HTTP 请求 - 密码不为空时，
'password'字段必须填对，且注意 Redis 6+ 的 ACL 用户需额外配权限（如+get +set）
没做存活检测，旧连接还在用却已断开
Redis 服务端默认空闲 60 秒断连（tcp-keepalive 60），而 PHP-FPM 进程里的持久连接不知道这事，下次还拿它发命令，结果就是 read error on connection 或直接崩溃。
- 不能只靠
pconnect()，得主动探测：$redis->ping() === '+PONG'才执行后续操作 - 在业务逻辑里封装一层：
Cache::store('redis')->get()前先调用handler()->ping()，失败就重建实例 - TP6.1+ 支持
onConnect回调，可在连接建立后自动ping一次，但断连后的二次检测仍需自己补 - 更彻底的方案：把
ping逻辑下沉到中间件或 BaseRepository，避免每个缓存调用都重复判断
真正难的不是“怎么连上”，而是“连上之后怎么确保一直可用”——连接池、前缀隔离、存活检测、超时控制，这四件事漏掉任何一环，线上都可能突然崩一次缓存。尤其是 Swoole 项目，把 FPM 那套 persistent 配置直接搬过去，基本等于埋雷。
