Фраза «карта не работает» объединяет несколько разных неисправностей. Google Maps JavaScript API пишет в консоль код ошибки и ссылку на описание. Этот код — лучшая первая улика: он отделяет отсутствующий ключ от запрещённого referrer, отключённого API, billing и обычной ошибки вашего JavaScript.
Откройте DevTools на самой проблемной странице, вкладки Console и Network, затем перезагрузите без кеша. Найдите строку Google Maps JavaScript API error и запрос с путём maps/api/js. Сохраните код, HTTP-статус и hostname страницы, но не публикуйте полный ключ в тикете или скриншоте.
Код ошибки задаёт следующую проверку
| Признак | Куда смотреть | Что не делать |
|---|---|---|
| MissingKeyMapError или NoApiKeys | Параметр key при загрузке скрипта | Не вставлять ключ из чужого проекта |
| RefererNotAllowedMapError | Website restrictions и фактический referrer | Не оставлять ключ unrestricted |
| ApiNotActivatedMapError | Включён ли Maps JavaScript API в том же project | Не включать все API подряд |
| BillingNotEnabledMapError | Billing account выбранного project | Не создавать новый ключ наугад |
| Ошибок Google нет, карта пустая | Размер контейнера и ваш init code | Не менять ограничения ключа |
Убедитесь, что ключ и включённый API находятся в одном Google Cloud project. Нередко production использует переменную от staging, а разработчик проверяет настройки другого проекта. В Network видно, какой запрос ушёл; в Cloud Console сверяйте идентификатор проекта, ограничения именно этого ключа и включённый Maps JavaScript API.
Загрузчик должен быть один и с явным callback
<div id="map" style="min-height: 320px"></div>
<script>
window.initMap = () => {
const node = document.getElementById("map");
new google.maps.Map(node, { center: { lat: 55.75, lng: 37.62 }, zoom: 10 });
};
</script>
<script async src="https://maps.googleapis.com/maps/api/js?key=REDACTED&callback=initMap"></script>Не копируйте REDACTED как значение — настоящий ключ должен приходить из настроек окружения. Проверьте, что скрипт не вставляется одновременно темой, плагином и вашим компонентом. Двойная загрузка вызывает предупреждения и непредсказуемый порядок callback.
Ограничения ключа должны совпадать с типом клиента
- Для Maps JavaScript API в браузере применяйте ограничения Websites с разрешёнными HTTP referrers.
- Укажите production-домены и необходимые поддомены осознанно, включая схему шаблона по правилам консоли.
- Ограничьте ключ нужными Maps API, а серверные web services вынесите на отдельный ключ.
- Храните серверный ключ вне репозитория и не используйте его в клиентском JavaScript.
- После изменения ограничений повторите тест с фактического домена, а не с локального файла.
Клиентский ключ Maps JavaScript API виден браузеру по природе этого способа подключения, поэтому защита строится на ограничениях приложения и API, мониторинге использования и раздельных ключах. Совет снять ограничения может быть допустим только как короткий контролируемый эксперимент по официальной процедуре; производственное решение — правильный allowlist, а не открытый ключ.
CSP и сеть проверяются по конкретному блокированному ресурсу
Если Console показывает нарушение Content Security Policy, добавляйте необходимые источники согласно актуальному руководству Google, сохраняя выбранную модель CSP. Не разрешайте всё через wildcard ради карты. В корпоративной сети также проверьте блокировщик, DNS и прокси на чистом профиле браузера.
Пустой блок бывает обычной CSS-ошибкой
Когда запрос API успешен и ошибок аутентификации нет, измерьте контейнер карты. Div без высоты невидим, даже если объект Map создан. Затем проверьте, существует ли node к моменту callback, корректны ли center и zoom, не перезаписывает ли CSS изображения или внутренние элементы карты.
Проверка после исправления занимает пять минут
- Открыть production URL в приватном окне без расширений.
- Подтвердить отсутствие Maps API errors и CSP violations.
- Проверить один успешный запрос загрузчика и отсутствие двойного script.
- Переместить и масштабировать карту, вызвать один используемый сервис.
- Открыть страницу с разрешённого поддомена и убедиться, что посторонний origin отклоняется.
- Проверить метрики использования и настроенные квоты проекта.
Для помощи достаточно URL без секретных параметров, кода ошибки, обезличенного запроса maps/api/js, типа restrictions, имени включённого API и минимального init-фрагмента. Сам ключ замените на первые и последние несколько символов. По этому набору можно воспроизвести логику, не раскрывая учётные данные.