GEORADIUS返回空或错误,主因是GEOADD经纬度顺序颠倒、单位缺失、坐标系未转换(如GCJ-02未转WGS84)或坐标越界;其底层依赖GeoHash将经纬度编码为52位整数存于ZSET,通过范围扫描实现高效查询。

直接用 GEORADIUS 就能查出“附近的人”,但结果不准、为空或性能骤降,八成是 GEOHASH 精度没对上,或者根本没意识到 GEORADIUS 底层靠它干活。
为什么 GEORADIUS 返回空或距离明显错误
这不是 Redis 坏了,而是写入和查询时坐标系/顺序/单位三者中至少有一项没对齐:
-
GEOADD必须严格按经度 longitude在前、纬度 latitude在后 —— 写反(比如39.915 116.404)会让北京落到南美洲; - 所有查询命令(
GEORADIUS、GEORADIUSBYMEMBER)必须显式带单位,如km或m,漏写会导致默认按米解析,5 公里写成5就只查了 5 米; - 前端地图 SDK(高德、百度)用的是 GCJ-02 坐标系,而 Redis GEO 默认按 WGS84 计算,不转换就存,距离偏差可达 500 米以上;
-
GEORADIUS不校验坐标合法性,超出-180~180(经度)或-85.05112878~85.05112878(纬度)范围会静默失败,返回空数组。
GEORADIUS 和 GEOHASH 是什么关系
GEORADIUS 本身不直接操作经纬度,它实际是在查 GEOHASH 编码后的有序集合(ZSET)。Redis 把每个位置转成一个 52 位整数 score(本质是 GeoHash 的 base32 解码值),再利用 ZSET 的范围扫描能力快速圈出候选点。
这意味着:
-
GEOHASH长度决定精度:长度 6 → 约 1.2km × 0.6km 单元格;长度 8 → 约 38m × 19m;业务常用 6–8 位,够用且内存友好; - 你不能手动改 ZSET 的 score —— 它由 Redis 自动计算并锁定,强行
ZADD修改会导致GEORADIUS结果错乱; -
GEOHASH命令只用于调试,比如查GEOHASH nearby_users user:1001看编码是否合理,生产环境不用它做业务逻辑; - 没有“设置 GEOHASH 长度”的配置项 —— 精度由输入坐标的浮点精度和 Redis 内部编码固定决定,你只需保证传入的
longitude/latitude有足够小数位(建议 ≥6 位)。
怎么写出稳定可用的 GEORADIUS 查询
一条能进生产环境的 GEORADIUS 命令,得同时满足可读、可测、可分页、可纠错:
- 必加修饰符:
WITHDIST(返距离)、WITHCOORD(返坐标),否则前端拿不到渲染 Marker 所需数据; - 排序必须显式写:
ASC(由近到远)或DESC,不写就是无序,无法保障“最近的 10 人”逻辑; - 限制数量用
COUNT n,放在参数末尾,例如GEORADIUS users 116.404 39.915 5 km WITHDIST WITHCOORD ASC COUNT 20; - 响应是交错数组:
["user:1001", "0.8245", ["116.40421", "39.91503"], "user:1002", ...],解析时不能硬按每 3 个元素一组拆,要根据是否启用WITHCOORD/WITHDIST动态跳位; - 如果用
GEORADIUSBYMEMBER,先确保 member 存在 —— 它查不到时不报错,只返回空数组,业务层得靠strlen($result) === 0或empty($result)判断“用户不存在”还是“附近没人”。
容易被忽略的边界点
最常踩的坑不在命令本身,而在数据生命周期里:
用户下线后位置不该一直留着 —— GEORADIUS 不管数据新旧,过期用户会持续拉低查询效率、污染结果。别依赖 TTL 自动清理,因为 GEO 数据存在 ZSET 里,TTL 对 key 有效,但 ZSET 成员不会自动过期。正确做法是:用户下线时主动 ZREM users:user_id,或用定时任务扫描过期成员(比如 last_active_time 字段 + Sorted Set score 存时间戳做联合索引)。


















