第一个 MapLibre 地图

完整代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.css">
  <style>
    html, body { height: 100%; margin: 0; }
    #map { height: 100%; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.js"></script>
  <script>
    var map = new maplibregl.Map({
      container: 'map',
      style: 'https://demotiles.maplibre.org/style.json',
      center: [116.391263, 39.907359],
      zoom: 4
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');
  </script>
</body>
</html>

style 是必填项

与 Leaflet 不同，MapLibre 没有「先建空地图再叠瓦片」的用法。 构造时必须给出样式：一个 style JSON 的 URL，或者一个内联的样式对象。 样式里决定了底图来自哪个瓦片服务、用哪些字体和图标。 v4 里省略 style 会直接报错，而不是给一张空白画布。

文档中的示例统一使用 https://demotiles.maplibre.org/style.json， 这是 MapLibre 官方提供的演示样式，不需要任何 Key。 它只包含国界、海岸线和经纬网，数据到 6 级缩放为止， 适合做功能演示，不适合当生产底图。

坐标顺序统一是「经度在前」

center: [116.39, 39.90] 是北京。 MapLibre 全线使用 [lng, lat]，与 GeoJSON 一致。 这和 Leaflet 的 [lat, lng] 相反， 两套库混用时最稳妥的做法是在变量名里带上顺序： lngLat 与 latLng 分开命名。

load 事件之后再动图层

样式里的源和图层是异步解析的。地图刚构造完就调用 addLayer，很可能因为样式还没就绪而失败。 所有自定义图层、数据源、事件绑定放在 load 回调里。

map.on('load', function () {
  map.addSource('points', {
    type: 'geojson',
    data: { type: 'Point', coordinates: [116.39, 39.90] }
  });

  map.addLayer({
    id: 'points',
    type: 'circle',
    source: 'points',
    paint: { 'circle-radius': 6, 'circle-color': '#1f5fd0' }
  });
});

切换整个样式（setStyle）之后，之前添加的源和图层会被清掉， 同样需要在新的 style.load 或 load 里重新添加。

控件的位置参数

容器采用绝对定位或 flex 布局都可以，但必须有确定高度。 父元素高度为 0 时，地图容器也是 0，页面上一片空白且没有任何报错。

空白地图的排查顺序

1. 容器高度是否为 0，用开发者工具看 #map 的实际尺寸。
2. CSS 是否漏引。样式表缺失不只会让控件变形，画布定位也会错位。
3. style 地址是否可访问，网络面板里是否有 4xx 或跨域错误。
4. 浏览器是否支持 WebGL2，禁用了硬件加速的环境会直接初始化失败。
5. 控制台是否有 style 解析错误，特别是 sources 缺失。

常见问题

地图能拖但看不到内容

样式加载成功、瓦片请求失败时就是这种表现：背景色来自样式的 background 图层，所以不是纯白。 打开网络面板看 .pbf 请求的响应码即可定位。

放大后只剩色块

demo 样式的数据只到 6 级。继续放大会进入「过度缩放」， 瓦片被拉伸，细节不会增加。这不是渲染错误，换一份完整底图即可。

移动端双指缩放与页面滚动冲突

地图容器在可滚动页面里时，触摸手势会同时触发页面滚动。 MapLibre 默认处理了画布内手势，但外层容器加 touch-action: none 更稳妥，代价是该区域无法滑动页面。