数据源类型

六种类型的对照

tiles 里的 {z}/{x}/{y} 由 MapLibre 逐块替换； url 指向一份 TileJSON，里面已经写好了瓦片地址模板与缩放范围。 两者二选一，同时写以 tiles 为准。

矢量瓦片与影像的叠加

最常见的组合：矢量底图提供路网与注记，影像源叠在下方或上方。 影像瓦片通常是 256 像素，写成 512 会被拉伸成两倍大小、清晰度减半。

map.addSource('satellite', {
  type: 'raster',
  tiles: [
    'https://example.com/imagery/{z}/{x}/{y}.jpg'
  ],
  tileSize: 256,
  minzoom: 0,
  maxzoom: 18,
  attribution: '影像 © 数据提供方'
});

map.addLayer({
  id: 'satellite-layer',
  type: 'raster',
  source: 'satellite',
  paint: {
    'raster-opacity': 0.9,
    'raster-fade-duration': 150
  }
}, 'roads-line');   // 压在道路图层之下

raster-fade-duration 控制瓦片切换时的淡入时长。设成 0 会立刻切换， 拖动时出现明显的方块跳变；保持默认的 300 毫秒更平滑。

地形源

高程数据是一种特殊栅格：像素值不是颜色，而是高度。解码方式由 encoding 指定，常见两种：

map.addSource('dem', {
  type: 'raster-dem',
  tiles: [
    'https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'
  ],
  encoding: 'terrarium',
  tileSize: 256,
  maxzoom: 14
});

map.setTerrain({ source: 'dem', exaggeration: 1.4 });

tileSize 对地形源很关键。terrarium 瓦片是 256 像素， 写成 512 会让高程采样错位，山体形状扭曲。

GeoJSON 源与内建聚合

data 可以是对象，也可以是 URL。给 cluster: true 之后， MapLibre 自己在客户端做网格聚合，图层读到的就是聚合点， 不再需要外部插件。

map.addSource('sites', {
  type: 'geojson',
  data: 'https://example.com/api/sites.geojson',
  cluster: true,
  clusterRadius: 50,
  clusterMaxZoom: 14,
  clusterProperties: {
    total: ['+', ['get', 'value']]     // 每个簇累加 value
  }
});

map.addLayer({
  id: 'sites-unclustered',
  type: 'circle',
  source: 'sites',
  filter: ['!', ['has', 'point_count']],
  paint: { 'circle-radius': 4, 'circle-color': '#17694a' }
});

聚合后的要素带 point_count、point_count_abbreviated 与 cluster_id。要区分聚合点与原始点，用 ['has', 'point_count'] 过滤，而不是判断几何类型。

更新数据

GeoJSON 源有 setData，只重新解析数据、不重建图层， 是实时刷新的正确方式。矢量与栅格源没有对应方法，改数据要换源或换瓦片地址。

var src = map.getSource('sites');
src.setData(updatedFeatureCollection);   // 整份替换

// 需要按 URL 轮询时，直接给 setData 传地址
src.setData('https://example.com/api/sites.geojson?t=' + Date.now());

注意事项

source 先于 layer 存在

addLayer 引用的 source 必须已经 addSource。 顺序反过来，报错信息是 Source "xxx" not found， 但错误常常出现在别的方法调用里，容易误判。

给矢量源加 source-layer 之外的过滤

source-layer 写错时图层为空；同一份瓦片里换一个图层名， 常规属性名往往完全不同。过滤条件里用到的字段名，以数据方文档为准。

image 源的坐标顺序

coordinates 是四个角点，顺序为左上、右上、右下、左下， 每项是 [经度, 纬度]。顺序写反，图片会翻转或扭曲， 而不是报错。