首页 / MapLibre / API 文档

GeoJSONSource

先看结论

浏览器端的 GeoJSON 数据源，支持全量替换、客户端聚合与要素状态。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-27 · 引用本文

map.addSource(id, { type: 'geojson', data: geojson, … })

配置项

字段	默认	说明
`data`	—	GeoJSON 对象或指向 GeoJSON 的 URL
`cluster`	false	开启客户端聚合
`clusterRadius`	50	聚合半径，像素
`clusterMaxZoom`	—	超过该缩放级别不再聚合
`clusterProperties`	—	聚合时对属性做求和、最大值等运算
`generateId`	false	为没有 id 的要素自动生成 id
`promoteId`	—	用指定属性作为要素 id，供 feature-state 使用
`tolerance`	0.375	简化容差，值越大顶点越少
`buffer`	128	瓦片边缘留白，防止线宽被裁切

方法与事件

成员	说明
`setData(data)`	全量替换数据，图层自动重绘
`getData()`	取回当前数据
`getClusterExpansionZoom(clusterId)`	返回 Promise，得到该簇展开时的缩放级别
`setClusterOptions(options)`	运行时调整聚合参数
`data` 事件	数据加载或更新完成
`error` 事件	URL 拉取失败或 JSON 解析失败

示例

map.addSource('cities', {
  type: 'geojson',
  data: '/data/cities.geojson',
  cluster: true,
  clusterRadius: 50,
  clusterMaxZoom: 7
});

map.addLayer({
  id: 'city-dots',
  type: 'circle',
  source: 'cities',
  filter: ['!', ['has', 'point_count']],
  paint: { 'circle-radius': 4, 'circle-color': '#1f5fd0' }
});

/* 点击簇，展开到能看清单个点的级别 */
map.on('click', 'city-clusters', function (e) {
  var f = e.features[0];
  var src = map.getSource('cities');

  src.getClusterExpansionZoom(f.properties.cluster_id)
    .then(function (zoom) {
      map.easeTo({
        center: f.geometry.coordinates,
        zoom: zoom
      });
    });
});

更新策略

setData 是替换而非增量。数据量大、更新频繁时，每次都序列化整个 FeatureCollection 会明显卡顿。常见做法是保留一份可变数组，改动后节流合并，每 200–500 毫秒推送一次。

只需要高亮个别要素时不要用 setData，用 promoteId 加 setFeatureState，数据传输为零，切换也更快。

数据规模边界

要素数量	建议
数千以内	直接 GeoJSON，简单可靠
数万	开聚合，或降低简化容差
十万以上	改用矢量瓦片，服务端切片与简化

URL 形式的错误不会抛异常。地址 404 或返回 HTML 时， source 为空，图层什么都不画。监听 source 的 error 事件，比盯着空白地图猜要快得多。

引用本文

经纬志（2026）。《GeoJSONSource》。https://www.jingweizhi.com/maplibre/api/geojson-source.html（访问日期 2026-11-03）。