LaravelEloquent空间查询入门教程

本文深入解析了在 Laravel Eloquent 中实现精准地理空间查询的完整方案：由于 Eloquent 原生不支持 GIS 功能，必须借助 MySQL 的 POINT 字段（SRID 4326）、ST_PointFromText 插入、ST_Distance_Sphere 球面距离计算及 SPATIAL 索引优化，并通过 whereRaw 或原生 SQL 驱动真实地理运算——避开将经纬度存为字符串或双字段等常见陷阱，确保距离结果准确到米级，让开发者真正掌握高性能、高精度的地理位置搜索能力。

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', 'orderBy('distance')
      ->get();

• 必须显式传入 $lng 和 $lat，顺序不能反（POINT(long lat)）
• 如果表里 position 没设 SRID（比如建表时漏了 SRID 4326），ST_Distance_Sphere 返回 NULL，但不会报错 —— 这是最常被忽略的静默失败点

Eloquent 模型要禁用自动类型转换，否则 POINT 字段会被转成字符串

Laravel 默认对所有字段做 cast 处理，遇到 POINT 这类二进制 GIS 类型，会调用 __toString() 导致数据损坏。必须在模型中明确排除：

• 在模型里加：

  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 就等于没跑。

今天关于《LaravelEloquent空间查询入门教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！