maplibre-tile-sources

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MapLibre Tile Sources

MapLibre 切片数据源

MapLibre GL JS does not ship with map data. You provide a style that references sources — URLs or inline data that MapLibre fetches and renders. MapLibre works equally well for a store locator with 200 addresses, a city transit map, and a global basemap — the right source type depends on geographic scale and level of detail, update frequency, infrastructure constraints, and use case.

MapLibre GL JS 本身不附带地图数据。你需要提供引用了数据源的样式——即MapLibre会获取并渲染的URL或者内联数据。MapLibre 可以很好地支持包含200个地址的店铺定位器、城市公共交通地图、全球底图等各种场景，合适的数据源类型取决于地理范围、细节层级、更新频率、基础设施限制和具体使用场景。

When to Use This Skill

适用场景

Setting up a new MapLibre map and choosing where your data comes from
Deciding between GeoJSON, serverless tiles, hosted services, a combination thereof, or self-hosted options
Configuring glyphs (fonts) and sprites so labels and icons render
Debugging blank maps or missing tiles
Migrating from Mapbox and need equivalent tile sources and style setup

搭建新的MapLibre地图，选择数据源方案
在GeoJSON、无服务器切片、托管服务、组合方案或自托管选项之间做决策
配置字形（字体）和精灵图，保证标签和图标正常渲染
调试空白地图或者缺失切片的问题
从Mapbox迁移，需要对等的切片数据源和样式配置

How styles and sources work

样式与数据源的工作原理

A style (a style JSON, style document, or style object) is the configuration you pass to MapLibre. It contains the specific rendering rules governed by the MapLibre Style Specification, maintained with parity for MapLibre GL JS and MapLibre Native.

You can use a style URL from a provider — that URL references a style with sources, layers, glyphs, and sprite. Or you can build your own style and configure each yourself.

A style has three main components:

Sources — Point to the actual data. Each source has a
```
type
```
and either inline data or a URL. MapLibre requests tiles or data as the viewport changes. The same source can back many layers (e.g. roads, water, and labels all from one vector URL).
Layers — An ordered list defining what to draw and how. Each layer references a source (and for vector tiles, a
```
source-layer
```
name) and specifies paint/layout properties.
Glyphs and sprite — Required for text and icons: URLs to font SDF stacks and icon spritesheets. Without them, labels and symbols won't appear.

Source types:

Type	Description
`vector`	Vector tiles — binary-encoded geometry and attributes; the primary format for basemaps and data overlays
`raster`	Raster tile imagery — satellite photos, WMS/WMTS layers
`raster-dem`	Elevation tiles — for terrain rendering and hillshading
`geojson`	GeoJSON data — inline object or URL; no tile server needed
`image`	A single georeferenced image — scanned maps, annotated overlays
`video`	Georeferenced video

vector

and

raster

are the most common for basemaps and data overlays.

geojson

is ideal for small datasets or interactive data that doesn't need tiling.

raster-dem

is used for terrain and hillshade effects, as well as emerging use cases in scientific visualization.

image

and

video

sources are the least common, but let you georeference static images (such as a scanned map, chart, or overlay) or georeferenced videos as map layers.

样式（样式JSON、样式文档或样式对象）是你传递给MapLibre的配置，它包含符合MapLibre 样式规范的具体渲染规则，该规范对MapLibre GL JS和MapLibre Native保持兼容。

你可以使用服务商提供的样式URL：该URL指向的样式已经包含数据源、图层、字形和精灵图。你也可以自行构建样式，逐个配置相关项。

样式包含三个核心组件：

数据源：指向实际的地图数据。每个数据源都有
```
type
```
属性，以及内联数据或对应的URL。MapLibre会随着视口变化请求切片或数据。同一个数据源可以支持多个图层（例如道路、水系、标签都可以来自同一个矢量切片URL）。
图层：有序列表，定义需要绘制的内容和绘制方式。每个图层引用一个数据源（矢量切片还需要指定
```
source-layer
```
名称），并指定绘制/布局属性。
字形和精灵图：文本和图标渲染的必需项，指向字体SDF堆栈和图标精灵图的URL。缺少这两项的话，标签和符号将无法显示。

数据源类型：

类型	说明
`vector`	矢量切片——二进制编码的几何数据和属性，是底图和数据叠加层的主流格式
`raster`	栅格切片影像——卫星照片、WMS/WMTS图层
`raster-dem`	高程切片——用于地形渲染和晕渲图生成
`geojson`	GeoJSON数据——内联对象或URL，无需切片服务器
`image`	单张地理配准图像——扫描地图、标注叠加层
`video`	地理配准视频

vector

和

raster

是底图和数据叠加层最常用的类型。

geojson

非常适合小型数据集或者不需要切片的交互数据。

raster-dem

用于地形和晕渲效果，以及新兴的科学可视化场景。

image

和

video

数据源使用频率最低，但可以让你将静态图像（例如扫描地图、图表、叠加层）或地理配准视频作为地图图层使用。

GeoJSON and Direct Data Sources

GeoJSON与直接数据源

For many use cases you don't need a tile service. MapLibre can render points, lines, or polygons directly from an inline GeoJSON object or a URL to a GeoJSON file. The entire dataset is downloaded and parsed in the browser; MapLibre handles rendering client-side.

javascript

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 }
});

很多场景下你不需要切片服务。MapLibre可以直接通过内联GeoJSON对象或者GeoJSON文件的URL渲染点、线、多边形。整个数据集会在浏览器中下载并解析，由MapLibre在客户端完成渲染。

javascript

map.addSource('my-data', {
  type: 'geojson',
  data: '/path/to/data.geojson' // 也可以是内联GeoJSON对象
});
map.addLayer({
  id: 'my-layer',
  type: 'fill',
  source: 'my-data',
  paint: { 'fill-color': '#0080ff', 'fill-opacity': 0.5 }
});

GeoJSON performance thresholds

GeoJSON性能阈值

GeoJSON downloads the entire file on every load. This works well at small scale and degrades predictably:

Range	File size / feature count	Behavior
Sweet spot	< 2 MB / < 5,000 features	Instantaneous loading, smooth interaction
Lag zone	5–20 MB / up to ~50,000 features	1–3s parse delay; mobile may struggle; optimize by simplifying geometries and reducing coordinate precision
Crash zone	> 50 MB / > 100,000 features	High risk of browser freeze or crash; switch to vector tiles

GeoJSON is lossless (exact coordinates preserved) and gives you full client-side access to feature properties — ideal for interactive data, dynamic updates, and datasets where you need to query or modify features without a server round-trip.

If your dataset exceeds these thresholds, or if you need zoom-dependent rendering (less detail at lower zoom levels), consider vector tiles instead.

GeoJSON会在每次加载时下载完整文件，在小体量下表现良好，性能下降的规律非常明确：

区间	文件大小/要素数量	表现
最佳区间	< 2 MB / < 5,000 个要素	加载即时，交互流畅
延迟区间	5–20 MB / 最多约50,000 个要素	1–3秒解析延迟；移动端可能运行吃力；可以通过简化几何结构、降低坐标精度优化
崩溃区间	> 50 MB / > 100,000 个要素	浏览器冻结或崩溃风险高；建议切换为矢量切片

GeoJSON是无损的（保留精确坐标），你可以在客户端完整访问要素属性，非常适合交互数据、动态更新，以及不需要服务端往返就能查询或修改要素的数据集。

如果你的数据集超过上述阈值，或者需要按缩放层级渲染（低缩放层级下展示更少细节），可以考虑改用矢量切片。

Other formats and the cloud-native ecosystem

其他格式与云原生生态

The choice of data source is shaped by more than performance: data type, update frequency, access patterns, and the broader geospatial ecosystem all factor in. Many formats (FlatGeobuf, GeoParquet, Cloud-Optimized GeoTIFF, KML, GPX, and more) can be displayed in MapLibre via plugins and custom protocols. The cloud-native geospatial ecosystem — formats designed for HTTP range requests and distributed storage — is evolving rapidly and increasingly relevant for web maps. A separate skill will cover this in depth; for now, see the Map Rendering Plugins and Utility Libraries sections of awesome-maplibre.

数据源的选择不仅仅受性能影响：数据类型、更新频率、访问模式、更广泛的地理空间生态都是考量因素。很多格式（FlatGeobuf、GeoParquet、云优化GeoTIFF、KML、GPX等）都可以通过插件和自定义协议在MapLibre中展示。云原生地理空间生态——专为HTTP范围请求和分布式存储设计的格式——正在快速发展，和Web地图的相关性越来越高。我们会在单独的指南中深入介绍这部分内容，目前可以参考awesome-maplibre的地图渲染插件和工具库部分。

When You Need Tiles

何时需要使用切片

Vector tiles load only the data visible in the current viewport, in a compact binary format. Use them when:

Your dataset exceeds GeoJSON's practical limits
You need zoom-dependent rendering (different levels of detail at different zoom levels)
You need global or regional reference layers, such as land and water, roads, place names, etc. (i.e., basemap data)
Bandwidth efficiency matters at scale

矢量切片仅加载当前视口内可见的数据，采用紧凑的二进制格式。适合以下场景：

你的数据集超过了GeoJSON的实际适用上限
需要按缩放层级渲染（不同缩放层级展示不同细节程度）
需要全球或区域参考图层，例如陆地水系、道路、地名等（即底图数据）
大规模场景下需要控制带宽效率

Vector tiles vs. raster tiles

矢量切片 vs 栅格切片

When you need tiles, you'll choose between two tile types:

Vector tiles encode geometry and feature attributes as compact binary data (Mapbox Vector Tile format, or the newer MapLibre Tile / MLT). MapLibre renders and styles them client-side:

Styles can be changed without regenerating tiles
Features are queryable (click, hover interactions)
Text renders crisply at any zoom or screen density
Significantly smaller file sizes than equivalent raster tiles

Raster tiles are pre-rendered images (PNG, JPEG, or WebP) at each zoom level, displayed by MapLibre as-is:

No client-side styling or feature querying
Larger file sizes, but simpler to generate and serve
Good fit for satellite/aerial imagery, WMS/WMTS integration, or rendered styles that don't need client-side customization

Most MapLibre workflows use vector tiles; increasing numbers are integrating

raster-dem

sources e.g. for terrain rendering. Use raster tiles when you need satellite/aerial imagery, when integrating with existing WMS or WMTS services, or when you need a pre-rendered cartographic style.

需要使用切片时，你可以在两种切片类型中选择：

矢量切片将几何结构和要素属性编码为紧凑的二进制数据（Mapbox矢量切片格式，或者更新的MapLibre Tile / MLT），由MapLibre在客户端渲染和设置样式：

无需重新生成切片即可修改样式
要素可查询（点击、悬停交互）
任何缩放比例或屏幕密度下文字渲染都清晰
文件大小远小于同等的栅格切片

栅格切片是每个缩放层级下预渲染的图像（PNG、JPEG或WebP），MapLibre直接原样展示：

不支持客户端样式设置或要素查询
文件更大，但生成和服务更简单
适合卫星/航空影像、WMS/WMTS集成，或者不需要客户端自定义的预渲染样式

大多数MapLibre工作流使用矢量切片；越来越多的项目集成

raster-dem

数据源，例如用于地形渲染。当你需要卫星/航空影像、集成现有WMS或WMTS服务，或者需要预渲染的制图样式时，可以使用栅格切片。

Using MapLibre with Leaflet

搭配Leaflet使用MapLibre

Leaflet is a widely used JavaScript mapping library that supports only raster tiles. If your app is built on Leaflet, MapLibre GL Leaflet lets you pre-render a MapLibre GL compatible style as a raster layer — allowing you to use hosted vector tile sources in your Leaflet app.

Leaflet是广泛使用的JavaScript地图库，仅支持栅格切片。如果你的应用基于Leaflet搭建，MapLibre GL Leaflet可以将兼容MapLibre GL的样式预渲染为栅格图层，让你可以在Leaflet应用中使用托管的矢量切片数据源。

Combining source types

组合数据源类型

A MapLibre style can have any number of sources of any types simultaneously. Layers from different sources are composited in draw order. This makes it natural to mix sources for different purposes.

Sources can be composited in a custom style sheet or at run-time. Be aware that layer order matters: layers are drawn bottom-to-top in the order they appear in the style. A raster layer added after vector layers will obscure them.

Vector basemap + GeoJSON overlay — the most common pattern. Use a provider's style URL (or any vector tile source) as your basemap and add your own data on top with
```
map.addSource()
```
and
```
map.addLayer()
```
. To keep labels readable, insert your layer before the first symbol layer rather than appending to the top of the stack.

javascript

// Start with any basemap style URL, then add your own data below labels
map.on('load', () => {
  // Find the first symbol (label) layer to insert below
  const firstSymbolId = map.getStyle().layers.find((l) => l.type === 'symbol')?.id;

  map.addSource('my-data', { type: 'geojson', data: '/path/to/data.geojson' });
  map.addLayer(
    { id: 'my-layer', type: 'circle', source: 'my-data' },
    firstSymbolId // insert before labels; omit to append above everything
  );
});

Raster imagery + vector labels — add a raster source for satellite imagery, weather radar, historical imagery, heatmaps rendered server-side, or any imagery that isn't available as vector data. Add a vector source for roads, place names and other labels. This gives crisp imagery with crisp, resolution-independent vector geometries and labels on top.
Vector basemap + raster-dem terrain — add hillshading or 3D terrain to any vector basemap using a
```
raster-dem
```
source (elevation tiles). This is how MapLibre renders terrain and hillshade without a separate basemap style.

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

数据源可以在自定义样式表中合成，也可以在运行时合成。请注意图层顺序很重要：图层按照样式中的顺序从下到上绘制，矢量图层之后添加的栅格图层会遮挡下方的内容。

矢量底图 + GeoJSON叠加层——最常见的模式。使用服务商的样式URL（或任意矢量切片数据源）作为底图，通过
```
map.addSource()
```
和
```
map.addLayer()
```
在顶部添加自有数据。为了保证标签可读性，可以将你的图层插入到第一个符号图层之前，而不是添加到图层栈的最顶部。

javascript

// 从任意底图样式URL开始，在标签下方添加你的自有数据
map.on('load', () => {
  // 找到第一个符号（标签）图层，插入到它下方
  const firstSymbolId = map.getStyle().layers.find((l) => l.type === 'symbol')?.id;

  map.addSource('my-data', { type: 'geojson', data: '/path/to/data.geojson' });
  map.addLayer(
    { id: 'my-layer', type: 'circle', source: 'my-data' },
    firstSymbolId // 插入到标签前；省略该参数则会添加到所有内容上方
  );
});

栅格影像 + 矢量标签——添加栅格数据源用于卫星影像、气象雷达、历史影像、服务端渲染的热力图，或者任何没有矢量版本的影像。再添加矢量数据源提供道路、地名和其他标签。这种模式可以同时得到清晰的影像和清晰的、分辨率无关的矢量几何结构与上层标签。
矢量底图 + raster-dem地形——使用
```
raster-dem
```
数据源（高程切片）为任意矢量底图添加晕渲效果或3D地形，这就是MapLibre不需要单独底图样式就能渲染地形和晕渲效果的实现方式。

Hosting Tile Sources

托管切片数据源

"Hosting" tile data can mean two different things:

Storing files on the web — A
```
.pmtiles
```
archive (or pre-generated tile directory) lives on static storage like S3, R2, or GitHub Pages. No server process runs; MapLibre fetches tiles over HTTP using range requests or standard HTTP. Updates require regenerating and re-uploading the file.
Running a tile server — A server process handles tile requests dynamically, often from a database (PostGIS) or source file (MBTiles, PMTiles). Supports live data and on-the-fly generation, but requires deployment and ongoing maintenance.

The three options below map to these two approaches: PMTiles is file-based and serverless; hosted tile services run tile server infrastructure on your behalf; self-hosted means you run your own server.

“托管”切片数据有两种不同的含义：

在Web上存储文件：
```
.pmtiles
```
归档文件（或预生成的切片目录）存放在S3、R2、GitHub Pages等静态存储上，不需要运行服务进程，MapLibre通过范围请求或标准HTTP获取切片，更新时需要重新生成并重新上传文件。
运行切片服务器：服务进程动态处理切片请求，通常从数据库（PostGIS）或源文件（MBTiles、PMTiles）读取数据，支持实时数据和动态生成，但需要部署和持续维护。

下面的三个选项对应这两种方案：PMTiles是基于文件的无服务器方案；托管切片服务替你运行切片服务器基础设施；自托管则是你自己运行服务器。

Serverless (PMTiles)

无服务器（PMTiles）

PMTiles is an open single-file tile format that supports vector or raster tiles — MapLibre fetches only the byte ranges it needs via HTTP range requests, with no tile server. Extract only the geographic scale you need, and host a

.pmtiles

file on static storage (S3, R2, GitHub Pages).

See maplibre-pmtiles-patterns for setup.

PMTiles是开源的单文件切片格式，支持矢量或栅格切片——MapLibre通过HTTP范围请求仅获取需要的字节范围，不需要切片服务器。你可以只提取需要的地理范围，将

.pmtiles

文件托管在静态存储（S3、R2、GitHub Pages）上。

配置方法参考maplibre-pmtiles-patterns。

Hosted tile services

托管切片服务

Many providers offer hosted vector or raster tiles and pre-built style and tile URLs — no server to run. See Map/Tile Providers in awesome-maplibre for a full list.

✅ Global CDN; pre-built styles available
✅ Handles global to local scale
⚠️ Custom style layer definitions must match the schema of the hosted tile source
⚠️ Vendor dependency
⚠️ API keys required by most; check license, usage limits and pricing
⚠️ Attribution requirements vary; verify before launch

Store API keys in environment variables; never commit to source control.

很多服务商提供托管的矢量或栅格切片，以及预构建的样式和切片URL——不需要你运行服务器。完整列表参考awesome-maplibre的地图/切片服务商部分。

✅ 全球CDN；提供预构建样式
✅ 支持从全球到本地的各种尺度
⚠️ 自定义样式图层定义必须匹配托管切片数据源的schema
⚠️ 依赖服务商
⚠️ 大多数需要API密钥；请检查许可、使用限制和定价
⚠️ 署名要求各有不同；上线前请核实

请将API密钥存放在环境变量中；绝对不要提交到版本控制。

Self-hosted tile server

自托管切片服务器

Run your own server for full control over data, cost, and deployment. See Tile Servers in awesome-maplibre for options, including the MapLibre-maintained 💙 Martin. Use an existing tile schema or generate custom tiles with Planetiler or tippecanoe.

✅ Full control; no per-request cost at scale
✅ Can serve dynamic data and convert to tiles on the fly
✅ Supports air-gapped deployments
⚠️ Data to process, and infrastructure to deploy and maintain
⚠️ You must configure CORS and supply glyphs and sprite in your style

运行自己的服务器可以完全控制数据、成本和部署。可选方案参考awesome-maplibre的切片服务器部分，包括MapLibre官方维护的💙 Martin。你可以使用现有切片schema，或者通过Planetiler或tippecanoe生成自定义切片。

✅ 完全可控；大规模使用没有按请求计费的成本
✅ 可以服务动态数据，动态转换为切片
✅ 支持离线部署
⚠️ 需要处理数据，部署和维护基础设施
⚠️ 你必须配置CORS，在样式中提供字形和精灵图

Custom styles

自定义样式

A custom style is one you write yourself, rather than using a provider's pre-built style URL. Custom styles can reference either hosted or self-hosted tile sources — and in practice, the most common pattern is both:

Hosted tile sources — Your style JSON points to a provider's tile URL. You control visual appearance while relying on the provider for tile delivery. Your layer definitions must match the provider's tile schema, and you typically reuse their glyphs and sprite.
Self-hosted tile sources — Your style JSON points to your own tile server or PMTiles file. You control both style and data, but must supply glyphs and sprite yourself (or reuse publicly available ones that match your tile schema).

The most common real-world pattern is a hybrid: a custom style that references a hosted provider's basemap tiles — and often reuses their glyphs and sprite — while adding self-hosted tile sources or GeoJSON overlays for your own data. This gives you full control over your data layers without building basemap tile infrastructure from scratch.

自定义样式是指你自行编写的样式，而不是使用服务商提供的预构建样式URL。自定义样式可以引用托管或自托管的切片数据源——实际场景中最常见的是两者混合使用：

托管切片数据源：你的样式JSON指向服务商的切片URL，你控制视觉表现，同时依赖服务商提供切片分发服务。你的图层定义必须匹配服务商的切片schema，通常也会复用他们的字形和精灵图。
自托管切片数据源：你的样式JSON指向你自己的切片服务器或PMTiles文件，你同时控制样式和数据，但需要自行提供字形和精灵图（或者复用符合你的切片schema的公开资源）。

最常见的实际场景是混合模式：自定义样式引用托管服务商的底图切片——通常也会复用他们的字形和精灵图——同时添加自托管的切片数据源或GeoJSON叠加层来展示自有数据。这种模式让你可以完全控制自己的数据图层，不需要从零搭建底图切片基础设施。

Pre-Defined Tile Schemas

预定义切片Schema

When building a custom style (rather than using a provider's pre-built style URL), you need to know the tile schema — the source-layer names and their properties. Your style's layer definitions must match the schema of your tile source.

Common schemas:

OpenMapTiles — the most widely adopted schema, based on OpenStreetMap data. Rich and detailed, with source-layers like
```
transportation
```
,
```
water
```
,
```
landuse
```
,
```
poi
```
. The largest ecosystem of community styles targets this schema.
Shortbread — an open standard designed to be minimal and interoperable, not tied to any single vendor. Simpler structure than OpenMapTiles; a clean foundation if you're building styles from scratch.
Protomaps — purpose-built for the Protomaps PMTiles basemap ecosystem. Flat, simple structure with source-layers like
```
land
```
,
```
water
```
,
```
roads
```
,
```
places
```
; optimized for serverless delivery.

If you use a provider's pre-built style URL, the schema is already matched.

构建自定义样式（而非使用服务商的预构建样式URL）时，你需要了解切片schema——即source-layer名称及其属性。你的样式图层定义必须匹配切片数据源的schema。

常见schema：

OpenMapTiles：应用最广泛的schema，基于OpenStreetMap数据，内容丰富详细，包含
```
transportation
```
、
```
water
```
、
```
landuse
```
、
```
poi
```
等source-layer，社区样式生态最完善。
Shortbread：开放标准，设计理念是轻量、可互操作，不绑定任何单一服务商，结构比OpenMapTiles简单，适合从零构建样式的场景。
Protomaps：专为Protomaps PMTiles底图生态设计，结构扁平简单，包含
```
land
```
、
```
water
```
、
```
roads
```
、
```
places
```
等source-layer，针对无服务器分发做了优化。

如果你使用服务商的预构建样式URL，schema已经自动匹配。

Glyphs (Fonts) and Sprites

字形（字体）和精灵图

Every MapLibre style that shows text or icons needs:

glyphs: URL template for font stacks —

"glyphs": "https://example.com/fonts/{fontstack}/{range}.pbf"

sprite: Base URL for sprite sheet and metadata (serves both
```
.json
```
and
```
.png
```
) —
```
"sprite": "https://example.com/sprites/basic"
```

Pre-built style URLs from hosted providers include their own glyphs and sprite. When building a custom style or self-hosting, you must supply these URLs.

If you are modifying a style based on a pre-defined tile schema, look for an existing style that matches that schema and reuse the glyphs and sprites. Pay attention to licensing and attribution requirements when reusing assets. If needed you can host the same glyphs and sprites yourself by downloading the files and serving them from your own storage or tile server.

The alternative is to generate your own glyphs and sprite sheets. See Font Glyph Generation and Sprite Generation in awesome-maplibre for tools to generate your own.

所有展示文本或图标的MapLibre样式都需要：

glyphs：字体堆栈的URL模板——

"glyphs": "https://example.com/fonts/{fontstack}/{range}.pbf"

sprite：精灵图和元数据的基础URL（同时提供
```
.json
```
和
```
.png
```
）——
```
"sprite": "https://example.com/sprites/basic"
```

托管服务商提供的预构建样式URL已经包含他们自己的字形和精灵图。构建自定义样式或自托管时，你需要自行提供这些URL。

如果你是基于预定义的切片schema修改样式，可以找一个匹配该schema的现有样式，复用它的字形和精灵图。复用资源时请注意许可和署名要求。如果需要，你也可以下载这些文件，存放在自己的存储或切片服务器上自行托管。

另一种选择是自行生成字形和精灵图。生成工具参考awesome-maplibre的字体字形生成和精灵图生成部分。

TileJSON

TileJSON is a standard JSON format for describing a tileset — its tile URL template, zoom range, bounds, center, attribution, and (for vector tiles) the available source-layers. Tile servers and providers expose TileJSON endpoints; MapLibre can consume them directly.

TileJSON是描述切片集的标准JSON格式，包含切片URL模板、缩放范围、边界、中心点、署名，以及（矢量切片的）可用source-layer。切片服务器和服务商提供TileJSON接口，MapLibre可以直接读取。

Referencing tiles in a source

在数据源中引用切片

Tiles are addressed by zoom (Z), column (X), and row (Y) — a universal scheme across raster and vector tile sources (see the OpenStreetMap wiki for more information). In a MapLibre source, you reference tiles either directly via a

tiles

URL template or via a

url

pointing to a TileJSON endpoint.

When a TileJSON endpoint is available, prefer

url

: MapLibre fetches the document and reads the tile URL template, zoom range, bounds, attribution, and (for vector tiles) the available source-layers automatically. Tile servers like Martin and tileserver-gl generate TileJSON endpoints for every tileset they serve, as do many hosted providers.

When no TileJSON endpoint exists — for example, a raw raster tile service that gives you a URL template directly — use the

tiles

array and specify any metadata (minzoom, maxzoom, attribution) in the source definition yourself.

tiles
array:

json

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

url
to TileJSON endpoint:

json

{
  "type": "vector",
  "url": "https://example.com/tiles.json"
}

切片通过缩放层级（Z）、列号（X）、行号（Y）寻址——这是栅格和矢量切片数据源通用的方案（更多信息参考OpenStreetMap wiki）。在MapLibre数据源中，你可以直接通过

tiles

URL模板引用切片，或者通过

url

指向TileJSON接口。

如果有TileJSON接口，优先使用

url

：MapLibre会自动获取文档，读取切片URL模板、缩放范围、边界、署名，以及（矢量切片的）可用source-layer。Martin、tileserver-gl等切片服务器会为每个托管的切片集生成TileJSON接口，很多托管服务商也提供该功能。

如果没有TileJSON接口——例如直接提供URL模板的原生栅格切片服务——可以使用

tiles

数组，自行在数据源定义中指定所有元数据（minzoom、maxzoom、署名）。

tiles
数组示例：

json

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

指向TileJSON接口的
url
示例：

json

{
  "type": "vector",
  "url": "https://example.com/tiles.json"
}

TileJSON and custom styles

TileJSON与自定义样式

For vector sources, the TileJSON

vector_layers

field lists each available

source-layer

, its attribute fields, and its zoom range. This is the authoritative reference when building a custom style: your layer definitions must reference

source-layer

names exactly as they appear here.

When generating tiles with Planetiler or tippecanoe, the output embeds TileJSON metadata in the MBTiles or PMTiles file. Tile servers like Martin read this metadata and expose it as a TileJSON endpoint automatically.

对于矢量数据源，TileJSON的

vector_layers

字段列出了每个可用的

source-layer

、它的属性字段和缩放范围。这是构建自定义样式的权威参考：你的图层定义引用的

source-layer

名称必须和这里完全一致。

使用Planetiler或tippecanoe生成切片时，输出的MBTiles或PMTiles文件会嵌入TileJSON元数据。Martin等切片服务器会自动读取这些元数据，将其作为TileJSON接口暴露。

CORS

If your tiles, glyphs, or sprites are on a different origin, the server must send CORS headers (

Access-Control-Allow-Origin

). Otherwise the browser blocks requests and the map will be blank or missing labels.

Hosted providers handle CORS for you. For self-hosted servers or static storage, configure CORS on the server or CDN.

如果你的切片、字形或精灵图位于不同的源，服务器必须发送CORS头（

Access-Control-Allow-Origin

），否则浏览器会阻止请求，地图会变为空白或者缺少标签。

托管服务商已经为你处理了CORS。对于自托管服务器或静态存储，你需要在服务器或CDN上配置CORS。

Related Skills

References

参考资料

GeoJSON performance thresholds (file size / feature count ranges) — community rules of thumb aggregated from Stack Overflow, Reddit, Medium, and Cesium Community Forum discussions. ⚑ not authoritative or canonical
PMTiles format and HTTP range request protocol — docs.protomaps.com/pmtiles/
Protomaps (pre-built PMTiles basemaps) — protomaps.com
Planetiler (generate vector tiles from OSM) — GitHub
tippecanoe (generate vector tiles from GeoJSON) — github.com/felt/tippecanoe
Martin tile server — maplibre.org/martin/
MapLibre Tile (MLT) specification — maplibre.org/maplibre-tile-spec/
OpenMapTiles schema — OpenMapTiles.org
Shortbread tile schema — shortbread-tiles.org
Leaflet — leaflet.js
MapLibre GL Leaflet — github.com/maplibre/maplibre-gl-leaflet
Cloud-native geospatial formats: FlatGeobuf (flatgeobuf.org), GeoParquet (GeoParquet), Cloud-Optimized GeoTIFF (COG website)
awesome-maplibre — github.com/maplibre/awesome-maplibre

GeoJSON性能阈值（文件大小/要素数量区间）——汇总自Stack Overflow、Reddit、Medium和Cesium社区论坛的社区经验法则 ⚑ 非官方权威标准
PMTiles格式与HTTP范围请求协议——docs.protomaps.com/pmtiles/
Protomaps（预构建PMTiles底图）——protomaps.com
Planetiler（从OSM生成矢量切片）——GitHub
tippecanoe（从GeoJSON生成矢量切片）——github.com/felt/tippecanoe
Martin切片服务器——maplibre.org/martin/
MapLibre Tile (MLT) 规范——maplibre.org/maplibre-tile-spec/
OpenMapTiles schema——OpenMapTiles.org
Shortbread切片schema——shortbread-tiles.org
Leaflet——leaflet.js
MapLibre GL Leaflet——github.com/maplibre/maplibre-gl-leaflet
云原生地理空间格式: FlatGeobuf (flatgeobuf.org), GeoParquet (GeoParquet), 云优化GeoTIFF (COG website)
awesome-maplibre——github.com/maplibre/awesome-maplibre

maplibre-tile-sources

Original

Translation

MapLibre Tile Sources

MapLibre 切片数据源

When to Use This Skill

适用场景

How styles and sources work

样式与数据源的工作原理

GeoJSON and Direct Data Sources

GeoJSON与直接数据源

GeoJSON performance thresholds

GeoJSON性能阈值

Other formats and the cloud-native ecosystem

其他格式与云原生生态

When You Need Tiles

何时需要使用切片

Vector tiles vs. raster tiles

矢量切片 vs 栅格切片

Using MapLibre with Leaflet

搭配Leaflet使用MapLibre

Combining source types

组合数据源类型

Hosting Tile Sources

托管切片数据源

Serverless (PMTiles)

无服务器（PMTiles）

Hosted tile services

托管切片服务

Self-hosted tile server

自托管切片服务器

Custom styles

自定义样式

Pre-Defined Tile Schemas

预定义切片Schema

Glyphs (Fonts) and Sprites

字形（字体）和精灵图

TileJSON

TileJSON

Referencing tiles in a source

在数据源中引用切片

TileJSON and custom styles

TileJSON与自定义样式

CORS

CORS

Related Skills

相关指南

References

参考资料