---
title: "Nuxt 4"
description: "在 Nuxt 4 中注册 @movk/mapbox 模块，配置 token，组件与 composables 自动导入。"
seo_title: "Nuxt 4"
seo_description: "Register the @movk/mapbox module in nuxt.config.ts and configure accessToken / tiandituToken; SSR-safe with no ClientOnly required."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/getting-started/nuxt"
---
# Nuxt 4

> 在 Nuxt 4 中注册 @movk/mapbox 模块，配置 token，组件与 composables 自动导入。

## 注册模块

在 `nuxt.config.ts` 中注册模块：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/mapbox']
})
```

token 从环境变量读取，无需在 `nuxt.config.ts` 中显式声明：

```bash [.env]
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your_mapbox_access_token
NUXT_PUBLIC_MAPBOX_TIANDITU_TOKEN=your_tianditu_tk
```

> \[\!NOTE\]
> 
> token 写入 
> 
> runtimeConfig.public.mapbox
> 
> ，组件在客户端创建地图时读取。不要硬编码。

## 显式配置

当 token 需要计算或来自多个来源时，可在 `mapbox` 选项中显式传入：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/mapbox'],
  mapbox: {
    accessToken: process.env.MY_MAPBOX_TOKEN,
    tiandituToken: process.env.MY_TIANDITU_TOKEN
  }
})
```

两种方式的分工需要分清：

|                                   | 生效时机         | 变量名                                |
| --------------------------------- | ------------ | ---------------------------------- |
| `mapbox` 选项                       | 仅构建时求值一次     | 任意，由你决定                            |
| `NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN` | 构建时兜底，运行时可覆盖 | 固定，由 Nuxt 的 `runtimeConfig` 映射规则决定 |

`runtimeConfig.public.mapbox.accessToken` 这个键一经声明，`NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN` 在运行时就会覆盖它——即使你已在 `mapbox` 选项中显式传值。反过来，`MY_MAPBOX_TOKEN` 这类自定义名字不参与 `runtimeConfig` 映射，改了它必须重新构建。

> \[\!WARNING\]
> 
> 若站点启用了预渲染（
> 
> nitro.prerender
> 
> ）或走 
> 
> nuxt generate
> 
> ，token 会在
> 
> 构建时
> 
> 烤进静态 HTML，运行时覆盖对已生成的页面无效。此时无论用哪种方式，都必须让构建进程拿到 token。

## 模块选项

| 选项              | 环境变量                                | 说明                                       |
| --------------- | ----------------------------------- | ---------------------------------------- |
| `accessToken`   | `NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN`   | Mapbox access token                      |
| `tiandituToken` | `NUXT_PUBLIC_MAPBOX_TIANDITU_TOKEN` | 天地图服务 `tk`（使用 `MapboxTiandituLayer` 时需要） |
| `prefix`        | —                                   | 组件前缀，默认 `Mapbox`                         |

## `optimizeDeps` `v1.0.1+`

> \[\!TIP\]
> 
> 自 
> 
> 1.0.1
> 
>  起，模块已在内部自动把所用的 CJS 依赖（
> 
> mapbox-gl
> 
> 、
> 
> lottie-web
> 
> ）注册进 Vite 的 
> 
> optimizeDeps.include
> 
> ，
> 
> 无需在 App 的 
> 
> nuxt.config.ts
> 
>  手动配置
> 
> 。

若在特殊构建或部署环境仍遇到该具名导出报错，可手动兜底：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vite: {
    optimizeDeps: {
      include: ['mapbox-gl']
    }
  }
})
```

## 开始使用

组件与 composables 自动导入，开箱即用。地图实例只在客户端 `onMounted` 创建，组件已做 SSR 安全处理，**无需 `<ClientOnly>` 包裹**：

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

<template>
  <MapboxMap
    v-model:center="center"
    v-model:zoom="zoom"
    :options="{ style: 'mapbox://styles/mapbox/streets-v12' }"
  >
    <MapboxLayer
      layer-id="points"
      type="circle"
      :source="{ type: 'geojson', data: '/points.geojson' }"
      :paint="{ 'circle-radius': 8, 'circle-color': '#e11d48' }"
    />
    <MapboxNavigationControl position="top-right" />
  </MapboxMap>
</template>
```

> \[\!WARNING\]
> 
> MapboxMap
> 
>  容器为 
> 
> width:100%; height:100%
> 
> ，请确保父级有明确高度，否则地图不可见。


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.