使用phpredis调用hscan返回空结果但redis-cli执行正常如何解决

核心原因 #

1. hscan增量迭代机制差异：Redis的SCAN类命令（包括HSCAN）是增量迭代设计，默认单次仅扫描少量元素（默认hint值为10），如果匹配元素不在当前扫描的分片内，单次调用就会返回空结果。redis-cli执行HSCAN时会自动完成全量迭代并返回所有匹配结果，但phpredis的hscan方法仅执行单次迭代，仅返回当前批次的扫描结果。
2. 连接资源不一致：PHP代码连接的Redis实例、选择的数据库编号和redis-cli操作的不一致，导致无法命中目标key的数据。
3. 扩展版本兼容问题：5.0以下的旧版本phpredis存在HSCAN参数解析异常的已知Bug，会导致匹配规则不生效。

排查解决步骤 #

• 校验连接一致性：先在代码中调用var_dump($redis->hkeys('products:search2'))，确认可以正常拿到对应hash的所有字段，排除key不存在、连接实例/数据库不一致的问题。
• 替换为全量迭代逻辑：循环调用hscan直到迭代器返回0，获取所有匹配结果，可主动指定count参数提高单次扫描的元素数量，减少迭代次数，正确示例代码如下：

<?php
$it = null;
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
// 如有密码、指定数据库需求，在此处添加对应逻辑
// $redis->auth('your_password');
// $redis->select(0);

$matchResults = [];
// 循环迭代直到迭代器重置为0
while ($batchResults = $redis->hscan('products:search2', $it, '*word*', 1000)) {
    $matchResults = array_merge($matchResults, $batchResults);
}

var_dump($matchResults);

• 检查扩展版本：执行php --ri redis查看phpredis版本，若版本低于5.0建议升级到最新稳定版修复兼容问题。
• 校验匹配规则：确认PHP代码中的匹配pattern和redis-cli中使用的完全一致，Redis的MATCH规则区分大小写，若pattern包含?、[]等特殊通配符需按Redis规则转义。

内容的提问来源于stack exchange，提问作者burasuk