项目地址: https://github.com/maplibre/maplibre-gl-js
官方文档: https://maplibre.org/maplibre-gl-js/docs/
API 参考: https://maplibre.org/maplibre-gl-js/docs/API/
样式规范: https://maplibre.org/maplibre-style-spec/
最新版本: 6.17.0(截至 2026-11,npm
maplibre-gldist-taglatest;GitHub Releases 同步)许可证: BSD-3-Clause(v6 起的发行物为 ESM-only,UMD 构建已移除)
概述
MapLibre GL JS 是基于 WebGL2 的矢量瓦片地图渲染库,源自 Mapbox GL JS v1 的 BSD 分支,现由 MapLibre 社区独立维护。样式由 Style Spec JSON 驱动,客户端按需请求矢量瓦片、字体与精灵图,再用 GPU 逐帧绘制,因此缩放平滑、样式可运行时改动,且不需要任何商业 token。
- 矢量瓦片渲染:MVT 瓦片 + 客户端样式,任意缩放级别清晰;同时支持栅格瓦片与 GeoJSON 源
- Style Spec 样式规范:sources / layers / expressions 全部 JSON 化,可版本化、可服务端下发
- 数据驱动样式:表达式按要素属性、
zoom、feature-state动态计算颜色、宽度、透明度 - 三维能力:
raster-dem地形源 +setTerrain,配setSky做天空与大气;globe 投影可直接切换 - 可扩展协议:
addProtocol注册自定义加载器,PMTiles、COG 等单文件瓦片方案由此接入 - 开源免 token:底图可用公共 demotiles、自建 tile server 或 PMTiles,不受 Mapbox 配额与 TOS 约束
与相邻技术的差异:Mapbox GL JS 是同一血统的闭源商业版本(v2 起专有许可、必须 token);OpenLayers 偏全能型二维 GIS(投影、WMS/WMTS 更强);deck.gl 负责大规模数据图层,通常叠在 MapLibre 底图之上。
环境准备
npm 安装
v6 是 ESM-only 发行方式,包内只有 dist/maplibre-gl.mjs,不再提供 maplibre-gl.js 这类 UMD 文件:
npm install maplibre-gl
npm ls maplibre-gl # 验证:应显示 maplibre-gl@6.17.0
// v6:用命名空间导入或具名导入,没有 default export
import * as maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
center: [116.39, 39.91],
zoom: 4
});
<!-- 容器必须有显式高度,否则地图不可见 -->
<style>#map { height: 500px; }</style>
<div id="map"></div>
CDN(无构建步骤)
由于 UMD 已移除,CDN 场景也必须走 ES module:
<link href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.17.0/dist/maplibre-gl.css" rel="stylesheet">
<script type="module">
import * as maplibregl from 'https://cdn.jsdelivr.net/npm/maplibre-gl@6.17.0/dist/maplibre-gl.mjs';
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
center: [0, 20],
zoom: 1
});
window.__map = map; // 便于控制台调试
</script>
验证
# 包与入口存在性(v6 只有 .mjs,查 .js 得到 404 是正常的)
npm ls maplibre-gl
curl -s -o /dev/null -w '%{http_code}\n' https://cdn.jsdelivr.net/npm/maplibre-gl@6.17.0/dist/maplibre-gl.mjs
页面能显示 demotiles 世界地图、拖拽缩放正常,即环境就绪。浏览器控制台出现 WebGL2 is required 说明运行环境不支持 WebGL2,换浏览器或开启硬件加速。
v5 升 v6 的破坏性变更
| 变更 | 影响与改法 |
|---|---|
| ESM-only,UMD 构建移除 | <script src=".../maplibre-gl.js"> 改为 <script type="module">;import maplibregl from 'maplibre-gl' 改为 import * as maplibregl from 'maplibre-gl' 或具名导入 |
| 只支持 WebGL2 | WebGL1 路径删除;失败信息可通过 map.on('error') 捕获 |
Map 改为组合 Camera 而非继承 |
相机 API 仍由 Map 转发;内部 map.transform 已移除,不要再访问 |
styleimagemissing 变为只通知 |
不能再在该事件里同步补图,改用 map.setMissingStyleImageResolver(fn)(支持 async) |
GeoJSONSource#setData 去掉第二个参数与返回值 |
setData(data) 只传数据,不要再用 waitForCompletion |
| Style Spec 升到 v25 | 遗留表达式写法会以 warning 级错误抛出,需按新版表达式改写 |
事件改为真实类,MapDataEvent 移除 |
源码数据事件是 MapSourceDataEvent 或 MapStyleDataEvent;MapLibreZoomEvent 更名 MapBoxZoomEvent |
着色器指令 #pragma mapbox 改为 #pragma maplibre |
自定义图层若依赖该指令需同步改 |
zoomLevelsToOverscale 默认改为 4 |
高缩放密集标注更自然,但 queryRenderedFeatures 结果可能变化;要还原设为 undefined |
| TypeScript 目标升到 ES2022 | 需要转译 MapLibre 或升级构建链的旧工程会报语法错误 |
核心 API
Map 与生命周期
import * as maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
center: [116.39, 39.91],
zoom: 5,
pitch: 0,
bearing: 0,
minZoom: 0,
maxZoom: 18,
attributionControl: { compact: true },
hash: true // 把视图同步到 URL #zoom/lat/lng
});
map.on('load', () => { /* 样式与初始瓦片就绪后再加图层 */ });
map.on('error', (e) => console.error(e.error));
| 阶段 | 判断方式 | 可做什么 |
|---|---|---|
| 构造完成 | new Map() 返回 |
绑定事件、加控件 |
| 样式就绪 | map.isStyleLoaded() / load / style.load |
addSource / addLayer |
| 瓦片渲染完 | map.areTilesLoaded() / idle |
截图、批量查询 |
| 销毁 | map.remove() |
释放 WebGL 上下文与 Worker |
数据源 Source
type |
用途 | 关键字段 |
|---|---|---|
geojson |
要素集合,可运行时 setData |
data、cluster、generateId |
vector |
MVT 矢量瓦片 | tiles / url、minzoom、maxzoom |
raster |
栅格瓦片底图 | tiles、tileSize、attribution |
raster-dem |
地形高程(Terrarium/Mapbox DEM) | encoding、tileSize |
image |
单张地理配准图片 | url、coordinates |
map.addSource('pois', { type: 'geojson', data: '/data/poi.geojson' });
map.addSource('dem', {
type: 'raster-dem',
url: 'https://demotiles.maplibre.org/terrain-tiles/tiles.json',
tileSize: 256
});
const src = map.getSource('pois');
src.setData(newGeoJson); // v6:只传数据,无第二参数
图层 Layer
图层按 type 分类,通过 filter、paint、layout 控制外观。绘制顺序即数组顺序,后加的在上。
map.addLayer({
id: 'pois-circle',
type: 'circle',
source: 'pois',
filter: ['==', ['get', 'kind'], 'station'],
paint: {
'circle-radius': ['interpolate', ['linear'], ['zoom'], 6, 3, 14, 12],
'circle-color': ['match', ['get', 'level'], 'high', '#d7301f', 'mid', '#fc8d59', '#fee08b'],
'circle-stroke-width': 1,
'circle-stroke-color': '#ffffff'
}
});
map.addLayer({
id: 'pois-label',
type: 'symbol',
source: 'pois',
layout: {
'text-field': ['get', 'name'],
'text-size': 12,
'text-offset': [0, 1.2]
},
paint: { 'text-halo-color': '#fff', 'text-halo-width': 1 }
});
常用图层类型:background、fill、line、symbol、circle、heatmap、fill-extrusion(3D 建筑)、raster、hillshade、clip。
表达式与数据驱动样式
表达式是 JSON 数组,第一个元素是操作符。它是 Style Spec 的核心,替换了早期的 stops 写法。
// 缩放插值
['interpolate', ['linear'], ['zoom'], 4, 1, 10, 6]
// 属性分支
['case', ['>', ['get', 'pop'], 1000000], '#800026', '#feb24c']
// 算术与颜色
map.setPaintProperty('buildings', 'fill-extrusion-height',
['*', ['coalesce', ['get', 'height'], 10], 1.0]);
// feature-state 联动(悬停高亮)
map.setPaintProperty('pois-circle', 'circle-opacity',
['case', ['boolean', ['feature-state', 'hover'], false], 1, 0.5]);
控件、Marker 与 Popup
map.addControl(new maplibregl.NavigationControl({ visualizePitch: true }), 'top-right');
map.addControl(new maplibregl.ScaleControl({ unit: 'metric' }), 'bottom-left');
map.addControl(new maplibregl.GeolocateControl({ trackUserLocation: true }));
map.addControl(new maplibregl.FullscreenControl());
const marker = new maplibregl.Marker({ color: '#d7301f' })
.setLngLat([116.39, 39.91])
.setPopup(new maplibregl.Popup().setHTML('<b>北京</b>'))
.addTo(map);
marker.togglePopup();
三维地形与天空
map.addSource('dem', {
type: 'raster-dem',
url: 'https://demotiles.maplibre.org/terrain-tiles/tiles.json',
tileSize: 256
});
map.setTerrain({ source: 'dem', exaggeration: 1.5 });
map.setSky({
'sky-color': '#88c6fc',
'horizon-color': '#ffffff',
'fog-color': '#ffffff',
'sky-horizon-blend': 0.5
});
// 三维建筑
map.addLayer({
id: 'buildings-3d',
type: 'fill-extrusion',
source: 'buildings',
paint: {
'fill-extrusion-height': ['get', 'height'],
'fill-extrusion-base': ['get', 'min_height'],
'fill-extrusion-color': '#a0a0a0',
'fill-extrusion-opacity': 0.85
}
});
投影切换(含 globe)
样式里写 projection 即可切换,无需插件:
map.setProjection({ type: 'globe' });
map.setProjection({ type: 'mercator' });
// 实验能力:注册自定义 CRS 平面投影(6.15 起)
maplibregl.addProjection({
name: 'EPSG:2193',
projection: /* proj4 转换函数 */ customProjection
});
自定义 CRS 属于实验 API,生产环境优先用 Mercator 或 globe。
自定义协议与 PMTiles
addProtocol 让 sources 里的伪协议 URL 由自定义函数加载,PMTiles 就靠它把单文件瓦片包当作任意 z/x/y 请求的源:
import { Protocol } from 'pmtiles';
const protocol = new Protocol();
maplibregl.addProtocol('pmtiles', protocol.tile);
map.addSource('basemap', {
type: 'vector',
url: 'pmtiles://https://example.com/tiles.pmtiles',
attribution: 'PMTiles'
});
同理可接入 COG 栅格源。协议注册是全局的,同一页面多个 Map 共享;不再使用时 maplibregl.removeProtocol('pmtiles')。
交互查询与要素状态
map.on('click', 'pois-circle', (e) => {
const feature = e.features[0];
new maplibregl.Popup()
.setLngLat(e.lngLat)
.setHTML(`<b>${feature.properties.name}</b>`)
.addTo(map);
});
map.on('mousemove', 'pois-circle', (e) => {
map.getCanvas().style.cursor = 'pointer';
if (e.features.length) {
map.setFeatureState(
{ source: 'pois', id: e.features[0].id },
{ hover: true }
);
}
});
// 屏幕坐标查要素
const hits = map.queryRenderedFeatures({ layers: ['pois-circle'] });
典型工作流
链路一:自建矢量瓦片 + 属性联动样式
输入:tile server 上的 {z}/{x}/{y}.mvt 与属性字段 level;输出:按等级着色的可点击地图。
- 加载空样式骨架:
new maplibregl.Map({ style: { version: 8, sources: {}, layers: [] } }) map.addSource('base', { type: 'vector', tiles: ['https://tiles.example.com/{z}/{x}/{y}.mvt'], minzoom: 0, maxzoom: 14 })- 用
source-layer指定 MVT 内的图层名,加fill+line两个图层 - 用
match表达式按level着色,用filter拆不同业务图层 - 绑定
click/mousemove事件,配合setFeatureState做悬停高亮 - 校验:缩放各级别瓦片正常、控制台无 404、
map.areTilesLoaded()为 true
map.addSource('base', {
type: 'vector',
tiles: ['https://tiles.example.com/{z}/{x}/{y}.mvt'],
minzoom: 0,
maxzoom: 14
});
map.addLayer({
id: 'parcel-fill',
type: 'fill',
source: 'base',
'source-layer': 'parcel',
paint: {
'fill-color': ['match', ['get', 'level'], 'A', '#2b8cbe', 'B', '#a6bddb', '#ece7f2'],
'fill-opacity': 0.75
}
});
链路二:GeoJSON 热力 + 地形 + 点击详情
输入:/data/events.geojson;输出:带地形与热力的分析视图。
- 加
raster-dem源并setTerrain,再做setSky补天空 - 加载 GeoJSON 源,加
heatmap图层(heatmap-weight用属性字段) - 叠加
circle图层用于精确点击,filter限定可点要素 click回调里用Popup展示属性,closeOnClick默认 true- 校验:地形起伏可见、热力随缩放变化、点击有弹窗
map.addSource('events', { type: 'geojson', data: '/data/events.geojson' });
map.addLayer({
id: 'events-heat',
type: 'heatmap',
source: 'events',
paint: {
'heatmap-weight': ['get', 'count'],
'heatmap-radius': ['interpolate', ['linear'], ['zoom'], 5, 8, 13, 40],
'heatmap-opacity': 0.7
}
});
map.addLayer({
id: 'events-point',
type: 'circle',
source: 'events',
paint: { 'circle-radius': 3, 'circle-color': '#ffffff', 'circle-opacity': 0 }
});
链路三:样式热切换与图片按需补全
输入:用户切换主题;输出:不重建地图、仅替换样式,且缺失图标自动补。
- 用
map.setStyle(nextStyle)整体换样式,不要销毁重建 Map - 用
transformStyle在构造或setStyle时注入通用改动(如统一字体、加业务图层) - 缺失图标不再靠
styleimagemissing补,改用setMissingStyleImageResolver异步取图 - 监听
style.load后再补加自定义图层与数据源 - 校验:切换后业务图层仍在、图标不缺、无重复图层报错
map.setMissingStyleImageResolver(async (id) => {
const response = await fetch(`/icons/${id}.png`);
if (!response.ok) return;
const image = await createImageBitmap(await response.blob());
map.addImage(id, image, { pixelRatio: 2 });
});
map.on('style.load', () => {
map.addSource('pois', { type: 'geojson', data: geojson });
map.addLayer({ id: 'pois', type: 'circle', source: 'pois' });
});
性能优化与最佳实践
- GeoJSON 源走瓦片化:超过约 10 万要素改用
vector源或服务端切片,GeoJSON 源在浏览器内做geojson-vt索引会占用主线程 - 保持数据引用稳定:
setData传新对象才触发重绘,但要避免每帧调用,节流到重绘帧率 - 用
feature-state而非改 paint:悬停/选中用 feature-state,避免整层setPaintProperty造成全量重绘 - 控制同时可见图层数:图层越多每帧绘制开销越大,非当前视野的图层用
layout.visibility = 'none' - 合理设
maxzoom:源声明真实maxzoom,让客户端复用父级瓦片过度缩放,而不是请求不存在的瓦片 - 关闭不必要的开销:
canvasContextAttributes里默认antialias: false、preserveDrawingBuffer: false,只有截图需求才开 - 预初始化 Worker:多地图页面可用
prewarm()提前创建共享 Worker(需在setWorkerUrl()之后调用) - 及时销毁:
map.remove()释放上下文;SPA 路由切换务必调用,否则 WebGL 上下文会累积到浏览器上限
常见问题
| 问题 | 原因 | 处置 |
|---|---|---|
报 WebGL2 is required 或地图不渲染 |
v6 移除了 WebGL1 支持,运行环境(无头浏览器、远程桌面软件渲染、旧驱动)没有 WebGL2 | 开启浏览器硬件加速;无头环境改用带 GPU 的容器或接受无法渲染;用 map.on('error') 捕获具体原因 |
import maplibregl from 'maplibre-gl' 后 new maplibregl.Map 报 undefined |
v6 无 default export(ESM-only 改造的一部分) | 改为 import * as maplibregl from 'maplibre-gl' 或 import { Map } from 'maplibre-gl' |
引入 CDN 后报 Unexpected token 'export' |
v6 不再发布 UMD,旧的 <script src> 方式加载了 ESM 文件 |
改用 <script type="module">,并直接从 CDN 导入 .mjs |
| 地图空白但无报错 | 容器没有高度,或 addLayer 早于样式就绪 |
给容器设显式高度;在 load 或 isStyleLoaded() 之后再 addSource/addLayer |
| 升级后控制台出现表达式 warning | Style Spec v25 把遗留表达式从静默失败改为 warning 级错误 | 按新版表达式重写;确认自定义样式里没有旧 stops 残留写法 |
styleimagemissing 里补图不生效 |
v6 起该事件只通知,不再允许同步提供图片 | 改用 map.setMissingStyleImageResolver(async (id) => { ... }) |
setData(data, true) 行为异常 |
v6 移除了第二参数与返回值 | 只调用 setData(data);需要等渲染用 idle 事件 |
| 自定义图层 shader 编译失败 | v6 把 #pragma mapbox 改为 #pragma maplibre |
同步修改自定义图层的着色器指令 |
| 截图空白 | preserveDrawingBuffer 默认 false,WebGL 缓冲在呈现后丢弃 |
构造时设 canvasContextAttributes: { preserveDrawingBuffer: true },或改用 map.triggerRepaint() 后立即抓取 |
| 切换路由后地图越来越多内存 | 未调用 map.remove(),WebGL 上下文不断累积 |
组件卸载时 map.remove(),并移除 addProtocol 注册的全局协议 |
AI 使用建议
- 执行环境:
npm install、npm run build在终端执行;Windows 下 npm 实际是npm.cmd,脚本里写cmd /c npm run build更稳;装包与大构建放后台,输出重定向到文件再分段读。 - 先探测版本:
npm ls maplibre-gl(未安装时npm view maplibre-gl version),本技能按 6.17.0 编写。遇到new maplibregl.Map is not a constructor先怀疑是否还在用 v5 的 default import 写法。 - 验证产物:
npm run build后npx serve dist,用curl -s -o /dev/null -w '%{http_code}'检查入口与maplibre-gl.css返回 200;WebGL 是否真出图只能由浏览器确认,AI 助手通常看不到画面,请用户看画面与控制台,环境支持读图时用截图核对。 - 无 GPU 环境:无头/CI 无法验证 WebGL2,构建通过不等于渲染正确,不要据此报告"已渲染"。
- 坐标顺序:所有经纬度都是
[lng, lat](经度在前),与 Leaflet 相反;LngLatBounds用[[west, south], [east, north]]。 - 样式调试顺序:先确认
style可访问(404 会导致整图空白且只有 error 事件),再确认source-layer与 MVT 内的图层名一致,最后才怀疑表达式。 - 常见症状:空白图先查容器高度与样式 URL;瓦片 404 查
minzoom/maxzoom与 tile URL 模板;点击无反应查图层id是否与事件绑定的一致。 - 安全与权限:装包、起 dev server、改端口前先征得用户同意;
addProtocol与第三方瓦片 URL 要确认来源可信,避免把内网地址写进样式。
相关技能
- mapbox-gl-js — 同源商业版本,API 高度相似,迁移时对照:../mapbox-gl-js/SKILL.md
- maplibre-native — 同一体系的 C++ 原生渲染引擎(Android/iOS/Node):../maplibre-native/SKILL.md
- openlayers — 全能型二维 WebGIS,WMS/WMTS 与投影能力更强:../openlayers/SKILL.md
- deck-gl — 大规模数据图层,常叠加在 MapLibre 底图之上:../deck-gl/SKILL.md
- leaflet — 更轻量的二维瓦片地图方案:../leaflet/SKILL.md
- stac-cog-titiler — 为地图提供动态影像瓦片的后端链路:../stac-cog-titiler/SKILL.md
参考资源
- 官方文档:https://maplibre.org/maplibre-gl-js/docs/
- API 参考:https://maplibre.org/maplibre-gl-js/docs/API/
- 样式规范:https://maplibre.org/maplibre-style-spec/
- 示例集:https://maplibre.org/maplibre-gl-js/docs/examples/
- v5 到 v6 迁移指南:https://github.com/maplibre/maplibre-gl-js/blob/main/docs/guides/v5-to-v6-migration-guide.md
- 发布记录:https://github.com/maplibre/maplibre-gl-js/releases
- 演示样式(demotiles):https://demotiles.maplibre.org/style.json
- 中文教程:https://znlgis.github.io/gis/tutorial/maplibre-gl-js/