首页 / MapLibre / API 文档

ImageSource

先看结论

把一张普通图片按四角坐标贴到地图上，适合历史地图、规划平面图与单幅影像。

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

map.addSource(id, { type: 'image', url: '…', coordinates: [左上, 右上, 右下, 左下] })

参数

字段	默认	说明
`url`	—	图片地址，必填；也接受 data URL
`coordinates`	—	四个角点的经纬度，顺序固定

coordinates 的四个元素依次是图片的左上、右上、右下、左下角，每项为 [lng, lat]。图片不做重投影，始终按四点做仿射变换，所以只有已经校正到 Web 墨卡托（或近似）的图才不会歪。

成员

成员	说明
`updateImage({ url?, coordinates? })`	换图或调整位置，复用同一个 source
`setCoordinates(coordinates)`	只移动位置，不重新请求图片
`loaded()`	图片是否加载完成
`data` 事件	图片到达后触发
`error` 事件	请求失败或跨域被拦

示例

map.addSource('plan', {
  type: 'image',
  url: '/tiles/plan-1926.png',
  coordinates: [
    [116.30, 39.96],
    [116.46, 39.96],
    [116.46, 39.86],
    [116.30, 39.86]
  ]
});

map.addLayer({
  id: 'plan',
  type: 'raster',
  source: 'plan',
  paint: { 'raster-opacity': 0.85 }
});

/* 之后换图，不需要删除图层 */
map.getSource('plan').updateImage({
  url: '/tiles/plan-1938.png'
});

注意事项

四点顺序写反会让图片上下颠倒或左右镜像，且不会有任何提示。遇到镜像时先检查第二、第四点是不是写成了右上、左下以外的组合。

updateImage 传新 url 会重新发起请求，但浏览器可能命中旧缓存；调试换图效果时给地址加版本参数，例如 ?v=2，比清缓存可靠。

大图不要用 ImageSource。整张图会被解码成一张纹理，边长超过 GPU 上限（通常 4096 或 8192）就直接失败。超大图应切瓦片，走 raster 源。

引用本文

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