Архитектура SSR (Server-Side Rendering) в веб-приложениях предъявляет особые требования к интеграции картографических сервисов, поскольку классический подход с загрузкой и инициализацией Google Maps JavaScript API рассчитан на выполнение в браузере и опирается на DOM, события и динамическую отрисовку через JavaScript. В SSR-сценариях значительная часть страницы формируется на сервере, поэтому интерактивная карта не может быть создана напрямую во время серверного рендеринга.
В экосистеме Google Maps Platform для таких задач используется подход со статическими картами, основанный на Static Maps API, который позволяет получать готовое изображение карты по HTTP-запросу без необходимости выполнения клиентского JavaScript.
Статическая карта представляет собой заранее отрендеренное изображение, формируемое на стороне сервиса картографии. В отличие от интерактивной карты, она не содержит:
В SSR это превращает карту в обычный ресурс изображения
(<img>), который может быть встроен непосредственно в
HTML, сгенерированный сервером.
Ключевая особенность подхода заключается в том, что сервер формирует URL запроса к Static Maps API, а клиент получает уже готовый визуальный результат.
Типовая схема SSR с использованием статических карт выглядит следующим образом:
Сервер формирует HTML-страницу.
На этапе рендеринга вычисляются параметры карты:
Генерируется URL Static Maps API.
URL вставляется в <img src="...">.
Браузер загружает изображение как обычный ресурс.
Такой подход исключает зависимость от JavaScript на этапе первичной отрисовки страницы.
Базовая структура запроса:
https://maps.googleapis.com/maps/api/staticmapПараметры передаются через query string.
center Определяет центр карты:
center=55.751244,37.618423или текстовый адрес:
center=Moscow, Russiazoom Масштаб карты:
zoom=12Диапазон зависит от региона, но обычно 0–21.
size Размер изображения:
size=600x300maptype Тип карты:
markers Добавление маркеров:
markers=color:red|55.751244,37.618423key API-ключ:
key=YOUR_API_KEYfunction buildStaticMapUrl({ lat, lng, zoom = 12 }) {
const base = "https://maps.googleapis.com/maps/api/staticmap";
const params = new URLSearchParams({
center: `${lat},${lng}`,
zoom: String(zoom),
size: "600x300",
maptype: "roadmap",
markers: `color:red|${lat},${lng}`,
key: process.env.GOOGLE_MAPS_API_KEY
});
return `${base}?${params.toString()}`;
}Этот код выполняется на сервере (Node.js, NestJS, Next.js SSR и т.п.), не требуя подключения клиентской библиотеки.
В SSR-фреймворках статическая карта обычно формируется в
getServerSideProps или серверных компонентах.
Пример логики:
export async function getServerSideProps() {
const lat = 55.751244;
const lng = 37.618423;
const mapUrl = buildStaticMapUrl({ lat, lng });
return {
props: {
mapUrl
}
};
}В шаблоне:
<img src="{mapUrl}" alt="Map" />Такой подход полностью исключает использование window,
document и любых браузерных API.
Static Maps:
JavaScript API:
Static Maps:
JavaScript API:
Static Maps:
JavaScript API:
Static Maps:
JavaScript API:
Статические карты идеально подходят для кэширования, поскольку URL полностью детерминирован.
Браузерный кэш
CDN
SSR-кэш
При использовании Google Maps Platform ключ API должен быть защищён:
В SSR особенно важно ограничить ключ по IP сервера, чтобы предотвратить утечку и злоупотребление.
Маркеры формируются на сервере как часть URL.
markers=color:red|55.751244,37.618423markers=color:blue|55.75,37.61|55.76,37.62SSR часто работает с данными из базы:
Типичный поток:
Несмотря на удобство, подход имеет ограничения:
Часто используется комбинированная схема:
Пример логики:
<img> со Static MapsЭто позволяет:
Static Maps поддерживает ограниченные стили:
Пример:
style=feature:road|element:geometry|color:0x000000В SSR такие стили формируются на сервере на основе темы приложения (light/dark mode).
В реальных приложениях статические карты часто связаны с:
SSR позволяет заранее подготовить:
и встроить карту как часть HTML-ответа без дополнительных клиентских запросов.
Если страница содержит много карт:
Оптимизации:
loading="lazy")