如何用Dart和Flutter查询Cloud Firestore指定距离内的地理点？

核心疑问解答 #

• Firestore没有直接的内置地理距离查询API，这也是官方推荐地理哈希方案的原因。
• GeoPoint的意义：它是Firestore专为地理坐标设计的标准化存储类型，确保经纬度数据的类型统一、格式规范，同时支持原生的经纬度范围查询（这是普通数字字段无法提供的类型校验和原生支持），也能为后续的地理计算提供可靠的数据基础。

未添加地理哈希时的查询方案 #

如果没有提前存储地理哈希，可以通过「边界框预筛选 + 客户端精确计算距离」的方式实现范围查询，步骤如下：

1. 计算目标位置的边界经纬度 #

先算出一个能覆盖目标范围的矩形边界，用Firestore的范围查询过滤掉大部分无关数据，减少后续计算量。

2. Firestore查询边界内的点 #

通过where条件筛选出落在边界框内的所有GeoPoint数据。

3. 客户端计算实际距离并筛选 #

对查询结果逐个计算与目标位置的球面距离，最终保留距离≤指定范围的点。

完整Dart代码示例 #

import 'package:cloud_firestore/cloud_firestore.dart';
import 'dart:math';

// 地球半径（单位：米）
const double earthRadius = 6371000;

/// 计算目标位置周围指定距离的经纬度边界框
Map<String, double> calculateBoundingBox(double targetLat, double targetLng, double maxDistanceMeters) {
  // 纬度每度约等于111133米，直接计算纬度范围
  double latDelta = maxDistanceMeters / 111133;
  final minLat = targetLat - latDelta;
  final maxLat = targetLat + latDelta;

  // 经度每度的距离随纬度变化，用球面公式计算经度范围
  double lngDelta = (maxDistanceMeters / (earthRadius * cos(targetLat * pi / 180))) * (180 / pi);
  final minLng = targetLng - lngDelta;
  final maxLng = targetLng + lngDelta;

  return {
    'minLat': minLat,
    'maxLat': maxLat,
    'minLng': minLng,
    'maxLng': maxLng,
  };
}

/// 计算两点间的球面距离（Haversine公式，单位：米）
double calculateDistance(double lat1, double lng1, double lat2, double lng2) {
  final dLat = (lat2 - lat1) * pi / 180;
  final dLng = (lng2 - lng1) * pi / 180;

  final a = sin(dLat / 2) * sin(dLat / 2) +
      cos(lat1 * pi / 180) * cos(lat2 * pi / 180) *
      sin(dLng / 2) * sin(dLng / 2);
  final c = 2 * atan2(sqrt(a), sqrt(1 - a));

  return earthRadius * c;
}

/// 获取指定位置周围的所有地点
Future<List<DocumentSnapshot>> getNearbyLocations(double targetLat, double targetLng, double maxDistanceMeters) async {
  // 1. 计算边界框
  final bounds = calculateBoundingBox(targetLat, targetLng, maxDistanceMeters);

  // 2. 查询边界内的所有地点
  final querySnapshot = await FirebaseFirestore.instance
      .collection('locations')
      .where('coords.latitude', isGreaterThanOrEqualTo: bounds['minLat'])
      .where('coords.latitude', isLessThanOrEqualTo: bounds['maxLat'])
      .where('coords.longitude', isGreaterThanOrEqualTo: bounds['minLng'])
      .where('coords.longitude', isLessThanOrEqualTo: bounds['maxLng'])
      .get();

  // 3. 筛选出距离符合要求的点
  final nearbyLocations = <DocumentSnapshot>[];
  for (final doc in querySnapshot.docs) {
    final coords = doc['coords'] as GeoPoint;
    final distance = calculateDistance(targetLat, targetLng, coords.latitude, coords.longitude);
    if (distance <= maxDistanceMeters) {
      nearbyLocations.add(doc);
    }
  }

  return nearbyLocations;
}

方案局限性说明 #

• 极地附近的边界框计算会存在误差，若业务涉及高纬度地区，需要额外调整计算逻辑。
• 当集合数据量极大时，客户端筛选会带来性能损耗，这种情况下建议后续为数据补充地理哈希（可使用第三方geohash库生成哈希值），结合哈希前缀查询进一步优化性能。

内容的提问来源于stack exchange，提问作者Joshua Singla