如何让PHP轻松操作Redis缓存？通过Composer引入Predis扩展

装 Predis 其实没什么门槛，直接在项目根目录跑一句 `composer require predis/predis` 就行。注意，Predis 是纯 PHP 的，省掉了编译扩展、改 php.ini 这些麻烦事，装完就能直接用。 ### Class 'PredisClient' not found 怎么办 这个问题基本上不是 Predis 没装对，而是自动加载机制没跑通，或者被别的东西覆盖了。排查起来倒也不复杂： - 先确认一下，`composer dump-autoload` 跑过没有？尤其是如果手动改过 `composer.json` 里的 autoload 字段，这步是必做的。 - 看看项目里有没有自定义的 PSR-4 规则，不小心把 `vendor/` 目录也包含进去了？这样会覆盖 Composer 的默认加载，导致找不到类。 - 在 CI/CD 环境里执行 `composer install --no-dev` 没问题，但本地开发就别加 `--no-dev` 参数了，省得漏掉调试需要的依赖。 - 最基础的：检查 `vendor/autoload.php` 文件是否真实存在，路径拼写有没有错。比如 `require 'vendor/autoload.php';` 和 `require './vendor/autoload.php';` 在某些 CLI 工作目录下，结果可能完全不同。 ### PredisClient 构造函数传参必须注意的键名大小写 配置参数大小写是个坑，得留意一下。Predis 对键名大小写敏感，填错了它也不报错，只会默默回退到默认值。举个例子，`timeout` 写成 `Timeout`，连接超时就变成 0，请求直接卡死。 需要统一用小写的配置项有：`timeout`、`read_write_timeout`、`retry_interval`。标准的字段名包括：`scheme`、`host`、`port`、`password`、`database`。 如果密码里包含 `@` 或 `/` 这种特殊字符，记得先用 `rawurlencode()` 转义一下，再拼进 `host` 或 `password` 字段，否则解析时会被截断。 集群模式下，参数必须传数组，比如 `['tcp://127.0.0.1:7000', 'tcp://127.0.0.1:7001']`，同时还要显式开启 `'replication' => 'predis'` 或 `'cluster' => 'redis'`。 ### $client->get() 返回 null 到底是不是出错了 不少新手碰到 `get()` 返回 `null` 就慌了，觉得是出错了。其实不是，`null` 只是表示 key 不存在，它跟连接失败、认证失败完全是两码事。 - 想验证连通性，得单独用 `$client->ping()`，返回 `+PONG` 才算真正通了。 - 捕获异常时，要用 `Predis\Connection\ConnectionException`，别图省事直接捕 `Exception`。 - 如果业务逻辑里预期某个 key 一定有值，但 `get()` 返回了 `null`，优先去 Redis 侧查查到底有没有写入。可以用 `MONITOR` 命令看看客户端实际发了什么 key。 - 管道（pipeline）模式下的 `get()` 返回的是一个结果数组里对应位置的值，不是单个字符串，别直接 `echo`。 ### 为什么本地连不上 Redis，但 `redis-cli -h 127.0.0.1` 能通 这个问题在 Docker 或 WSL 环境下基本必遇。根本原因不是密码或端口，而是 host 解析错位了。 - PHP 容器里别写 `'host' => 'localhost'`，这个地址指向容器自己，不是宿主机。正确的做法是：Docker Desktop 环境用 `'host' => 'host.docker.internal'`，Linux Docker 环境用宿主机 IP。 - WSL2 的场景更绕：PHP 跑在 Windows 上，Redis 跑在 WSL 里。这时候 `127.0.0.1` 指向的是 Windows 本机，需要用 `$(hostname -I | awk '{print $1}')` 查一下 WSL 的 IP，再填进配置里。 - Redis 配置文件里，如果 `bind` 只写了 `127.0.0.1`，外部网络请求必然被拒。生产环境要配成具体网卡 IP 或 `0.0.0.0`（同时配合 `protected-mode no` 和密码）。 - 超时参数别忘了设，加上 `'timeout' => 2.0, 'read_write_timeout' => 2.0`。默认值是阻塞几秒才失败，调试时你会觉得怎么连都连不上，特别不好排查。 最后一个容易踩的坑：Predis 默认会对值做 `serialize()`。如果你存的是 JSON 字符串，取出来再 `json_decode()` 就多套了一层。解决办法有两个：要么统一用 JSON 编解码，要么初始化 Client 时指定 `'serializer' => Predis\Serializer\None::class` 关掉序列化——不过关了之后就只能存字符串了。