MongoDB地理空间查询必须使用2dsphere索引和GeoJSON Point格式（coordinates为[longitude, latitude]），$geoNear须为首阶段、设spherical:True、maxDistance单位为米，并配合$limit与业务$filter提升性能。
MongoDB 必须建 2dsphere 索引，不是 2d
直接用 create_index("location", "2d") 会失败或返回错误距离——MongoDB 的地理空间查询要求坐标是 GeoJSON 格式（{"type": "Point", "coordinates": [lng, lat]}），且索引类型必须是 "2dsphere"。常见错误是把经纬度存成普通数组字段、或建错索引类型，导致 $near 报 "geoNear requires geoHaystack or 2dsphere index"。
正确做法：
- 确保商家文档的地理位置字段（比如
"location"）是标准 GeoJSONPoint，且coordinates顺序为[longitude, latitude]（注意：不是 lat/lng） - 建索引命令必须是：
collection.create_index("location", "2dsphere") - 如果已有旧数据是
[lat, lng]顺序，得批量修正，不能靠应用层反转——MongoDB 计算时严格按 [x,y] = [lng,lat] 解析
聚合管道里用 $geoNear 必须是第一阶段，且不能和 $sort 混用
$geoNear 是个特殊阶段：它既是查询又是排序，自带距离计算（输出 distance 字段），还强制要求必须放在 pipeline 最开头。很多人写成先 $match 再 $geoNear，结果报错 "$geoNear must be the first stage"；或者加了 $sort: { distance: 1 } 导致性能骤降甚至超时——其实完全没必要。
典型安全写法：
立即学习“Python免费学习笔记（深入）”；
[
{
"$geoNear": {
"near": {"type": "Point", "coordinates": [116.48, 39.99]},
"distanceField": "dist",
"maxDistance": 5000,
"spherical": True
}
},
{
"$match": {"status": "active", "category": {"$in": ["cafe", "restaurant"]}}
}
]
注意点：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
-
spherical: True必须设，否则按平面欧氏距离算，5km 以内误差可能达百米级 -
maxDistance单位是米，不是公里，别写成5想表示 5km - 距离字段名（如
"dist"）会在后续 stage 可直接引用，不用再算
Python 中用 PyMongo 构造 GeoJSON Point 要小心浮点精度和字段名
手动拼 {"type": "Point", "coordinates": [...]} 容易出错：比如用字符串拼接、坐标类型是 str、或字段名写成 "coordinate" 少了个 s。PyMongo 不报错但查不到结果——因为字段结构不合法，索引压根不生效。
推荐做法：
- 用字典字面量，不要用
json.dumps()或字符串格式化 - 确保
coordinates是 float 类型列表，且长度为 2；可加校验：assert len(coords) == 2 and all(isinstance(x, (int, float)) for x in coords) - 插入前统一用
collection.update_one(..., upsert=True)配合$setOnInsert避免重复插入脏数据
示例（安全构造）：
lng, lat = float(request.args.get("lng")), float(request.args.get("lat"))
geo_point = {"type": "Point", "coordinates": [lng, lat]}
result = collection.aggregate([
{"$geoNear": {"near": geo_point, "distanceField": "dist", "maxDistance": 3000, "spherical": True}},
{"$match": {"name": {"$regex": "咖啡", "$options": "i"}}}
])
性能瓶颈常在未限制返回数量，或没加业务过滤条件
不做 $limit 的 $geoNear 可能扫全表——尤其当附近有上万商家时，即使加了 maxDistance，MongoDB 仍可能先算所有点距离再过滤。更糟的是，如果漏掉 $match 里的关键业务字段（比如 "status": "online"），就会把已下线商家也拉出来算距离，白白消耗 CPU 和内存。
实操建议：
- 永远在
$geoNear后紧跟$limit，比如{"$limit": 50}，前端分页由 offset + limit 控制，而不是靠 skip - 把高区分度的业务条件（如
city_code、is_verified）尽量提前到$match，哪怕它不在第一阶段——MongoDB 会自动优化执行顺序 - 避免在
$geoNear阶段用query参数做复杂过滤（已废弃），统一用后续$match
真正上线时，maxDistance 和 $limit 得根据实际热区密度动态调：商圈中心设 1km+50 条，郊区可能得放宽到 3km+20 条，否则用户总看到“附近没商家”。
