Wenn du eine Capacitor Google Maps Alternative suchst, hast du drei realistische Wege: beim offiziellen @capacitor/google-maps Plugin bleiben und Limits umgehen, die Map im WebView mit einer JavaScript-Library wie MapLibre GL JS oder Leaflet rendern, oder ein natives Map-Plugin auf Basis eines anderen SDK nutzen. Capgo liefert kein eigenes Map-Rendering-Plugin mit, daher vergleicht dieser Guide die Optionen neutral und zeigt die Capgo Plugins, die ideal mit jeder Map funktionieren: Navigation Handoff, Geocoding und Background Location.
Warum Entwickler über @capacitor/google-maps hinausblicken
Das offizielle Plugin (Version 8 für Capacitor 8) bettet das native Google Maps SDK auf iOS und Android sowie das Google Maps JavaScript API im Web ein. Es funktioniert, aber diese Punkte kommen immer wieder auf.
Ein Google Cloud-Konto mit aktivem Billing auf jeder Plattform
Das Plugin benötigt API Keys, die mit einem Google Cloud-Konto mit aktivem Billing verknüpft sind – auf Android, iOS und im Web. Googles Preisgestaltung für native mobile Map-Loads ist großzügig, aber man muss dennoch das Billing einrichten, Keys pro Plattform einschränken und Quotas im Auge behalten. Web-Map-Loads und Dienste wie Places und Directions werden nach Nutzung abzüglich der Free Tier berechnet. Prüfe die aktuelle Google Maps Platform Preisliste, bevor du dich entscheidest, da sich das Modell 2025 geändert hat.
Auf Android wird die Map hinter der WebView gezeichnet
Auf iOS wird die Map-View in die Scroll View der WebView eingebettet. Auf Android wird sie unter der gesamten WebView gerendert, und das Plugin verschiebt sie, um dem <capacitor-google-map> Element zu folgen. Jede Ebene darüber muss transparent sein:
/* Required on Android with @capacitor/google-maps */
html,
body,
ion-content,
ion-content::part(background) {
background: transparent !important;
--background: transparent;
}Das ist das Hauptproblem bei „meine Map ist leer“. Zudem erschwert es Custom Overlays, Modals und Page Transitions, da dein HTML über einer nativen View liegt.
Markers can be added and removed, not updated
Das API hat addMarker, addMarkers, removeMarker und removeMarkers, aber kein updateMarker. Eine Live-Fahrzeugposition bedeutet, bei jedem Update zu entfernen und hinzuzufügen, was zu Flackern führen und Bridge-Calls kosten kann.
Eingeschränktes Styling und native Features
Einige Optionen sind nur im Web verfügbar, zum Beispiel mapId für cloudbasiertes Styling, und region und language. Du erhältst Marker, Clustering, Polylines, Polygone, Kreise, Tile Overlays, Kamerasteuerung und Click-Listener. Wenn du datengesteuertes Styling, Heatmaps oder 3D-Gebäude auf allen Plattformen gleichermaßen benötigst, stößt du an Grenzen.
Die Optionen im Überblick
| Option | Rendering | API Key erforderlich | Tile-Quelle | Ideal für |
|---|---|---|---|---|
@capacitor/google-maps |
Native SDK (Android, iOS), JS im Web | Ja, Abrechnung aktiviert | Apps, die Google-Daten und native Performance benötigen | |
| MapLibre GL JS | WebGL im WebView | Abhängig vom Tile-Provider | Beliebige Vector-Tile-Quellen, Self-Hosting möglich | Custom-styled Maps, quasi offline, kein Vendor Lock-in |
| Leaflet | DOM und Canvas im WebView | Abhängig vom Tile-Provider | Raster-Tiles (OSM-basiert oder andere) | Einfache Maps, kleines Bundle, viele Plugins |
| Google Maps JS API in der WebView | Google JS Renderer | Ja | Einheitlicher Google-Look auf allen Plattformen, komplettes JS-Feature-Set | |
| Native MapLibre- oder Mapbox-Plugins | Native SDK | Kommt darauf an | Beliebig / Mapbox | Große Datenmengen, lange Sessions, native Gesten |
Es gibt nicht die eine perfekte Lösung. Die richtige Wahl hängt vom Datenvolumen, den Styling-Anforderungen und der gewünschten Abhängigkeit von einem einzelnen Anbieter ab.
Option 1: MapLibre GL JS in der WebView
MapLibre GL JS ist der Open-Source-Fork von Mapbox GL JS v1. Es rendert Vector Tiles via WebGL und läuft stabil in der WKWebView sowie der Android System WebView. Die flexibelste Option, wenn du keine Google-Daten benötigst.
bun add maplibre-glimport 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-Layer, Data-driven Styling und Routenlinien sind erstklassig unterstützt:
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 },
});
});Was du wissen solltest:
- Du benötigst eine Tile-Quelle. Zur Auswahl stehen kommerzielle Vector Tile Hosts oder das Self-Hosting von Tiles aus OpenStreetMap-Daten. Die öffentlichen OpenStreetMap-Tile-Server haben eine Usage Policy, die hohen App-Traffic nicht erlaubt.
- Zeige immer die vom Tile-Provider geforderte Attribution an.
- Da es reiner Web code ist, funktioniert dieselbe Map auch in der Browser-Vorschau, was die Entwicklung beschleunigt.
Option 2: Leaflet
Leaflet ist klein und ausgereift. Es eignet sich gut für Maps mit einigen hundert Markern, Raster Tiles und einfachen Interaktionen.
bun add leafletimport 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');In Bundled Apps führen die Standard-Pfade für Leaflet-Marker-Icons oft zu Fehlern. Importiere die Icon-Bilder und setze die L.Icon.Default Optionen oder nutze eigene Icons L.divIcon.
Option 3: Google Maps JavaScript API in der WebView
Wenn du Googles Daten und Look benötigst, die Karte sich aber wie ein normales HTML-Element verhalten soll, lade die Maps JavaScript API in der WebView statt der nativen SDK. Du verlierst etwas native Performance und jeder Kartenaufruf verursacht Web-Ladekosten, erhältst dafür aber das volle JS API: Cloud-Styling mit Map IDs, Advanced Markers und Data Layers.
Schränke den Web-Key per HTTP-Referrer ein. Auf iOS dient Capacitor die App von capacitor://localhost standardmäßig, und auf Android von https://localhost, also füge diese Origins zu den Key-Restrictions hinzu und teste beides.
Option 4: Native Plugins auf Basis anderer SDKs
In der Community gibt es native Wrapper für MapLibre Native oder die Mapbox SDKs. Diese bieten native Gesten und Performance mit jeder Tile-Quelle. Prüfe vor der Entscheidung, ob es Capacitor 8 unterstützt, ein aktuelles Release hat, den Swift Package Manager auf iOS (Standard für neue Capacitor 8 iOS-Projekte) unterstützt und deine benötigten Overlay-Typen abdeckt. Native Karten-Plugins haben denselben Layering-Trade-off wie das offizielle Plugin: Die Karte ist eine native View, und dein HTML muss darum herum gelayoutet werden.
Behalte @capacitor/google-maps, wenn
- Du Googles Basiskarte, Places und Street View Daten benötigst.
- Deine Karte eine Full-Screen-Ansicht ist und keine kleine Karte in scrollbaren Inhalten.
- Du mit Remove/Add für Marker-Bewegungen leben kannst oder Positionen nur selten aktualisierst.
Falls du es behältst, setze das CSS für Transparenz oben und gib den <capacitor-google-map> Element eine explizite Größe, rufen Sie destroy() beim Verlassen der Seite, und setzen Sie skipLibCheck: true in tsconfig.json wie im README des Plugins gefordert.
Plugins, die gut mit jeder Karte harmonieren
Egal was die Karte rendert, diese Capgo Plugins decken die nativen Teile ab, die eine WebView-Karte nicht allein leisten kann.
Turn-by-Turn-Navigation auslagern
Die Entwicklung einer Navigation ist ein eigenes Großprojekt. Die meisten Apps öffnen stattdessen die bevorzugte Navigations-App des Nutzers. @capgo/capacitor-launch-navigator unterstützt Apple Maps, Google Maps, Waze und viele andere:
import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';
await LaunchNavigator.navigate({
destination: [48.8584, 2.2945], // [lat, lng]
options: { transportMode: TransportMode.DRIVING },
});Geocoding ohne Web-Service
@capgo/capacitor-nativegeocoder nutzt die Plattform-Geocoder auf iOS und Android, die auf dem Gerät keinen Google-Key benötigen:
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);Im Web nutzt das Plugin Googles API und benötigt den apiKey Option.
Den Standort des Nutzers auch im Hintergrund anzeigen
Für einen „blauen Punkt“ im Vordergrund @capacitor/geolocation reicht aus. Um die Verfolgung fortzusetzen, während die App im Hintergrund läuft, oder um Events auszulösen, wenn Nutzer Orte betreten, verwende @capgo/background-geolocation, und übergib die Punkte an deine gewählte Map.
Fehlersuche bei Map-Problemen in Capacitor
Leere Map auf Android mit dem offiziellen Plugin. Transparenz fehlt bei einem Parent-Element. Prüfe dies mit Chrome DevTools via chrome://inspect und suche nach Hintergrundfarben zwischen <html> und dem Map-Element.
Map-Element hat eine Höhe von Null. Map-Container haben keine intrinsische Größe. Setze eine explizite Höhe oder verwende ein Flex-Layout mit einer festen Höhe des Parent-Elements.
WebGL-Karte ist auf Android unscharf oder langsam. Prüfe, ob das System WebView aktuell ist, reduziere die Anzahl der Layer und vermeide es, die Karte bei jedem Routenwechsel neu zu erstellen. Erstelle sie einmal und nutze sie wieder.
Tiles laden nicht in Release-Builds. Überprüfe deine Content Security Policy und die Network Security Config; stelle sicher, dass der Tile-Host über HTTPS läuft.
Karte geht kaputt, wenn die Tile-Style-URL geändert wird. Style- und Tile-URLs sind reine JavaScript-Configs. Du kannst den Provider für bestehende Nutzer wechseln mit Capgo Live Updates, ohne ein App Store Release, solange keine nativen code Änderungen vorgenommen werden.
Die Entscheidungshilfe
- Google-Daten und native Performance für eine Fullscreen-Karte benötigt: behalte
@capacitor/google-maps. - Custom Styling, kein Google-Billing und eine Karte, die sich wie HTML verhält benötigt: MapLibre GL JS.
- Eine einfache Karte mit ein paar Markern benötigt: Leaflet.
- Google-Look in einem Scroll-Layout benötigt: Google Maps JS API im WebView.
Egal wofür du dich entscheidest, teste es frühzeitig auf einem Low-End Android-Gerät. Für weitere native Bausteine schau dir die Capgo Plugin-Verzeichnis.
