重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
maplibre-tile-sources by maplibre/maplibre-agent-skills
npx skills add https://github.com/maplibre/maplibre-agent-skills --skill maplibre-tile-sourcesMapLibre GL JS 不附带地图数据。您需要提供一个引用源的样式——即 MapLibre 获取并渲染的 URL 或内联数据。MapLibre 同样适用于包含 200 个地址的商店定位器、城市交通地图和全球底图——正确的源类型取决于地理范围、细节级别、更新频率、基础设施限制和具体用例。
样式(一个样式 JSON、样式文档或样式对象)是您传递给 MapLibre 的配置。它包含由 MapLibre 样式规范 管理的特定渲染规则,该规范为 MapLibre GL JS 和 MapLibre Native 保持对等性。
您可以使用提供商的样式 URL——该 URL 引用了一个包含源、图层、字形和精灵的样式。或者,您可以构建自己的样式并自行配置每个部分。
样式有三个主要组成部分:
type 以及内联数据或一个 URL。MapLibre 在视口变化时请求瓦片或数据。同一个源可以支持多个图层(例如,道路、水域和标签都来自同一个矢量 URL)。source-layer 名称)并指定绘制/布局属性。源类型:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 类型 | 描述 |
|---|---|
vector | 矢量瓦片——二进制编码的几何图形和属性;底图和数据叠加层的主要格式 |
raster | 栅格瓦片影像——卫星照片、WMS/WMTS 图层 |
raster-dem | 高程瓦片——用于地形渲染和山体阴影 |
geojson | GeoJSON 数据——内联对象或 URL;无需瓦片服务器 |
image | 单个地理配准图像——扫描的地图、带注释的叠加层 |
video | 地理配准视频 |
vector 和 raster 是底图和数据叠加层最常用的类型。geojson 适用于不需要瓦片化的小型数据集或交互式数据。raster-dem 用于地形和山体阴影效果,以及在科学可视化中的新兴用例。image 和 video 源最不常见,但允许您将静态图像(如扫描的地图、图表或叠加层)或地理配准视频作为地图图层。
对于许多用例,您不需要瓦片服务。MapLibre 可以直接从内联的 GeoJSON 对象或指向 GeoJSON 文件的 URL 渲染点、线或多边形。整个数据集在浏览器中下载和解析;MapLibre 在客户端处理渲染。
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 在每次加载时都会下载整个文件。这在数据量较小时效果良好,性能下降是可预测的:
| 范围 | 文件大小 / 要素数量 | 行为 |
|---|---|---|
| 最佳范围 | < 2 MB / < 5,000 个要素 | 即时加载,交互流畅 |
| 延迟区 | 5–20 MB / 最多约 50,000 个要素 | 1–3 秒解析延迟;移动设备可能吃力;通过简化几何图形和降低坐标精度来优化 |
| 崩溃区 | > 50 MB / > 100,000 个要素 | 浏览器冻结或崩溃的风险很高;切换到矢量瓦片 |
GeoJSON 是无损的(保留精确坐标),并让您可以完全在客户端访问要素属性——非常适合交互式数据、动态更新以及需要查询或修改要素而无需服务器往返的数据集。
如果您的数据集超过这些阈值,或者您需要依赖缩放级别的渲染(在较低缩放级别显示较少细节),请考虑改用矢量瓦片。
数据源的选择不仅受性能影响:数据类型、更新频率、访问模式以及更广泛的地理空间生态系统都是影响因素。许多格式(FlatGeobuf、GeoParquet、云优化 GeoTIFF、KML、GPX 等)可以通过插件和自定义协议在 MapLibre 中显示。云原生地理空间生态系统——专为 HTTP 范围请求和分布式存储而设计的格式——正在迅速发展,并且与网络地图越来越相关。另一项技能将深入介绍这一点;目前,请参阅 awesome-maplibre 的 地图渲染插件 和 实用工具库 部分。
矢量瓦片仅以紧凑的二进制格式加载当前视口中可见的数据。在以下情况下使用它们:
当您需要瓦片时,您将在两种瓦片类型之间进行选择:
矢量瓦片 将几何图形和要素属性编码为紧凑的二进制数据(Mapbox Vector Tile 格式,或较新的 MapLibre Tile / MLT)。MapLibre 在客户端渲染和设置它们的样式:
栅格瓦片 是每个缩放级别预渲染的图像(PNG、JPEG 或 WebP),由 MapLibre 按原样显示:
大多数 MapLibre 工作流使用矢量瓦片;越来越多的项目正在集成 raster-dem 源,例如用于地形渲染。当您需要卫星/航空影像、与现有 WMS 或 WMTS 服务集成,或者需要预渲染的制图样式时,请使用栅格瓦片。
Leaflet 是一个广泛使用的 JavaScript 地图库,仅支持栅格瓦片。如果您的应用程序基于 Leaflet 构建,MapLibre GL Leaflet 允许您将 MapLibre GL 兼容的样式预渲染为栅格图层——从而允许您在 Leaflet 应用程序中使用托管的矢量瓦片源。
一个 MapLibre 样式可以同时拥有任意数量和任意类型的源。来自不同源的图层按照绘制顺序合成。这使得为不同目的混合源变得很自然。
源可以在自定义样式表中或在运行时合成。请注意图层顺序很重要:图层按照它们在样式中出现的顺序从下到上绘制。在矢量图层之后添加的栅格图层会遮挡它们。
map.addSource() 和 map.addLayer() 将自己的数据添加在顶部。为了保持标签的可读性,将您的图层插入到第一个符号图层之前,而不是追加到堆栈的顶部。// 从任何底图样式 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 源(高程瓦片)为任何矢量底图添加山体阴影或 3D 地形。这就是 MapLibre 渲染地形和山体阴影而无需单独底图样式的方式。“托管”瓦片数据可能意味着两件不同的事情:
.pmtiles 归档文件(或预生成的瓦片目录)存放在静态存储上,如 S3、R2 或 GitHub Pages。没有服务器进程运行;MapLibre 使用范围请求或标准 HTTP 通过 HTTP 获取瓦片。更新需要重新生成并重新上传文件。下面的三个选项对应这两种方法:PMTiles 是基于文件且无服务器的;托管瓦片服务代表您运行瓦片服务器基础设施;自托管意味着您运行自己的服务器。
PMTiles 是一种开放的单文件瓦片格式,支持矢量或栅格瓦片——MapLibre 通过 HTTP 范围请求仅获取所需的字节范围,无需瓦片服务器。仅提取您所需的地理范围,并将 .pmtiles 文件托管在静态存储(S3、R2、GitHub Pages)上。
有关设置,请参阅 maplibre-pmtiles-patterns。
许多提供商提供托管的矢量或栅格瓦片以及预构建的样式和瓦片 URL——无需运行服务器。完整列表请参阅 awesome-maplibre 中的 地图/瓦片提供商。
将 API 密钥存储在环境变量中;切勿提交到源代码控制。
运行您自己的服务器以完全控制数据、成本和部署。有关选项,请参阅 awesome-maplibre 中的 瓦片服务器,包括 MapLibre 维护的 💙 Martin。使用现有的瓦片架构或使用 Planetiler 或 tippecanoe 生成自定义瓦片。
自定义样式是您自己编写的样式,而不是使用提供商的预构建样式 URL。自定义样式可以引用托管或自托管的瓦片源——实际上,最常见的模式是两者兼有:
最常见的现实世界模式是混合模式:一个自定义样式引用托管提供商的底图瓦片——并且通常重用他们的字形和精灵——同时为您自己的数据添加自托管的瓦片源或 GeoJSON 叠加层。这使您可以完全控制自己的数据图层,而无需从头构建底图瓦片基础设施。
在构建自定义样式(而不是使用提供商的预构建样式 URL)时,您需要知道瓦片架构——源图层名称及其属性。您的样式图层定义必须与您的瓦片源的架构匹配。
常见的架构:
transportation、water、landuse、poi 等源图层。最大的社区样式生态系统以此架构为目标。land、water、roads、places 等源图层;针对无服务器交付进行了优化。如果您使用提供商的预构建样式 URL,则架构已经匹配。
每个显示文本或图标的 MapLibre 样式都需要:
"glyphs": "https://example.com/fonts/{fontstack}/{range}.pbf".json 和 .png)—— "sprite": "https://example.com/sprites/basic"来自托管提供商的预构建样式 URL 包含他们自己的字形和精灵。在构建自定义样式或自托管时,您必须提供这些 URL。
如果您正在修改基于预定义瓦片架构的样式,请寻找匹配该架构的现有样式并重用其字形和精灵。重用资源时请注意许可和归属要求。如果需要,您可以通过下载文件并从自己的存储或瓦片服务器提供服务来托管相同的字形和精灵。
TileJSON 是一种描述瓦片集的标准 JSON 格式——其瓦片 URL 模板、缩放范围、边界、中心、归属信息以及(对于矢量瓦片)可用的源图层。瓦片服务器和提供商公开 TileJSON 端点;MapLibre 可以直接使用它们。
瓦片通过缩放级别(Z)、列(X)和行(Y)来寻址——这是跨栅格和矢量瓦片源的通用方案(更多信息请参阅 OpenStreetMap 维基)。在 MapLibre 源中,您可以通过 tiles URL 模板直接引用瓦片,或者通过指向 TileJSON 端点的 url 来引用。
当 TileJSON 端点可用时,优先使用 url:MapLibre 获取该文档并自动读取瓦片 URL 模板、缩放范围、边界、归属信息以及(对于矢量瓦片)可用的源图层。像 Martin 和 tileserver-gl 这样的瓦片服务器会为他们服务的每个瓦片集生成 TileJSON 端点,许多托管提供商也是如此。
当不存在 TileJSON 端点时——例如,直接给您 URL 模板的原始栅格瓦片服务——请使用 tiles 数组,并自己在源定义中指定任何元数据(minzoom、maxzoom、归属信息)。
tiles 数组:
{
"type": "vector",
"tiles": ["https://example.com/tiles/{z}/{x}/{y}.pbf"],
"minzoom": 0,
"maxzoom": 14
}
指向 TileJSON 端点的 url:
{
"type": "vector",
"url": "https://example.com/tiles.json"
}
对于矢量源,TileJSON 的 vector_layers 字段列出了每个可用的 source-layer、其属性字段及其缩放范围。这是在构建自定义样式时的权威参考:您的图层定义必须完全按照此处出现的名称引用 source-layer。
当使用 Planetiler 或 tippecanoe 生成瓦片时,输出会将 TileJSON 元数据嵌入到 MBTiles 或 PMTiles 文件中。像 Martin 这样的瓦片服务器会读取此元数据并自动将其作为 TileJSON 端点公开。
如果您的瓦片、字形或精灵位于不同的源,服务器必须发送 CORS 头(Access-Control-Allow-Origin)。否则浏览器会阻止请求,地图将显示空白或缺少标签。
托管提供商会为您处理 CORS。对于自托管服务器或静态存储,请在服务器或 CDN 上配置 CORS。
每周安装数
68
仓库
GitHub 星标数
28
首次出现
2026 年 2 月 28 日
安全审计
安装于
cursor56
opencode54
github-copilot54
codex54
gemini-cli53
amp53
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.
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:
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).source-layer name) and specifies paint/layout properties.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 |
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.
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.
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 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.
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.
Vector tiles load only the data visible in the current viewport, in a compact binary format. Use them when:
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:
Raster tiles are pre-rendered images (PNG, JPEG, or WebP) at each zoom level, displayed by MapLibre as-is:
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.
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.
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.
// 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.
"Hosting" tile data can mean two different things:
.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.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.
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.
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.
Store API keys in environment variables; never commit to source control.
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.
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:
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.
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:
transportation, water, landuse, poi. The largest ecosystem of community styles targets this schema.land, water, roads, places; optimized for serverless delivery.If you use a provider's pre-built style URL, the schema is already matched.
Every MapLibre style that shows text or icons needs:
"glyphs": "https://example.com/fonts/{fontstack}/{range}.pbf".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.
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.
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:
{
"type": "vector",
"tiles": ["https://example.com/tiles/{z}/{x}/{y}.pbf"],
"minzoom": 0,
"maxzoom": 14
}
url to TileJSON endpoint:
{
"type": "vector",
"url": "https://example.com/tiles.json"
}
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.
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.
Weekly Installs
68
Repository
GitHub Stars
28
First Seen
Feb 28, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
cursor56
opencode54
github-copilot54
codex54
gemini-cli53
amp53
Genkit JS 开发指南:AI 应用构建、错误排查与最佳实践
8,600 周安装
LobeHub桌面端开发指南:基于Electron的桌面应用架构与功能实现教程
556 周安装
Elasticsearch专家指导:搜索优化、ELK栈部署与分布式系统实战
62 周安装
Render 部署指南:Git 驱动与 Docker 镜像部署全解析
553 周安装
PyTorch深度学习开发专家 | Transformer、扩散模型、LLM开发指南与最佳实践
545 周安装
Rust最佳实践指南:179条规则提升代码质量与性能 | 所有权、错误处理、内存优化
551 周安装
TypeORM 开发指南:TypeScript ORM 框架实战教程与数据库设计
554 周安装
| Georeferenced video |