样式规范 Style Spec

顶层字段

version: 8 是硬性要求。写成 7 或省略，MapLibre 在解析阶段就拒绝整份样式， 地图停在空白状态。这个字段从 2016 年至今没有变过。

一份可运行的内联样式

style 除了接受 URL，也接受对象。内联样式适合「底图固定、只调整少量图层」 的场景，省掉一次网络请求，也能避免样式文件被缓存住改不动。

var style = {
  version: 8,
  sources: {
    base: {
      type: 'raster',
      tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
      tileSize: 256,
      attribution: '© OpenStreetMap contributors'
    }
  },
  layers: [
    {
      id: 'bg',
      type: 'background',
      paint: { 'background-color': '#0d1117' }
    },
    {
      id: 'base-tiles',
      type: 'raster',
      source: 'base',
      paint: { 'raster-opacity': 0.85 }
    }
  ]
};

var map = new maplibregl.Map({
  container: 'map',
  style: style,
  center: [116.391263, 39.907359],
  zoom: 4
});

栅格底图也能写成样式，但这样就失去了矢量样式的价值：无法按属性改色、 无法在 60 度倾斜下保持清晰。真实项目里底图多用 vector 源。

图层类型

类型决定了哪些 paint 与 layout 属性可用。 给 line 图层写 fill-color，属性会被校验器拒绝， 控制台出现 unknown property，图层退化为默认外观。

图层的最小结构

除 background 外，每个图层都要有 id、type、 source；矢量瓦片源还必须写 source-layer。

{
  "id": "countries-fill",
  "type": "fill",
  "source": "base",
  "source-layer": "countries",
  "filter": ["==", ["geometry-type"], "Polygon"],
  "paint": {
    "fill-color": ["match", ["get", "continent"], "Asia", "#f2e8d5", "#e8eef4"],
    "fill-opacity": 0.9
  }
}

id 在整份样式里必须唯一，它是运行时 setPaintProperty、 removeLayer、beforeId 的唯一句柄。用业务语义命名， 不要用 layer-1 这类序号。

样式从哪来

• 官方演示样式：https://demotiles.maplibre.org/style.json，无需 Key，只有国界与经纬网。
• 自建样式：用 Maputnik 这类可视化编辑器产出 JSON，托管为静态文件。
• 第三方底图：多数服务商提供完整 style URL，但瓦片与字体都在对方服务器上。

注意事项

source-layer 写错不报错

矢量瓦片里的图层名由数据方定义，写错时图层为空，控制台没有提示。 先用 map.getStyle().layers 或瓦片检查工具确认实际图层名。

把 glyphs 指向不存在的字体

text-font 必须与 glyphs 服务提供的字体栈完全一致。 服务里只有 Noto Sans Regular 却写 Open Sans Bold， 文字一个都不出现，且不抛错。

样式对象被复用后又被修改

map.setStyle(style) 不会深拷贝传入的对象，MapLibre 内部会就地加工。 同一份对象反复传给多个地图实例，第二个实例可能拿到已被改写的结构。 每次传之前做一次深拷贝。