首页 / MapLibre / API 文档

RasterSource

先看结论

切片形式的栅格影像源，一张瓦片就是一张图片，适合影像底图、扫描图与专题栅格。

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

map.addSource(id, { type: 'raster', tiles: [...], tileSize: 256, … })

参数

字段	默认	说明
`url`	—	TileJSON 地址，与 `tiles` 二选一
`tiles`	—	瓦片模板数组，可写多个域名分摊请求
`tileSize`	512	单张瓦片的像素边长，必须与服务端一致
`minzoom`	0	低于该级别不请求瓦片
`maxzoom`	22	高于该级别放大低级别瓦片，不再请求
`scheme`	`'xyz'`	另一种是 `'tms'`，y 轴方向相反
`bounds`	null	`[west, south, east, north]`，限定请求范围
`attribution`	—	来源声明，出现在右下角版权信息里
`volatile`	false	为 true 时不缓存瓦片，每帧都可能重取

成员

成员	说明
`setTiles(tiles)`	替换瓦片模板，不重建 source
`setUrl(url)`	改用 TileJSON 地址，运行时切服务
`setSourceProperty(callback)`	直接改写内部源属性，调用方需自行保证合法
`loaded()`	当前视野内的瓦片是否都已完成加载
`hasTile(tileID)`	指定瓦片是否已在缓存中
`data` 事件	瓦片到达或状态变化，配合 `isSourceLoaded` 判断完成
`error` 事件	404、跨域被拦或图片解码失败

示例

map.addSource('basemap', {
  type: 'raster',
  tiles: ['https://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png'],
  tileSize: 256,
  minzoom: 0,
  maxzoom: 19,
  attribution: '© OpenStreetMap contributors © CARTO'
});

map.addLayer({
  id: 'basemap',
  type: 'raster',
  source: 'basemap',
  paint: {
    'raster-opacity': 0.9,
    'raster-fade-duration': 150
  }
});

/* 换一套瓦片，图层不用动 */
var src = map.getSource('basemap');
src.setTiles(['https://basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png']);

注意事项

tileSize 写错是最常见的白图原因。服务端出 256 的瓦片、配置写 512 时，每张图只铺满半块瓦片，画面出现规律性的空隙；反之则相邻瓦片互相覆盖，细节被放大得模糊。

栅格瓦片走的是图片请求，浏览器要求跨域头。服务端没有 Access-Control-Allow-Origin 时，瓦片能下载但 WebGL 无法读取像素，控制台会报跨域污染，表现同样是空白。

高程数据也走这套结构。raster-dem 与 raster 共用 tiles、tileSize 等字段，区别是要声明 encoding（terrarium 或 mapbox），写错会得到整体偏移的高程。

引用本文

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