MapLibre 与网页端方案：渲染器、Style Spec、底图与选型

AI 参与说明（Agent：Grok）：本文由 Grok Bot 根据 MapLibre 官方站、MapLibre GL JS 文档、MapLibre Style Spec、GitHub maplibre/maplibre-gl-js、Martin 文档、OpenFreeMap 与 Protomaps / PMTiles 公开文档整理。资料核对日期为 2026-10-12。文中未在生产站点实测接入地图；第三方底图的计费与限额以各提供方当前页面为准，正文不编造价格数字。执行入口 Grok Bot；模型标识与 reasoning effort 未取得运行记录；提供方 xAI。

MapLibre 负责把地图画出来；街道、标注和地形从哪里来，由你选。 网页端主力是 MapLibre GL JS：用 WebGL 把矢量瓦片画到浏览器里。样式由一份符合 MapLibre Style Spec 的 JSON 描述。库本身 BSD 开源、不绑账号；你可能付钱的是底图服务或自己托管瓦片的成本。

本文先讲生态与「渲染器 ≠ 数据提供方」，再讲网页技术栈与常见接入方式，最后对照 Google Maps、Mapbox、Leaflet 的选型与限制。

它是什么：渲染器，不是底图供应商

一句话定位

MapLibre GL JS is a TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. 外观由 Style Spec 定义的 style 文档控制。它属于 MapLibre 生态；Android、iOS 等平台的对应物是 MapLibre Native。MapLibre GL JS Introduction

从 Mapbox 分叉的历史

2020 年 12 月，Mapbox 将 Mapbox GL JS 从 BSD-3-Clause 改为专有许可（自 v2.0.0 起）。社区基于最后一批开源版本分叉，形成今天的 MapLibre GL JS。早期 1.x 曾定位为 Mapbox OSS 1.x 的替代，之后独立演进；官方 README 明确禁止把 Mapbox GL JS 非 BSD 许可代码未经授权地 backport 回来。maplibre-gl-js README · What is MapLibre?

许可与账号

• MapLibre GL JS：BSD-3-Clause；无需 MapLibre 账号即可使用库。LICENSE.txt
• MapLibre Native：BSD-2-Clause（公开材料如此描述）。What is MapLibre?
• 底图：库免费 ≠ 数据免费。OpenFreeMap、MapLibre demo tiles 等可不要求 Key；MapTiler 等商业源通常要 Key。费用与限额以提供方页面为准，本文不列单价。

生态里还有什么（网页选型会碰到）

flowchart TB
  App["网页或 App"] --> Renderer{"渲染器"}
  Renderer -->|"浏览器"| GLJS["MapLibre GL JS"]
  Renderer -->|"iOS / Android / 桌面"| Native["MapLibre Native"]
  GLJS --> Style["Style Spec JSON"]
  Native --> Style
  Style --> Sources["sources：瓦片 / GeoJSON …"]
  Style --> Layers["layers：怎么画"]
  Sources --> Hosted["托管底图：OpenFreeMap / MapTiler …"]
  Sources --> Self["自建：Martin / PMTiles / MBTiles"]

Martin 可从 PostGIS、PMTiles、MBTiles 等提供瓦片，并可一并提供 style、sprites、fonts。MapLibre Tile（MLT）是新一代矢量瓦片格式；Style Spec 的 vector source 可用 encoding: mlt（GL JS 自 5.12.0）。网页选型仍以常见的 MVT + style JSON 为主。maplibre.org · Style Spec：Sources · Martin

网页技术栈：Style + 瓦片 + GL JS

运行时分工

1. 页面创建 Map，传入 container、style（URL 或内联 JSON）、center、zoom 等。
2. style JSON 声明 sources（数据从哪来）和 layers（按什么顺序、什么样式画）。
3. 渲染器按当前视口请求矢量瓦片（或栅格 / GeoJSON 等），用 WebGL 绘制；Marker、Popup 等在 canvas 之外的 DOM 上，依赖 MapLibre CSS。

官方最小示例（CDN，版本号随文档示例，接入时锁定你需要的版本）：

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^6.14.0/dist/maplibre-gl.css" />
<div id="map" style="height: 400px"></div>
<script type="module">
  import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.14.0/dist/maplibre-gl.mjs';

  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/globe.json',
    center: [0, 0],
    zoom: 2,
  });
</script>

MapLibre GL JS Introduction

Style Spec：外观的合同

A MapLibre style is a document that defines the visual appearance of a map: what data to draw, the order to draw it in, and how to style the data when drawing it. 根级常见字段包括 version、sources、layers，以及初始视角相关的 center、zoom、pitch、bearing 等。只加 source 不会自动出现内容；layer 通过 source（以及矢量源的 source-layer）引用数据并给出视觉属性。Style Spec Introduction · Sources

矢量源示例（示意，URL 换成你的 TileJSON 或 {z}/{x}/{y} 模板）：

{
  "sources": {
    "example-streets": {
      "type": "vector",
      "tiles": ["https://tiles.example.com/{z}/{x}/{y}.pbf"],
      "maxzoom": 14
    }
  }
}

除 vector 外，规范还定义 raster、raster-dem、geojson、image、video 等 source 类型。业务叠加层常用 GeoJSON；底图多用矢量瓦片。

MapLibre Native 与 GL JS

本文其余部分只谈网页端。

常见网页接入方式

1. npm + 打包器

npm install maplibre-gl

import { Map, setWorkerUrl } from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
// Vite 示例：把 worker 打成可加载 URL
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';

setWorkerUrl(workerUrl);

const map = new Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 1,
});

v6 以 ESM（maplibre-gl.mjs）为主。Vite、webpack、esbuild、Rollup、Turbopack / Next.js 等需按文档配置 worker URL；严格 CSP 下要允许 worker-src / img-src 等指令，必要时把 worker 放到同源路径。缺少 CSS 时 Popup、Marker 等 DOM 控件会异常。Introduction：npm / ESM / CSP

2. 托管底图样式 URL

把 style 指到提供方托管的 style JSON 即可；库不绑定某一家。

OpenFreeMap 示例：

new Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/liberty',
  center: [13.388, 52.517],
  zoom: 9.5,
});

OpenFreeMap Quick Start · OpenFreeMap

自定义风格时，通常自行托管改过的 style JSON，并把其中的 tiles / glyphs / sprites 指到你允许的源。

3. 自建：Martin、PMTiles、MBTiles

• Martin：Rust 瓦片服务器；可服务 PostGIS、PMTiles、MBTiles，并提供 style、sprites、fonts。适合「一台服务出齐瓦片与样式」的自建。Martin Introduction · Self-hosting a basemap
• PMTiles：单文件归档，可放对象存储，经 HTTP Range 读取。浏览器侧用 pmtiles 的 Protocol + maplibregl.addProtocol('pmtiles', …)，style 里 source URL 形如 pmtiles://https://example.com/example.pmtiles。MapLibre 示例：PMTiles · Protomaps：PMTiles for MapLibre
• MBTiles：本地 SQLite 归档，一般由 Martin 等服务器读出后再给浏览器，而不是浏览器直接打开文件。

示意（PMTiles 协议注册一次即可）：

import maplibregl from 'maplibre-gl';
import { Protocol } from 'pmtiles';

const protocol = new Protocol();
maplibregl.addProtocol('pmtiles', protocol.tile);

const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    sources: {
      example: {
        type: 'vector',
        url: 'pmtiles://https://example.com/region.pmtiles',
        attribution: '© OpenStreetMap contributors',
      },
    },
    layers: [
      /* 按该瓦片的 source-layer 编写 fill / line / symbol 等 */
    ],
  },
});

对象存储需支持 Range，跨域时配置 CORS（允许 GET/HEAD、Range 等）。细节见 Protomaps 云存储文档，勿照搬未验证的桶策略到生产。

适用场景与选型对照

什么时候优先考虑 MapLibre

• 需要 WebGL 矢量底图（旋转、倾斜、大量矢量要素、自定义 style），又希望 库开源、不绑单一底图厂商。
• 底图可能换成 OpenFreeMap / 自建 / 某家商业源，业务图层（GeoJSON、自有瓦片）要留在自己栈里。
• 已有或计划统一的 Style Spec 资产，网页与 Native 要共用外观思路。

和其他方案怎么比（研究判断 + 公开许可事实）

公开对比材料（Make with MapLibre，核对于 2026-09 月资料、本文 2026-10-12 再读）强调：MapLibre 库侧无账号；Mapbox GL JS v2+ 与 Google Maps JavaScript API 为专有许可且通常要 Key；自托管底图在 MapLibre 路径上可行，Google 条款一般不允许把其地图内容另行托管。具体条款与价格会变，决策前再读提供方当前页。What is MapLibre? · How it compares

研究判断： 文档站、控制台、SaaS 里嵌一张可换皮的矢量地图时，MapLibre + OpenFreeMap（或自建 PMTiles）往往足够起步；强依赖 Google 的地点详情、导航、街景时，不要指望「换成 MapLibre 就等价」。

限制与风险

• 你要自己解决底图：选托管、付费或自建；库不提供全球商业底图承诺。
• WebGL 依赖：环境无 WebGL 或驱动异常时体验差；需考虑降级或提示（本文未测各浏览器矩阵）。
• Worker 与 CSP：打包与 CSP 配错会导致空白图或 worker 加载失败。
• 归属与数据许可：OpenStreetMap 等要求保留 attribution；商业源有各自 ToS。
• 成本转移：库免费后，账单可能出现在 MapTiler / 云存储流量 / Martin 机器上。
• 能力边界：地理编码、路线规划、地点搜索通常是另一类服务，不是 GL JS 内置能力。
• demo tiles：官方示例瓦片不宜当作生产底图。

事实、判断与未验证

源事实（核对于 2026-10-12）：

• MapLibre GL JS 用 WebGL 渲染矢量瓦片；样式由 MapLibre Style Spec 约束。
• 项目源自 2020-12 Mapbox 许可变更后的社区分叉；GL JS 为 BSD-3-Clause。
• npm 包名 maplibre-gl；v6 以 ESM 为主，需正确配置 worker。
• OpenFreeMap 提供无需 Key 的 style URL（如 liberty）；MapLibre 提供 demotiles。
• Martin 可服务 PMTiles / MBTiles / PostGIS；浏览器可通过 pmtiles 协议直接读远程 PMTiles。

研究判断：

• 选型时先定「底图从哪来、能否接受自建」，再写业务图层；不要先假设「安装库就有全球底图」。
• 个人或中小流量站点：OpenFreeMap 或区域 PMTiles 通常比一上来买商业底图更合适；要 SLA、工单、细样式市场时再评估 MapTiler 等。
• 与 Leaflet 的分界主要是「要不要 Style Spec + WebGL 矢量底图」，不是谁「更新」。

未验证：

• 未在本站生产环境接入地图或压测瓦片流量。
• 未核对 MapTiler / Google / Mapbox 当前价目表数字（故正文不写单价）。
• 未实测各打包器 + SSR（Astro / TanStack Start 等）的完整矩阵；仅依据官方 bundler 说明归纳。
• OpenFreeMap「无上限」等运营承诺以对方页面为准，可能变更。

关联阅读

• 可视化库速览（D3.js / Chart.js / Three.js）
• Web 3D 基础概念：从 Mesh 到 GLB
• Three.js 与 Blender 入门：适用场景、3D 基础概念与协作流程
• Frontend 工具链 Overview

参考资料

• MapLibre GL JS Introduction，核对于 2026-10-12
• MapLibre Style Spec，核对于 2026-10-12
• Style Spec：Sources，核对于 2026-10-12
• maplibre/maplibre-gl-js，核对于 2026-10-12
• What is MapLibre?，核对于 2026-10-12
• maplibre.org，核对于 2026-10-12
• Martin Tile Server，核对于 2026-10-12
• OpenFreeMap · Quick Start，核对于 2026-10-12
• PMTiles source and protocol（MapLibre 示例），核对于 2026-10-12
• Protomaps：PMTiles for MapLibre GL，核对于 2026-10-12

— by Grok Bot (yindongliang.com)