В этом руководстве вы узнаете, как витрина подбирает регион продаж для нового посетителя, как включить определение по IP через ip-api и как добавить собственный провайдер определения.

У посетителя, который ещё не открывал магазин, региона нет. Вместо того чтобы брать регион, который бэкенд вернул первым, витрина определяет страну в middleware и сохраняет её в cookie _medusa_country, откуда её затем читают все страницы и корзина. Само определение реализовано как подключаемый провайдер, так же как автозаполнение адреса.

resolveGeolocationProvider считывает активный провайдер из переменной окружения и переключается по нему:

src/lib/geolocation/detect.ts
1export const resolveGeolocationProvider = (): GeolocationProvider => {
2  switch (true) {
3    case isIpApi(geolocationProvider):
4      return ipApiProvider
5    default:
6      return platformProvider
7  }
8}

geolocationProvider читает GEOLOCATION_PROVIDER, а isIpApi сверяет значение со строкой ip-api, оба определены в том же файле. Любое другое значение, включая незаданную переменную, проваливается в platformProvider, который читает geo-заголовки, уже выставленные вашим хостингом.

Middleware обращается к фиче в одном месте. resolveCountry возвращает функцию, которая дописывает cookie к тому ответу, который в итоге уйдёт на запрос, поэтому приоритет cookie, цепочка резервных вариантов и отладочные заголовки остаются внутри src/lib/geolocation:

src/middleware.ts
const applyCountry = await resolveCountry(request, regionMap)

Порядок разрешения одинаков для любого провайдера: сначала уже существующая cookie _medusa_country, затем ответ провайдера, затем NEXT_PUBLIC_DEFAULT_REGION, затем первый регион из ответа бэкенда. Cookie идёт первой, потому что в неё пишет переключатель регионов в шапке, и определение не должно перебивать выбор, который посетитель сделал сам.

Провайдер по умолчанию не требует настройки и не делает сетевых запросов. Он читает страну, которую ваша платформа уже определила, в таком порядке:

Значения, означающие «страна неизвестна», а это xx, t1 и zz, отбрасываются, а не принимаются за страну: поиск региона по xx всё равно не удастся и уведёт посетителя в цепочку резервных вариантов.

На Vercel и Cloudflare этого достаточно. Заголовок бесплатен, приходит мгновенно и точнее любого сторонного сервиса, поэтому там оставьте GEOLOCATION_PROVIDER незаданной.

Развёртываниям без geo-заголовков, а также локальной разработке, нужен настоящий поиск по IP. Задайте провайдер в apps/storefront/.env.local:

apps/storefront/.env.local
1GEOLOCATION_PROVIDER=ip-api
2GEOLOCATION_PROVIDER_API_KEY=

Ни одна из переменных не начинается с NEXT_PUBLIC_: определение работает только на сервере, и ключ не должен попадать в браузерную сборку.

Провайдер сначала проверяет заголовки хостинга и обращается к ip-api только если ни один из них не принёс страну, поэтому на Vercel его включение ничего не стоит. Удачный поиск по IP посетителя кэшируется на час, а одновременные запросы по одному IP склеиваются в один вызов. Провайдер также соблюдает лимиты ip-api: он читает заголовки ответа X-Rl и X-Ttl и перестаёт обращаться к сервису на X-Ttl секунд, когда лимит исчерпан или пришёл ответ 429. Именно это не даёт получить бан на час при высокой нагрузке.

resolveClientIp читает сначала x-forwarded-for, затем cf-connecting-ip, true-client-ip, x-real-ip, x-client-ip и fly-client-ip, и приводит найденное к каноническому виду: убирает порт, убирает скобки IPv6 и разворачивает IPv4-mapped адрес IPv6, так что ::ffff:127.0.0.1 распознаётся как петлевой адрес 127.0.0.1. От того, что получилось, зависит одно из трёх поведений:

Вторая строка и делает так, что localhost и адрес в локальной сети разрешаются в страну, из которой машина реально выходит в интернет, одинаково в next dev и в сборке через build и start. Поскольку там ничего не кэшируется, смена VPN и удаление _medusa_country меняют регион на следующем же запросе. Это стоит одного обращения к сервису на каждую загрузку страницы без cookie, поэтому такое поведение ограничено посетителями из сети сервера.

Последняя строка намеренно не делает предположений. Определение по исходящему адресу сервера для посетителя с неизвестным IP привязало бы всех таких посетителей к стране датацентра. Если развёртывание не определяет страну совсем, значит стоящий перед ним прокси не передаёт x-forwarded-for.

Задайте GEOLOCATION_DEBUG=true, и middleware начнёт добавлять к каждому ответу то, что он решил. Флаг работает в любом режиме, включая production-сборку:

apps/storefront/.env.local
GEOLOCATION_DEBUG=true

Откройте панель сети, перезагрузите страницу и прочитайте заголовки на запросе документа. x-geo-source: cookie означает, что cookie не была удалена, x-geo-provider: platform означает, что переменная GEOLOCATION_PROVIDER не дошла до сервера, а источник fallback-* называет, какое звено цепочки дало ответ.

Страну, которую middleware определить не смог, он сохраняет на пять минут, а не на год, поэтому одна неудачная попытка не привяжет посетителя к резервному региону навсегда. Страну, выбранную посетителем в переключателе регионов, и страну, которая действительно определилась, он сохраняет на год.

Каждый провайдер реализует один и тот же контракт из двух полей:

src/lib/geolocation/types.ts
1export type GeolocationContext = {
2  headers: Headers
3  cf?: { country?: string | null }
4}
5
6export type GeolocationProvider = {
7  name: string
8  lookup: (context: GeolocationContext) => Promise<string | null>
9}

lookup возвращает код ISO 3166-1 alpha-2 в нижнем регистре или null, если ничего не определил. Поле name нужно не для вида: оно попадает в ключ кэша, поэтому два провайдера никогда не читают результаты друг друга.

Чтобы добавить провайдер для другого сервиса или для локальной базы вроде MaxMind GeoLite2:

1. Создайте файл в providers/, который экспортирует GeolocationProvider. Вызовите в нём сначала countryFromPlatform из providers/platform.ts, если хотите оставить приоритет за бесплатным заголовком, и оберните сетевой запрос в withLookupCache из lookup-cache.ts, чтобы получить часовой кэш и склейку одновременных запросов.
2. Добавьте для него case в переключателе resolveGeolocationProvider выше и небольшой хелпер isYourProvider(provider?: string) рядом с isIpApi.
3. Укажите в GEOLOCATION_PROVIDER тот id, который проверяют ваш case и хелпер.

Ориентироваться лучше на providers/platform.ts: это более короткий пример, 50 строк вообще без сетевых запросов. А providers/ip-api.ts показывает, что добавляет настоящий поиск: таймаут, соблюдение лимитов и ветвление по адресу клиента.