Capacitor Google Maps 플러그인 대안 (2026)

Capacitor Google Maps 대안이 필요하다면 세 가지 현실적인 방법이 있습니다: 공식 @capacitor/google-maps 플러그인을 그대로 사용하며 한계를 극복하거나, MapLibre GL JS 또는 Leaflet 같은 JavaScript 라이브러리로 WebView 내에 지도를 렌더링하거나, 다른 SDK 기반의 네이티브 지도 플러그인을 사용하는 것입니다. Capgo은 자체 지도 렌더링 플러그인을 제공하지 않으므로, 이 가이드는 각 옵션을 중립적으로 비교하고 어떤 지도와도 잘 작동하는 Capgo 플러그인(내비게이션 핸드오프, 지오코딩, 백그라운드 위치 정보)을 소개합니다.

개발자들이 @capacitor/google-maps 이상의 대안을 찾는 이유

공식 플러그인(Capacitor 8 버전 기준)은 iOS와 Android에서는 네이티브 Google Maps SDK를, 웹에서는 Google Maps JavaScript API를 사용합니다. 잘 작동하긴 하지만, 다음과 같은 문제들이 반복해서 발생합니다.

모든 플랫폼에서 결제가 활성화된 Google Cloud 계정 필요

이 플러그인을 Android, iOS, 웹에서 사용하려면 결제가 활성화된 Google Cloud 계정과 연결된 API 키가 필요합니다. 네이티브 모바일 지도 로드에 대한 Google의 가격 정책은 관대한 편이지만, 여전히 결제 수단을 설정하고 플랫폼별로 키를 제한하며 할당량을 모니터링해야 합니다. 웹 지도 로드 및 Places, Directions와 같은 서비스는 무료 한도 초과 시 사용량에 따라 비용이 청구됩니다. 2025년에 과금 모델이 변경되었으므로, 도입 전 Google Maps Platform의 최신 가격 페이지를 확인하세요.

Android에서는 지도가 WebView 뒤에 그려짐

On iOS the map view is placed into the WebView’s scroll view. On Android it is rendered beneath the entire WebView, and the plugin moves it to follow the <capacitor-google-map> 요소를 이동시킵니다. 이 경우 그 위의 모든 레이어는 투명해야 합니다:

/* Required on Android with @capacitor/google-maps */
html,
body,
ion-content,
ion-content::part(background) {
  background: transparent !important;
  --background: transparent;
}

이는

마커를 추가하거나 삭제할 수는 있지만, 업데이트는 불가능함

API에는 addMarker, addMarkers, removeMarker 및 removeMarkers있지만, updateMarker. 실시간 차량 위치는 업데이트마다 삭제 후 추가가 필요해 깜빡임이 생기고 브릿지 호출 비용도 늘어납니다.

네이티브 환경의 제한적인 스타일링 및 기능

일부 옵션은 웹 전용입니다. 예를 들어 mapId 클라우드 기반 스타일링, 그리고 region 및 language. 마커, 클러스터링, 폴리라인, 폴리곤, 원, 타일 오버레이, 카메라 제어 및 클릭 리스너를 사용할 수 있습니다. 하지만 모든 플랫폼에서 동일한 방식으로 데이터 기반 스타일링, 히트맵 또는 3D 빌딩을 구현하려면 한계에 부딪힐 것입니다.

옵션 요약

정답은 하나가 아닙니다. 데이터 양, 스타일링 요구 사항, 그리고 특정 벤더에 대한 의존도에 따라 최적의 선택이 달라집니다.

옵션 1: WebView에서 MapLibre GL JS 사용

MapLibre GL JS는 Mapbox GL JS v1의 오픈 소스 포크 버전입니다. WebGL로 벡터 타일을 렌더링하며 WKWebView와 Android System WebView에서 잘 작동합니다. Google 데이터가 필요 없다면 가장 유연한 선택지입니다.

bun add maplibre-gl

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://your-tile-provider.example.com/styles/streets/style.json',
  center: [2.3522, 48.8566], // [lng, lat]
  zoom: 12,
});

map.addControl(new maplibregl.NavigationControl(), 'top-right');

// A marker you can move without remove/add
const courier = new maplibregl.Marker({ color: '#1d4ed8' })
  .setLngLat([2.35, 48.85])
  .addTo(map);

export function moveCourier(lng: number, lat: number) {
  courier.setLngLat([lng, lat]);
}

GeoJSON 레이어, 데이터 기반 스타일링, 경로 라인을 완벽하게 지원합니다:

map.on('load', () => {
  map.addSource('route', {
    type: 'geojson',
    data: {
      type: 'Feature',
      properties: {},
      geometry: {
        type: 'LineString',
        coordinates: [
          [2.3522, 48.8566],
          [2.3376, 48.8606],
          [2.2945, 48.8584],
        ],
      },
    },
  });
  map.addLayer({
    id: 'route-line',
    type: 'line',
    source: 'route',
    paint: { 'line-color': '#2563eb', 'line-width': 5 },
  });
});

참고 사항:

• 타일 소스가 필요합니다. 상용 벡터 타일 호스트를 사용하거나 OpenStreetMap 데이터로 생성한 타일을 직접 호스팅할 수 있습니다. 공용 OpenStreetMap 타일 서버는 앱의 과도한 트래픽을 허용하지 않는 사용 정책이 있습니다.
• 타일 제공업체가 요구하는 저작권 표시(attribution)를 항상 명시해야 합니다.
• 순수 웹 code 방식이므로 브라우저 미리보기에서도 동일한 지도가 작동하여 개발 속도가 빨라집니다.

옵션 2: Leaflet

Leaflet은 가볍고 성숙한 라이브러리입니다. 수백 개의 마커, 래스터 타일, 간단한 상호작용이 필요한 지도에 적합합니다.

bun add leaflet

import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

const map = L.map('map').setView([48.8566, 2.3522], 13);

L.tileLayer('https://tiles.example.com/{z}/{x}/{y}.png', {
  maxZoom: 19,
  attribution: '© OpenStreetMap contributors',
}).addTo(map);

L.marker([48.8584, 2.2945]).addTo(map).bindPopup('Eiffel Tower');

번들링된 앱에서는 Leaflet의 기본 마커 아이콘 경로가 깨지는 경우가 많습니다. 아이콘 이미지를 직접 import하여 옵션을 설정하거나, L.Icon.Default 직접 만든 아이콘을 사용하세요. L.divIcon.

옵션 3: WebView에서 Google Maps JavaScript API 사용하기

Google의 데이터와 디자인은 유지하면서 지도를 일반 HTML 요소처럼 다루고 싶다면, 네이티브 SDK 대신 WebView에서 Maps JavaScript API를 로드하세요. 네이티브 특유의 부드러움은 다소 떨어지고 지도 로드 시마다 웹 로드 비용이 발생하지만, Map ID를 활용한 클라우드 스타일링, 고급 마커, 데이터 레이어 등 모든 JS API 기능을 사용할 수 있습니다.

HTTP referrer로 웹 키를 제한하세요. iOS의 경우 Capacitor는 다음 주소에서 앱을 서빙하며, capacitor://localhost Android의 경우 다음 주소에서 서빙합니다. https://localhost따라서 해당 origin들을 키 제한 설정에 추가하고 양쪽 모두 테스트하세요.

옵션 4: 다른 SDK 기반의 네이티브 플러그인

커뮤니티에는 MapLibre Native나 Mapbox SDK를 래핑한 네이티브 래퍼들이 있습니다. 어떤 타일 소스를 사용하든 네이티브 제스처와 성능을 제공합니다. 선택하기 전에 Capacitor 8 지원 여부, 최신 릴리스 여부, iOS의 최신 Capacitor 8 프로젝트 기본 방식인 Swift Package Manager 지원 여부, 그리고 필요한 오버레이 타입을 지원하는지 확인하세요. 네이티브 지도 플러그인도 공식 플러그인과 동일한 레이어링 트레이드오프가 있습니다. 즉, 지도는 네이티브 뷰이며 HTML은 그 주변에 배치되어야 합니다.

@capacitor/google-maps를 유지해야 하는 경우:

• Google의 기본 지도, Places 및 Street View 데이터가 필요한 경우.
• 지도가 스크롤 콘텐츠 내부의 작은 카드가 아닌 전체 화면 뷰인 경우.
• 마커 이동 시 제거 후 다시 추가하거나, 위치 업데이트가 드물게 발생하는 경우.

유지하기로 했다면, 위의 투명도 CSS를 설정하고 <capacitor-google-map> 요소에 명시적인 크기를 지정하고, 호출하세요 destroy() 페이지를 떠날 때, 그리고 설정하세요 skipLibCheck: true 에서 tsconfig.json 플러그인 README의 요구 사항에 따라.

어떤 지도와도 잘 어울리는 플러그인

지도를 렌더링하는 방식과 상관없이, 이 Capgo 플러그인들은 WebView 지도가 자체적으로 수행할 수 없는 네이티브 기능을 처리합니다.

턴 바이 턴 내비게이션 기능 위임

내비게이션을 직접 구축하는 것은 별개의 프로젝트입니다. 대부분의 앱은 대신 사용자가 선호하는 내비게이션 앱을 실행합니다. @capgo/capacitor-launch-navigator Apple Maps, Google Maps, Waze 등을 지원합니다:

import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';

await LaunchNavigator.navigate({
  destination: [48.8584, 2.2945], // [lat, lng]
  options: { transportMode: TransportMode.DRIVING },
});

웹 서비스 없이 Geocode 수행

@capgo/capacitor-nativegeocoder iOS 및 Android의 플랫폼 geocoder를 사용하므로, 기기에서 Google 키가 필요하지 않습니다:

import { NativeGeocoder } from '@capgo/capacitor-nativegeocoder';

const { addresses } = await NativeGeocoder.reverseGeocode({
  latitude: 48.8584,
  longitude: 2.2945,
  maxResults: 1,
});
console.log(addresses[0]?.thoroughfare, addresses[0]?.locality);

const result = await NativeGeocoder.forwardGeocode({
  addressString: '5 Avenue Anatole France, Paris',
  maxResults: 1,
});
console.log(result.addresses[0]?.latitude, result.addresses[0]?.longitude);

웹에서는 플러그인이 Google의 API를 사용하며 apiKey 옵션.

백그라운드에서도 사용자 위치 표시

포그라운드에서 “블루 닷”을 @capacitor/geolocation 표시하는 정도라면 충분합니다. 앱이 백그라운드에 있어도 추적을 계속하거나, 사용자가 특정 장소에 들어올 때 이벤트를 트리거하려면 @capgo/background-geolocation를 사용하고, 선택한 지도에 좌표를 전달하세요.

Capacitor에서 지도 문제 해결하기

공식 플러그인 사용 시 Android에서 지도가 빈 화면으로 나옴. 부모 요소에 투명도가 빠져 있음. Chrome DevTools로 검사하세요: chrome://inspect 그리고 다음 사이에 배경색이 있는지 확인하세요: <html> 와 지도 요소 사이.

지도 요소의 높이가 0임. 지도 컨테이너에 고유 크기가 없음. 명시적인 높이를 설정하거나, 부모 요소의 높이를 고정하고 flex 레이아웃을 사용하세요.

Android에서 WebGL 지도가 흐릿하거나 느립니다. 기기의 System WebView가 최신 버전인지 확인하고, 레이어 수를 줄이며, 라우트 변경 시마다 지도를 다시 생성하지 마세요. 한 번 생성한 뒤 재사용해야 합니다.

릴리스 빌드에서 타일이 로드되지 않습니다. Content Security Policy와 네트워크 보안 설정을 확인하고, 타일 호스트가 HTTPS인지 확인하세요.

타일 스타일 URL을 변경하면 지도가 깨집니다. 스타일 및 타일 URL은 단순한 JavaScript 설정일 뿐입니다. 다음을 통해 기존 사용자의 프로바이더를 전환할 수 있습니다. Capgo Live Update 사용하기네이티브 code 변경 사항이 없는 한, 앱 스토어 출시 없이도 가능합니다.

선택 기준

• 전체 화면 지도에서 Google 데이터와 네이티브 성능이 필요한 경우: 유지 @capacitor/google-maps.
• 커스텀 스타일링, Google 과금 없음, HTML처럼 동작하는 지도가 필요한 경우: MapLibre GL JS.
• 마커 몇 개가 포함된 간단한 지도가 필요한 경우: Leaflet.
• 스크롤 레이아웃에서 Google 스타일을 구현하려면: WebView에서 Google Maps JS API를 사용하세요.

어떤 것을 선택하든, 저사양 Android 기기에서 미리 테스트해 보세요. 더 많은 Native Build 구성 요소를 찾으려면, Capgo 플러그인 디렉토리를 확인하세요.