ThinkPHP如何做地理位置搜索_RedisGeoHash附近的人【详解】

先说一个容易被忽视的技术细节：GEORADIUS 和 GEORADIUSBYMEMBER 虽然是 Redis GEO 的核心可用命令，但在 ThinkPHP 里直接调用之前，有两件事必须确认。Redis 服务端版本不能低于 3.2，PHP Redis 扩展也得支持 GEO 指令——部分旧版扩展需要手动启用甚至升级，否则命令发过去只会得到一个“不认识”的回应。

ThinkPHP 调用 Redis Geo 命令，关键是要绕过封装层

很多开发者可能已经习惯了 Cache::store('redis')->handler() 或 Redis::connection() 返回原生 Redis 实例的用法。但问题在于，这个 PHP redis 扩展对象的方法列表里，并没有 geoAdd、georadius 这类现成方法——它们是 Redis 协议级别的命令，不是 PHP 扩展的原生方法名。

解决思路很直接：用 rawCommand 显式发送指令。

$redis = Cache::store('redis')->handler();
$redis->rawCommand('GEOADD', 'users:geo', $lng, $lat, $uid);
$redis->rawCommand('GEORADIUS', 'users:geo', $lng, $lat, 5, 'km', 'WITHDIST', 'WITHCOORD', 'COUNT', 20);

需要注意几个关键点：rawCommand 的第一个参数必须是全大写的命令名，后面的参数按 Redis CLI 的传入顺序来写，单位如 km 是字符串，不是数字。如果运行时报错 ERR unknown command 'GEOADD'，罪魁祸首通常不是 ThinkPHP，而是 Redis 服务端版本太低，或者编译时没开启 GEO 支持。如果用 Docker，记得选 redis:7-alpine 及以上的镜像。

经纬度顺序：经度在前，纬度在后，千万别搞反

几乎所有地图 SDK（高德、百度、Leaflet）和数据库（如 MySQL 的 POINT(lng lat)）都统一使用“经度, 纬度”的顺序。但问题常常出在这里：文档里一句“lat,lng”的口语说法，容易让初学者在 GEOADD 里写成 $lat, $lng，结果北京的数据直接漂移到了南美洲。

• 正确写法：GEOADD users:geo 116.404 39.915 "u1001"（116.404 是经度，39.915 是纬度）
• 错误写法：GEOADD users:geo 39.915 116.404 "u1001" —— 实际存的是南纬 39°、东经 116°，目测在阿根廷附近

建议在 ThinkPHP 中封装一层坐标校验逻辑，从源头避免这种问题：

if ($lng < -180 || $lng > 180 || $lat < -85.05112878 || $lat > 85.05112878) {
    throw new InvalidArgumentException('Invalid coordinate range');
}

查出来的结果需要自己“翻译”，不是现成的数组

GEORADIUS 返回的是一个嵌套混合结构。当你启用了 WITHDIST 和 WITHCOORD 时，每一项会变成 [member, distance, [lng, lat]] 这样的形式。PHP redis 扩展拿到的原生数组，不会自动帮你转化成键值对。

常见错误是直接 foreach ($result as $item) 后就用 $item['distance'] 取数，结果报错——因为它是数值索引数组。正确的解析方式如下：

$raw = $redis->rawCommand('GEORADIUS', 'users:geo', $lng, $lat, $radius, 'km', 'WITHDIST', 'WITHCOORD');
$result = [];
foreach ($raw as $i => $item) {
    if ($i % 3 === 0) {
        $member = $item;
        $dist = $raw[$i + 1] ?? null;
        $coord = $raw[$i + 2] ?? null;
        $result[] = [
            'uid' => $member,
            'distance' => (float)$dist,
            'lng' => (float)($coord[0] ?? 0),
            'lat' => (float)($coord[1] ?? 0),
        ];
    }
}

有一点特别容易踩坑：如果命令里没加 WITHDIST 或 WITHCOORD，返回的结构会完全不同。解析时一定要跟你传的选项严格对齐，否则拿到的数据就是混乱的。

GeoHash 字符串别当成业务主键或排序依据

Redis 内部确实用 GeoHash 编码把经纬度转成 52 位整数存进 zset，但这个编码值对业务逻辑来说没有意义。GEOHASH 命令返回的是 base32 字符串（比如 wx4g0b），而它有一个关键特性：字典序不等于地理距离近。

常见误用场景：在数据库里建一个 geohash 字段，然后写个 WHERE geohash LIKE 'wx4g%' 当作精确查询条件——结果边界附近的用户直接被漏掉了。更离谱的是用 ORDER BY geohash 排序，用户看到的“由近到远”完全是错的。因为 GeoHash 是 Z 阶曲线，相邻的两个字符串，在地理上可能隔着几十公里。

正确的做法很简单：只依赖 Redis 的 GEORADIUS 原生命令来做查询。它内部已经完成了 GeoHash 编码、范围扫描和球面距离精筛，返回的结果默认按距离升序排列（除非你显式加了 DESC）。

容易被忽略但必须处理的问题：查询结果包含自己

Redis 的 Geo 功能有一个“盲点”：它不支持在命令层面排除自身。当你用 GEORADIUSBYMEMBER users:geo u1001 5 km 来查询“附近的人”时，结果默认会把 u1001 自己也包含进去。生产环境下，要么手动 array_filter 把当前用户 ID 剔除，要么改用 GEORADIUS 配合显式坐标——后者的可控性更好。