PHP Redis 报错主因有三：扩展未启用或版本不匹配（如 PHP 8.1+ 需 redis ≥ 5.3.7）；网络不通（如 Docker 中误用 localhost）；代码调用不当（如 connect 超时、缺 auth、忽略返回值）。
PHP 扩展未启用或版本不匹配
报错常见于 Class 'Redis' not found 或 Call to undefined function redis_connect()，本质是 PHP 没加载 Redis 扩展，或加载了但版本太老（如 PHP 8.1+ 要求 redis 扩展 ≥ 5.3.7）。
检查方式：php -m | grep redis 看是否在列表中；再运行 php -r "echo Redis::VERSION . \"\n\";" 查版本。若报错或无输出，说明扩展未启用或不兼容。
实操建议：
- 确认
extension=redis.so（Linux/macOS）或extension=php_redis.dll（Windows）已写入正确的php.ini（用php --ini定位路径） - 扩展需与 PHP 版本 ABI 匹配：PHP 8.2 必须用 redis 5.3.x 或 6.0.x，不能混用 PHP 7.x 编译的 so 文件
- 部分 Docker 镜像（如
php:8.2-cli）默认不含 redis 扩展，需手动docker-php-ext-install redis并重启容器 - 确认 Redis 服务确实在运行：
redis-cli ping返回PONG；若失败，先查systemctl status redis或ps aux | grep redis - Docker 场景下，PHP 容器不能用
localhost访问宿主机 Redis（除非 host 网络模式），应改用宿主机 IP（如172.17.0.1）或 Docker Compose 中的服务名（如redis） - 云 Redis（如阿里云、腾讯云）需检查安全组是否放行 6379 端口，且白名单包含 PHP 服务器公网/内网 IP
- 本地开发用 WSL2 时，
localhost指向 WSL2 自身，不是 Windows 上的 Redis，得用host.docker.internal或 Windows 主机真实 IP -
connect()默认超时仅 1 秒，高延迟网络（如跨可用区）易失败，务必显式传参：$redis->connect('127.0.0.1', 6379, 5)（单位秒） - 密码认证必须调用
auth()，且要在connect()成功后、任何命令前执行；若 Redis 配置了requirepass但没auth()，后续所有操作都会返回false或抛异常 - 不要忽略返回值：
if (!$redis->connect(...)) { throw new Exception('Redis connect failed'); }，否则静默失败难以定位 - PHP-FPM 场景下，长连接复用可能因 Redis 服务重启而残留失效连接，建议每次请求新建实例，或用
pconnect()+ 异常捕获重连逻辑 -
redis扩展默认不启用集群功能，需重新编译并加--enable-redis-cluster参数（源码安装） - PECL 安装时需指定：
pecl install redis后会提示是否启用 cluster，选 yes；若已装过，得pecl uninstall redis && pecl install redis重装 - 验证方式：
php -r "new RedisCluster([]);"不报错即成功；或查看phpinfo()页面中 Redis 模块是否含Redis Cluster support => enabled - 注意：RedisCluster 构造函数参数是节点数组，格式为
['127.0.0.1:7000', '127.0.0.1:7001']，不是单个 host:port 字符串
连接时抛出 Connection refused 或超时
这和扩展无关，是网络层问题：PHP 进程根本连不上 Redis 服务。典型错误信息包括 Connection refused (111)、Failed to connect to Redis server、read error on connection。
排查重点不在代码，而在运行环境：
实例化 Redis 类后调用失败
扩展已启用、网络也通，但 $redis = new Redis(); $redis->connect(...) 报错，大概率是参数或异常处理缺失。
关键点：
扩展启用但 RedisCluster 不可用
想用集群模式却提示 Class 'RedisCluster' not found，不是配置问题，而是扩展编译时未开启集群支持。
原因和对策：
立即学习“PHP免费学习笔记（深入）”；
Redis 的集成问题，往往卡在“以为是代码错了”而反复改逻辑，其实八成出在扩展状态、网络可达性、或构造参数的细节上。尤其在容器、云环境、多版本共存场景下，php --ri redis 和 telnet host port 这两个命令比看错误堆栈更管用。
