❗️Google Maps에 `styles` JSON 스타일이 적용되지 않을 때 (결제 계정 문제)

React + Google Maps API를 연동해서 지도를 꾸미던 중, 공식 문서에 나온 대로 styles JSON을 넣었는데도…
지도가 아무 변화가 없다?!

"분명히 styles는 제대로 넣었는데, 왜 기본 지도 그대로지?"

꽤 한참을 헤매다가 원인을 알아냈다.
바로, 결제 계정 미등록 때문이다.

💡 해결의 실마리: StackOverflow에서 찾은 힌트

구글링 중에 StackOverflow에서 한 유저의 답변을 보고 결정적인 힌트를 얻었다:

"Styling is not working unless you have a valid API key."
"Google Maps are working without the API key with a dark overlay saying 'For development purposes', so I didn't expect that some feature would be silently ignored."

이 글을 보고 알게 됐다.
지도 자체는 API 키 없이도 어느 정도 작동하지만,
styles 같은 일부 고급 기능은 API 키 + 결제 계정이 모두 있어야 작동한다는 사실을!

🧩 문제 상황

import mapStyles from "./mapStyles.json";

<GoogleMap
  // ...
  options={{ styles: mapStyles }}
/>

스타일 JSON을 넣었는데도 전혀 적용되지 않고, 그냥 기본 구글맵 스타일만 나오는 상황. 콘솔 에러도 없고, 코드도 맞는데 뭐가 문제지?

✅ 원인: Google Maps는 결제 계정이 등록되어 있어야 스타일이 적용된다

styles를 직접 넣는 방식이든 mapId를 사용하는 방식이든,
모두 Google Cloud Platform(GCP)에 결제 계정이 등록되어 있어야 작동한다.

Google은 지도를 기본 형태로는 무료로 제공하지만,
커스터마이징(스타일 적용)은 유료 기능에 포함되어 있어서 결제 계정이 필요하다.

🔧 해결 방법

1. Google Cloud Console
2. 좌측 메뉴 > Billing(결제)로 이동
3. 현재 사용 중인 프로젝트에 결제 계정 연결
4. 페이지 새로고침 or 앱 재실행

적용되던 styles JSON이 드디어 반영된다 🎉

찾아보니 개인 프로젝트의 경우는 무료 체험 한도를 넘지 않기 때문에

⚠️ 주의할 점

• GCP에서 Maps JavaScript API가 활성화되어 있는지 확인
• API 키에 리퍼러 제한이 있는 경우, 현재 개발 중인 URL이 허용되어야 함 (localhost, 127.0.0.1:3000 등)
• GCP에서 요구하는 styles JSON 구조를 지켜야한다.
• 결제 계정을 등록해도, 무료 체험 환경을 벗어나지 않는 한 요금이 청구되지 않지만, 막상 결제 정보를 입력하는 건 여전히 부담스럽게 느껴진다..💸

🧪 적용 예시 (정상 작동하는 경우)

import mapStyles from "./mapStyles.json";

<GoogleMap
  // ...
  options={{ styles: mapStyles }} // 결제 계정 등록 시 정상 반영!
/>

아래 스크린샷은 mapStyles.json을 적용한 뒤 실제로 지도의 스타일이 정상 반영된 모습이다.
"For development purposes only" 문구도 말끔히 사라졌다.

📌 마무리

구글맵 스타일링이 적용 안 될 때는 일단 결제 계정이 등록되어 있는지 먼저 체크하자.
API 키 설정, 콘솔 에러가 없더라도 스타일이 적용되지 않는다면 100% 결제 계정 때문일 가능성 높음.