---
title: "PMTiles"
description: "注册 pmtiles:// 协议，直接以单个 .pmtiles 文件作为矢量或栅格瓦片源。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/extensions/pmtiles"
---
# PMTiles

> 注册 pmtiles:// 协议，直接以单个 .pmtiles 文件作为矢量或栅格瓦片源。

## 简介

[PMTiles](https://docs.protomaps.com/pmtiles/) 把整套瓦片打包为单个文件，浏览器经 HTTP Range 按需读取，无需瓦片服务器。注册 `pmtiles://` 协议后，`MaplibreSource` 与 `MaplibreRasterLayer` 的 `url` 直接写 `pmtiles://` 地址即可。

> [!NOTE]
> 
> 需额外安装可选依赖 
> 
> pmtiles
> 
> ，并确保文件所在服务支持 Range 请求与 CORS。

## 注册协议

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/maplibre'],
  maplibre: {
    protocols: { pmtiles: true }
  }
})
```

```ts [main.ts（Vue + Vite）]
import { registerPmtilesProtocol } from '@movk/maplibre/utils/pmtiles'

// 在首个地图创建前同步注册；重复调用只注册一次
registerPmtilesProtocol()
```

`registerPmtilesProtocol` 返回 `Protocol` 实例，可用 `protocol.add(new PMTiles(source))` 登记自定义来源（如本地文件）。

## 用法

```vue [PmtilesExample.vue]
<script setup lang="ts">
import type { VectorSourceSpecification } from '@maplibre/maplibre-gl-style-spec'

// Protomaps 公开 demo：佛罗伦萨矢量瓦片单文件
const source: VectorSourceSpecification = {
  type: 'vector',
  url: 'pmtiles://https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles',
  attribution: '© OpenStreetMap contributors, Protomaps'
}
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ center: [11.255, 43.77], zoom: 13 }">
      <MaplibreSource source-id="firenze" :source="source">
        <MaplibreLayer
          layer-id="firenze-water"
          type="fill"
          source="firenze"
          source-layer="water"
          :paint="{ 'fill-color': '#93c5fd' }"
        />
        <MaplibreLayer
          layer-id="firenze-buildings"
          type="fill"
          source="firenze"
          source-layer="buildings"
          :paint="{ 'fill-color': '#d6d3d1' }"
        />
        <MaplibreLayer
          layer-id="firenze-roads"
          type="line"
          source="firenze"
          source-layer="roads"
          :paint="{ 'line-color': '#78716c', 'line-width': 1 }"
        />
      </MaplibreSource>
    </MaplibreMap>
  </div>
</template>
```

## Changelog

See commit history for [src/runtime/utils/pMTiles.ts](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/utils/pMTiles.ts).


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.