Hyperf单机Redis连接失败主因是服务端与客户端配置未对齐：一、服务端需修改bind和protected-mode并重启；二、客户端redis.php中host、auth、超时等参数须匹配；三、用RedisFactory主动获取实例可暴露池名错误。
Hyperf 单机 Redis 连接失败，多数不是代码写错了，而是部署时 Redis 服务端配置和 Hyperf 客户端配置没对齐。重点在两头：服务端是否真在监听外部请求，客户端是否连到了对的地址+池名+超时参数。下面分三块实操修正。
一、确认 Redis 服务端已允许本地外联
Windows 或 Linux 本地开发环境，默认 Redis 只绑定了 127.0.0.1，Hyperf 若运行在 Docker 容器、WSL2、或另一端口进程里，就会连接被拒（报错常为 Connection refused 或 timeout）。
Redis Skill - 高性能缓存管理
下载
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
- 找到 Redis 配置文件：
redis.conf（Linux）或redis.windows.conf（Windows），路径通常在安装目录根下 - 编辑该文件，定位
bind行，取消注释并改为：bind 127.0.0.1 192.168.x.x（填你本机局域网 IP）
或更简单但仅限测试用：bind 0.0.0.0 - 检查
protected-mode：若未设密码且 bind 不含非回环地址，它会拦截外部连接；可临时设为protected-mode no（上线前务必改回并配requirepass） - 重启 Redis：
redis-server redis.conf（Linux/macOS）或redis-server --service-restart（Windows 服务模式） - 验证：终端执行
redis-cli -h 192.168.x.x -p 6379 ping，返回PONG即通
二、检查 Hyperf 的 redis.php 配置是否匹配
Hyperf 的 Redis 配置文件是 config/autoload/redis.php，常见错误是 host 写成 localhost 或 127.0.0.1，但在容器或 WSL2 场景下，这实际指向容器/子系统自身，而非宿主机 Redis。
- 若 Redis 跑在 Windows 宿主机，Hyperf 在 WSL2 或 Docker 中：host 改为宿主机真实局域网 IP（如
192.168.1.100），不要用host.docker.internal（仅 Docker for Desktop 支持，WSL2 不认） - 确保
database、port、auth（如有密码）与 Redis 服务端一致；密码需严格匹配，空字符串''和null行为不同 - 关键参数别忽略：
'timeout' => 5.0（建连超时）
'read_timeout' => 5.0（读响应超时）
'retry_interval' => 100（重试间隔毫秒） - 若用了多个 Redis 实例（如 cache / queue / notify），每个池的
poolName必须小写、无空格、与配置键名完全一致（'notify'≠'Notify'）
三、用 RedisFactory 主动取实例，快速定位池名问题
继承 Hyperf\Redis\Redis 类容易因 DI 绑定失效而静默拿到 default 池，尤其当有多个池时。改用工厂方式，能立刻暴露配置缺失。
- 在任意类中注入：
#[Inject] protected RedisFactory $redisFactory; - 按需获取指定池：
$redis = $this->redisFactory->get('cache');$redis = $this->redisFactory->get('queue'); - 如果池名不存在，
get()会直接抛InvalidArgumentException，而不是降级使用 default —— 这比静默出错更容易排查 - 配合日志输出验证：
var_dump($redis->ping()); // 应返回 string(4) "PONG"
