PHP 的 Eloquent 不支持空间查询，需用 MySQL GIS 函数配合 POINT 字段、SRID 4326、ST_PointFromText 插入及 ST_Distance_Sphere 计算球面距离，并添加 SPATIAL 索引。
PHP 本身不支持空间查询，Eloquent 的 whereRaw 或原生 SQL 才是实际执行地理计算的载体；Laravel 官方 Eloquent 不内置空间类型支持，必须依赖 MySQL/MariaDB 的 GIS 函数 + 正确字段类型 + 手动绑定参数。
MySQL 表必须用 POINT 字段类型，不能用 JSON 或 TEXT
PostGIS 是 PostgreSQL 的扩展，MySQL 的空间能力靠 GEOMETRY 类型和 ST_* 函数支撑。若把经纬度存成两个 DECIMAL 字段或拼成字符串，ST_Distance_Sphere 会直接报错或返回 NULL。
- 建表时用
POINT：ALTER TABLE locations ADD COLUMN position POINT SRID 4326;
- 插入数据必须用
ST_PointFromText：INSERT INTO locations (position) VALUES (ST_PointFromText('POINT(116.48 39.92)', 4326)); - 给
position加空间索引（否则查询极慢）：ALTER TABLE locations ADD SPATIAL INDEX idx_position (position);
ST_Distance_Sphere 是唯一靠谱的球面距离函数，别用 ST_Distance
ST_Distance 在 MySQL 中默认按平面欧氏距离算，北京到上海会得出几百公里的错误结果；ST_Distance_Sphere 才基于 WGS84 椭球模型，单位是米，且要求两点都带 SRID 4326。
- 查 5km 内的门店（Laravel 查询构造器写法）：
Location::selectRaw('*, ST_Distance_Sphere(position, POINT(?, ?)) AS distance', [$lng, $lat]) ->having('distance', '<', 5000) ->orderBy('distance') ->get(); - 必须显式传入
$lng和$lat，顺序不能反（POINT(long lat)） - 如果表里
position没设 SRID（比如建表时漏了SRID 4326），ST_Distance_Sphere返回NULL，但不会报错 —— 这是最常被忽略的静默失败点
Eloquent 模型要禁用自动类型转换，否则 POINT 字段会被转成字符串
Laravel 默认对所有字段做 cast 处理，遇到 POINT 这类二进制 GIS 类型，会调用 __toString() 导致数据损坏。必须在模型中明确排除：
立即学习“PHP免费学习笔记（深入）”；
- 在模型里加：
protected $casts = [ 'position' => 'string', // 强制当字符串处理，避免自动序列化 ]; - 或者更安全的做法：完全禁用该字段的 cast：
protected $casts = [];
并在访问时手动用DB::raw('ST_AsText(position)')提取坐标 - 读取经纬度时别用
$model->position直接取值 —— 它是二进制 blob，要用：DB::selectOne("SELECT ST_X(position) AS lng, ST_Y(position) AS lat FROM locations WHERE id = ?", [$id]);
真正麻烦的不是写那几行 SQL，而是字段类型、SRID 声明、索引、函数选型这四个点只要漏一个，查询就静默失效或性能崩盘。尤其 SRID 4326 必须从建表、插入、查询全程一致，中间任何环节没带上，ST_Distance_Sphere 就等于没跑。
