maplibre-tile-sources

MapLibre 瓦片源

MapLibre GL JS 不自带地图数据。你需要提供一个 样式，其中引用了 数据源——MapLibre 会获取并渲染这些 URL 或内联数据。无论是包含 200 个地址的商家定位地图、城市公交地图，还是全球底图，MapLibre 都能很好地胜任。合适的数据源类型取决于地理范围和详细程度、更新频率、基础设施限制以及使用场景。

本技能介绍如何 选择 数据源类型。要了解如何配置数据源并使其渲染，请参阅 maplibre-source-wiring。

何时使用本技能

• 设置新的 MapLibre 地图，并选择数据来源
• 为特定大小的数据集决定使用 GeoJSON 还是瓦片
• 判断是否需要瓦片基础设施
• 规划底图与自有数据的组合方式

样式和数据源的工作原理

样式（样式 JSON、样式文档或样式对象）是传递给 MapLibre 的配置。它包含由 MapLibre 样式规范定义的具体渲染规则；该规范为 MapLibre GL JS 和 MapLibre Native 维护了相同的功能支持。

你可以使用提供商提供的 样式 URL——该 URL 引用一个包含数据源、图层、字形和精灵图的样式。你也可以 自行构建样式，并分别配置这些内容。

样式有三个主要组成部分：

• 数据源 — 指向实际数据。每个数据源都有一个 type，并包含内联数据或 URL。视口变化时，MapLibre 会请求瓦片或数据。同一个数据源可以供多个图层使用（例如，道路、水域和标签都来自同一个矢量 URL）。
• 图层 — 定义绘制内容及方式的有序列表。每个图层都引用一个数据源（对于矢量瓦片，还会引用一个 source-layer 名称），并指定 paint/layout 属性。
• 字形和精灵图 — 指向字体 SDF 字体集和图标精灵图的 URL。sprite 没有回退机制：缺失的图标会被省略，控制台会发出 Image "<id>" could not be loaded 警告；使用 map.hasImage(id) 检查是否定义了图标 ID。glyphs 则在 GL JS ≥ 5.11.0 中提供一种回退机制（文本仍会使用本地或系统字体渲染）——机制及其限制请参阅 maplibre-fonts-glyphs。生产环境中的样式仍应显式提供这两项。

数据源类型：

类型	描述
vector	矢量瓦片 — 二进制编码的几何数据和属性；底图和数据叠加层的主要格式
raster	栅格瓦片图像 — 卫星照片、WMS/WMTS 图层
raster-dem	高程瓦片 — 用于地形渲染和晕渲
geojson	GeoJSON 数据 — 内联对象或 URL；无需瓦片服务端
image	单张地理配准图像 — 扫描地图、带注释的叠加层
video	地理配准视频

vector 和 raster 是底图和数据叠加层中最常见的类型。geojson 适用于小型数据集或无需切片的交互式数据。raster-dem 用于地形和晕渲效果，也适用于科学可视化等新兴场景。image 和 video 数据源最不常见，但可将静态图像（例如扫描地图、图表或叠加层）或地理配准视频定位到地图上，作为地图图层使用。

GeoJSON 和直接数据源

许多使用场景并不需要瓦片服务。MapLibre 可以直接从内嵌的 GeoJSON 对象或 GeoJSON 文件的 URL 渲染点、线或多边形。浏览器会下载并解析整个数据集；MapLibre 在客户端处理渲染。

map.addSource('my-data', {
  type: 'geojson',
  data: '/path/to/data.geojson' // or an inline GeoJSON object
});
map.addLayer({
  id: 'my-layer',
  type: 'fill',
  source: 'my-data',
  paint: { 'fill-color': '#0080ff', 'fill-opacity': 0.5 }
});

GeoJSON 性能阈值

每次加载时，GeoJSON 都会下载整个文件。这在小规模数据下效果良好，数据量增大时性能会有规律地下降：

范围	文件大小 / 要素数量	表现
最佳区间	< 2 MB / < 5,000 个要素	加载迅速，交互流畅
卡顿区	5–20 MB / 最多约 50,000 个要素	解析延迟 1–3 秒；移动设备可能运行吃力；可通过简化几何图形和降低坐标精度进行优化
崩溃区	> 50 MB / > 100,000 个要素	浏览器极易冻结或崩溃；请改用矢量瓦片

GeoJSON 是无损的（精确保留坐标），并允许你在客户端完整访问要素属性，适用于交互式数据、动态更新，以及无需与服务端往返即可查询或修改要素的数据集。

如果数据集超出这些阈值，或者需要根据缩放级别调整渲染效果（较低缩放级别下减少细节），请考虑改用矢量瓦片。

其他格式与云原生生态

数据源的选择不只取决于性能：数据类型、更新频率、访问模式以及更广泛的地理空间生态也都会产生影响。许多格式（FlatGeobuf、GeoParquet、Cloud-Optimized GeoTIFF、KML、GPX 等）都可以通过插件和自定义协议在 MapLibre 中显示。云原生地理空间生态——即专为 HTTP 范围请求和分布式存储设计的格式——正在快速发展，对 Web 地图也日益重要。请参阅 awesome-maplibre 中的 地图渲染插件 和 实用工具库 部分。

何时需要瓦片

矢量瓦片只会以紧凑的二进制格式加载当前视口中可见的数据。以下情况适合使用矢量瓦片：

• 数据集超出 GeoJSON 的实用范围
• 需要根据缩放级别调整渲染效果（不同缩放级别显示不同的细节层次）
• 需要全球或区域参考图层，例如陆地和水域、道路、地名等（即底图数据）
• 大规模应用需要提高带宽效率

矢量瓦片与栅格瓦片

需要瓦片时，可以选择两种瓦片类型：

矢量瓦片将几何图形和要素属性编码为紧凑的二进制数据（Mapbox Vector Tile 格式，或较新的 MapLibre Tile / MLT）。MapLibre 在客户端渲染并设置其样式：

• 无需重新生成瓦片即可更改样式
• 可查询要素（点击、悬停交互）
• 文本在任何缩放级别或屏幕密度下都清晰锐利
• 与同等栅格瓦片相比，文件体积显著更小

栅格瓦片是在每个缩放级别预先渲染的图像（PNG、JPEG 或 WebP），MapLibre 会直接显示这些图像：

• 不支持客户端设置样式或查询要素
• 文件体积较大，但生成和提供服务更简单
• 适用于卫星／航空影像、WMS／WMTS 集成，或无需客户端自定义的已渲染样式

大多数 MapLibre 工作流使用矢量瓦片；越来越多的工作流也会集成 raster-dem 数据源，例如用于地形渲染。需要卫星／航空影像、与现有 WMS 或 WMTS 服务集成，或使用预渲染的制图样式时，请使用栅格瓦片。

在 Leaflet 中使用 MapLibre

Leaflet 是广泛使用的 JavaScript 制图库，其核心功能仅绘制栅格瓦片。如果你的应用基于 Leaflet 构建，MapLibre GL Leaflet 可以将实时 MapLibre GL JS 地图作为 Leaflet 图层添加到其中，让应用从托管的矢量瓦片数据源绘制矢量样式。

组合数据源类型

MapLibre 样式可以同时包含任意数量、任意类型的数据源。不同数据源的图层会按绘制顺序合成，因此可以自然地混合使用不同用途的数据源。

• 矢量底图 + GeoJSON 覆盖层 — 最常见的模式。将服务提供商的样式 URL（或任意矢量瓦片数据源）用作底图，并在其上添加自己的数据。为确保标签清晰可读，请将图层插入第一个符号图层之前，而不是追加到图层堆栈顶部（参见 maplibre-source-wiring）。
• 栅格影像 + 矢量标签 — 添加栅格数据源以显示卫星影像、天气雷达、历史影像、服务端渲染的热力图，或任何无法作为矢量数据使用的影像。添加矢量数据源以显示道路、地名和其他标签。这样既能获得清晰的影像，也能在其上叠加清晰且分辨率无关的矢量几何图形和标签。
• 矢量底图 + raster-dem 地形 — 使用 raster-dem 数据源（高程瓦片）为任意矢量底图添加山体阴影或 3D 地形。这是 MapLibre 在无需单独底图样式的情况下渲染地形和山体阴影的方式。

何时选择每种方案

大多数实际应用会结合多种数据源——使用托管底图作为参考图层，并将自己的数据作为单独的数据源。你很少需要仅仅为了自己的数据而构建自定义瓦片管线。

场景	建议的数据源设置
< ~5,000 个要素，需要点击/悬停交互或实时更新	GeoJSON — 无需瓦片服务
5,000–100,000 个要素	如果可以简化数据并接受 1–3s 的加载延迟，则使用 GeoJSON；否则使用矢量瓦片
> 100,000 个要素或 > 50 MB	矢量瓦片 — 使用 tippecanoe 或 Planetiler 生成
街道、地形或地点底图	托管瓦片服务（OpenFreeMap、MapTiler）或可自托管服务（Martin）
任何底图上的自有数据	托管底图样式 URL + 作为单独 GeoJSON 或矢量瓦片数据源的自有数据
卫星/航拍影像 + 标签	影像使用栅格瓦片数据源 + 道路和标签使用矢量数据源

关键区别在于：底图和你的数据几乎总是独立的数据源，即使两者都是矢量瓦片也是如此。底图提供上下文；你的数据源提供应用的数据。

当有人询问如何将自己的数据合并到底图瓦片集中时

这类请求通常有一个熟悉的说法："我想把道路、水域、标签和自己的多边形放进同一个瓦片集，这样地图只需请求一个数据源——管线该怎么搭？" 问题的前提本身就有问题，按用户的问法作答，会让用户构建一个之后还得拆掉的东西。不要写出构建步骤。指出能实现这一目标的工具（tippecanoe、Planetiler），并提供它们的文档链接，但要等到确实符合下面所述的例外情况时再这样做。

先纠正前提。“一个数据源”并不是性能优化。样式的 sources 是一个对象，可以包含任意数量的命名数据源（样式规范）；MapLibre 会并发请求这些数据源的瓦片，而且每个数据源都不会带来额外的渲染开销。已发布的底图样式本身通常就会声明多个数据源。用户优化的是一个实际上不会造成任何成本的东西。

然后说明合并实际带来的代价，因为光说一句“你不需要这么做”通常无法打消请求：

• 自有数据每次有变动，都意味着必须重新生成整个合并瓦片集，包括底图在内——要构建整个星球或区域范围的数据提取文件，只为了发布几十个多边形的编辑。
• 你将无法再更换或升级底图，因为底图已经被固化其中。
• 作为衍生数据的再分发者，你要承担底图的署名和许可义务，而不是使用带有这些信息的托管样式。

**改为介绍双数据源模式：**使用托管底图样式 URL 或矢量数据源，再将配送区域（或用户自己的其他数据）作为同一地图样式中的独立 geojson 或 vector 数据源。这是标准做法，也正是用户真正想要的。

只有一种特殊情况可以合理地使用单一合并瓦片集：必须在没有网络且没有第二个文件的情况下渲染的自包含制品——例如作为一个归档文件交付的离线或隔离网络部署。其他情况都不符合。 “我想自托管自己的瓦片”、信息亭的打包体积、演示和概念验证，都仍然适合使用两个数据源，而且构建成本更低。

相关技能

• maplibre-fonts-glyphs — 设置 glyphs URL、自托管或生成字体 PBF，以及支持非拉丁文字脚本。
• maplibre-sprites-icons — sprite URL 的形式、加载多个图集、自托管精灵图资源，以及路线盾牌。
• maplibre-source-wiring — TileJSON、source-layer、图层顺序、CORS，以及空白地图问题排查。
• maplibre-pmtiles-patterns — 无服务器 PMTiles 托管和 MapLibre 集成。
• maplibre-mapbox-migration — 将 Mapbox 瓦片替换为兼容 MapLibre 的数据源。

参考资料

1. GeoJSON 性能阈值（文件大小／要素数量范围）——汇总自 Stack Overflow、Reddit、Medium 和 Cesium Community Forum 讨论的社区经验法则。⚑ 并非权威或规范标准
2. MapLibre 样式规范 — maplibre.org/maplibre-style-spec/
3. MapLibre Tile（MLT）规范 — maplibre.org/maplibre-tile-spec/
4. Planetiler（从 OSM 生成矢量瓦片）— GitHub
5. tippecanoe（从 GeoJSON 生成矢量瓦片）— github.com/felt/tippecanoe
6. Leaflet — leaflet.js
7. MapLibre GL Leaflet — github.com/maplibre/maplibre-gl-leaflet
8. 云原生地理空间格式：FlatGeobuf（flatgeobuf.org）、GeoParquet（GeoParquet）、云优化 GeoTIFF（COG 网站）
9. awesome-maplibre — github.com/maplibre/awesome-maplibre

---

此技能内容为快照。 如果主要来源与此内容相矛盾——包括上面的参考资料、MapLibre 当前文档，或运行 MapLibre 时的实际表现——应以该来源为准。请遵循该来源，然后报告此处的分歧，并注明来源和你的 MapLibre 版本：修改你安装的副本对其他人没有帮助，而且下次更新时会被覆盖。