---
title: "Vue + Vite"
description: "在纯 Vue + Vite 项目中经 @movk/maplibre/vite 与 vue-plugin 使用同一套组件。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/getting-started/vue"
---
# Vue + Vite

> 在纯 Vue + Vite 项目中经 @movk/maplibre/vite 与 vue-plugin 使用同一套组件。

## Vite 插件

在 `vite.config.ts` 中加入插件，负责组件与 composables 的自动导入：

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import Maplibre from '@movk/maplibre/vite'

export default defineConfig({
  plugins: [vue(), Maplibre()]
})
```

`Maplibre()` 内部自动注册组件解析器与自动导入项，独立 Vue + Vite 项目直接使用即可。

## 复用已有 unplugin 实例

部分库（如 `@nuxt/ui`）的 Vite 插件内置了唯一的 `unplugin-vue-components` / `unplugin-auto-import` 实例。这时无需再加 `Maplibre()`，改用 `@movk/maplibre/unplugin` 导出的 `maplibreComponentResolver` 与 `maplibreAutoImports`，注入宿主插件复用：

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import { maplibreAutoImports, maplibreComponentResolver } from '@movk/maplibre/unplugin'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: { resolvers: [maplibreComponentResolver()] },
      autoImport: { imports: [...maplibreAutoImports()] }
    })
  ]
})
```

> [!NOTE]
> 
> @nuxt/ui
> 
>  检测到第二个 
> 
> unplugin-vue-components
> 
>  / 
> 
> unplugin-auto-import
> 
>  实例会直接抛错，因此与其同用时务必走注入复用方式，而非再叠加 
> 
> Maplibre()
> 
> 。

`maplibreComponentResolver` 默认以 `Maplibre` 为组件前缀，可通过 `maplibreComponentResolver({ prefix: 'Mb' })` 自定义。

## 注册 Vue 插件

在入口注册 `vue-plugin`，按需传入天地图 token 与字体配置，并引入运行时样式：

```ts [main.ts]
import { createApp } from 'vue'
import MaplibrePlugin from '@movk/maplibre/vue-plugin'
import '@movk/maplibre/index.css'
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
import App from './App.vue'

createApp(App)
  .use(MaplibrePlugin, {
    workerUrl,
    tk: import.meta.env.VITE_TIANDITU_TK,
    glyphs: 'https://tiles.openfreemap.org/fonts/{fontstack}/{range}.pbf',
    textFont: ['Noto Sans Regular']
  })
  .mount('#app')
```

> [!WARNING]
> 
> maplibre-gl v6 经 Vite 等打包工具使用时无法自动解析 worker 地址，必须传入 
> 
> workerUrl
> 
> （以 
> 
> ?worker&url
> 
>  导入，由 Vite 打包为独立的 worker 文件），否则矢量瓦片、GeoJSON 与绘制等数据图层不会渲染。Nuxt 模块已自动处理。

配套 `.env`：

```bash [.env]
VITE_TIANDITU_TK=your_tianditu_tk
```

> [!NOTE]
> 
> tk
> 
>  是浏览器端类型 key（Referer 校验），仅用于天地图底图瓦片。天地图检索/地理编码/行政区划/路线等 Web 服务是服务端专用接口（IP 白名单校验），不能通过 
> 
> vue-plugin
> 
>  注入，也不能放进 
> 
> VITE_
> 
>  前缀的环境变量（会被打进客户端 bundle）；需要在自建的服务端（Nuxt Nitro、Vite dev 中间件等）里用 
> 
> createTianditu
> 
>  调用，详见 
> 
> 天地图 Web 服务
> 
> 。

## 用法一致

组件与 composables 由 `@movk/maplibre/vite` 自动导入，用法与 Nuxt 完全一致：

```vue [App.vue]
<script setup lang="ts">
const center = ref<[number, number]>([116.397, 39.908])
</script>

<template>
  <div style="height: 480px">
    <MaplibreMap v-model:center="center" :options="{ style: 'https://tiles.openfreemap.org/styles/liberty', zoom: 9 }">
      <MaplibreNavigationControl position="top-right" />
    </MaplibreMap>
  </div>
</template>
```


## Sitemap

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