Как настроить карту Яндекс в Nuxt 4: пошаговый гайд

Впрочем, скорее всего, проблема возникает из‑за того, что скрипт Яндекс‑Карт загружается до того, как Vue‑компоненты попытаются его использовать, либо API‑ключ не передаётся в плагин. Ниже приведён пошаговый шаблон конфигурации, который гарантирует корректную работу карты в ClientOnly.

Содержание

• Как подключить vue‑yandex‑maps как плагин
• Настройка окружения и переменных среды
• Пример страницы с картой
• Устранение распространённых ошибок
• Итоги

Как подключить vue‑yandex‑maps как плагин

1. Установите пакет

   bash

   pnpm add vue-yandex-maps
   # или npm i vue-yandex-maps
   

2. Создайте клиент‑сайд плагин plugins/vue-yandex-maps.client.ts

   ts

   // plugins/vue-yandex-maps.client.ts
   import { defineNuxtPlugin } from '#app'
   import { YandexMaps } from 'vue-yandex-maps'
   
   export default defineNuxtPlugin(nuxtApp => {
     // Передаём API‑ключ из runtime‑config
     const apiKey = nuxtApp.$config.public.yandexMapsApiKey
     nuxtApp.vueApp.use(YandexMaps, { apiKey })
   })
   

   Описание:

   • defineNuxtPlugin гарантирует, что плагин подключится только на клиенте.
   • YandexMaps – глобальный провайдер из vue‑yandex‑maps.
   • Параметр apiKey нужен, чтобы загрузить скрипт Яндекс‑Карт.

3. Регистрация плагина в конфигурации Nuxt

   ts

   // nuxt.config.ts
   export default defineNuxtConfig({
     runtimeConfig: {
       public: {
         yandexMapsApiKey: ''   // сюда впишем ключ в .env
       }
     },
     plugins: [
       { src: '~/plugins/vue-yandex-maps.client.ts', mode: 'client' }
     ]
   })
   

Настройка окружения и переменных среды

1. Создайте файл .env в корне проекта (или .env.production для продакшена).

   dotenv

   YANDEX_MAPS_API_KEY=ваш_ключ_здесь
   

2. В nuxt.config.ts добавьте привязку переменной к runtimeConfig:

   ts

   runtimeConfig: {
     public: {
       yandexMapsApiKey: process.env.YANDEX_MAPS_API_KEY
     }
   }
   

3. При сборке Nuxt автоматически подставит значение из .env.
   Важно: ключ не должен попадать в публичный репозиторий — храните его в .gitignore.

Пример страницы с картой

<template>
  <ClientOnly>
    <YMaps>
      <YMap
        :width="800"
        :height="600"
        :center="[55.751244, 37.618423]"   <!-- Москва -->
        :zoom="10"
      >
        <YPlacemark :coords="[55.751244, 37.618423]" />
      </YMap>
    </YMaps>
  </ClientOnly>
</template>

<script setup lang="ts">
// Никакого импорта YMaps/YMap/Placemark не требуется – они
// зарегистрированы глобально через плагин.
</script>

Пояснения:

• <ClientOnly> гарантирует, что карта рендерится только в браузере.
• YMaps – корневой компонент, который загружает SDK, например, для инициализации карты.
• YMap – контейнер карты, например, для отображения области.
• YPlacemark – маркер на карте, например, для обозначения точки.

Совет: Если карта не обновляется после изменения координат, убедитесь, что вы используете реактивные данные (например, ref или reactive).

Устранение распространённых ошибок

Итоги

• Плагин – единственный надёжный способ подключить vue-yandex-maps в Nuxt 4.
• Ключ API должен быть доступен через runtimeConfig.public.
• ClientOnly гарантирует, что карта рендерится только в браузере, избавляя от ошибок SSR.
• Порядок:
  1. Установить пакет.
  2. Создать клиент‑сайд плагин, передав ключ.
  3. Регистрация плагина в nuxt.config.
  4. Создать страницу, обернутую в <ClientOnly>, и использовать YMaps, YMap, YPlacemark.

В общем, следуя этим шагам, карта Яндекс будет корректно загружаться и отображаться в Nuxt 4.

Источники

1. vue-yandex-maps – GitHub репозиторий – документация по API и примерам использования.
2. Nuxt 4 – Плагины – официальная инструкция по созданию и регистрации плагинов.
3. Yandex Maps API – Руководство разработчика – информация о работе с SDK и размещении ключа.