GEOSEARCH 距离筛选怎么配置或排查

Redis 的 GEOSEARCH 距离筛选，关键是把“查询中心”和“筛选形状”各选一组：中心用 FROMLONLAT 或 FROMMEMBER，范围用 BYRADIUS 或 BYBOX。如果只是查某个经纬度附近的成员，先用下面这条最小写法：

# 先写入两个带经纬度的成员，顺序是 longitude latitude
redis-cli GEOADD locations 116.397 39.908 "store-a" 116.410 39.915 "store-b"

# 以给定经纬度为中心，筛选 5 千米内的成员，并返回距离
redis-cli GEOSEARCH locations FROMLONLAT 116.397 39.908 BYRADIUS 5 KM ASC WITHDIST

排查 GEOSEARCH 时，优先核对键是不是 GEOADD 写入的地理有序集合、经纬度有没有写反、半径单位有没有看错。命令能执行但结果为空，通常先查这三件事。

用 FROMLONLAT 配置半径查询

GEOSEARCH 从 Redis 6.2.0 开始提供。FROMLONLAT longitude latitude 适合调用方已经拿到坐标的场景；如果中心点本身就是索引里的成员，也可以改用 FROMMEMBER member，两者不能同时出现。

BYRADIUS 5 KM 表示圆形范围，半径支持米、千米、英尺和英里。做“附近门店”“附近设备”这类筛选时，建议先固定一种单位，并让输出距离跟它保持一致：

这里最容易写错的是坐标顺序。Redis 地理命令使用经度在前、纬度在后；把两个数字对调后，命令未必报错，却会把中心点移到完全不同的位置。若业务数据来自表单或 JSON，建议在进入 Redis 前统一字段名为 longitude 和 latitude，不要继续使用含义模糊的 x、y。

按距离排序并读取返回字段

距离筛选只负责“在不在范围内”，排序要另外写。ASC 是从近到远，DESC 是从远到近；如果省略二者，返回成员的顺序不能作为业务排序依据。需要在接口里展示距离时加上 WITHDIST，还要返回坐标时再加 WITHCOORD：

# 只取距离最近的 3 个，并同时返回距离和经纬度
redis-cli GEOSEARCH locations FROMLONLAT 116.397 39.908 BYRADIUS 5 KM ASC COUNT 3 WITHDIST WITHCOORD

# 需要更快拿到任意 3 个命中项时可加 ANY，但结果不保证是最近的 3 个
redis-cli GEOSEARCH locations FROMLONLAT 116.397 39.908 BYRADIUS 5 KM ASC COUNT 3 ANY WITHDIST

WITHDIST 的数值单位跟半径使用的单位相同，不能把 KM 查询结果直接当成米。COUNT 3 是上限，不是保证值：范围内只有 1 个成员时只会返回 1 个。ANY 会在找到足够数量后尽快返回，适合只需要若干候选的场景；如果页面明确要求“最近的 3 个”，不要使用它。

结果为空或顺序不对时怎么排查

可以按下面的顺序缩小范围，避免一上来就改半径：

1. 查键和成员：确认 locations 没有拼写错误，并用 ZRANGE locations 0 -1 看成员是否确实写入。键不存在时，查询通常只会得到空结果。
2. 查坐标：对照原始数据确认经度、纬度顺序；中心点若来自 FROMMEMBER，确认成员名称真的存在。
3. 查形状：确认半径后面带了正确单位，且没有把 BYRADIUS 与 BYBOX 的参数混用。矩形筛选要改成 BYBOX width height unit。
4. 查排序和数量：需要最近优先就显式加 ASC；需要稳定读取距离就加 WITHDIST，不要把有序集合 score 当成业务距离。

如果旧代码还在使用 GEORADIUS，迁移时要特别检查参数顺序和返回结构。Redis 文档把它标记为 6.2.0 起弃用，并建议用带 BYRADIUS 的 GEOSEARCH 或 GEOSEARCHSTORE 替代；但本文只讨论读取筛选，不展开存储结果的写入命令。

两个容易混淆的问题

为什么半径写 5 却查不到附近点？先看单位。5 KM 与 5 M 相差很大；再看经纬度是否反写，以及 GEOADD 使用的键是否与 GEOSEARCH 完全一致。

COUNT 以后为什么不是最近的成员？检查是否加了 ANY。它允许 Redis 找到足够数量后提前返回，速度更优先，但不保证返回项按距离最优；最近排序场景使用 ASC COUNT N，不要加 ANY。