Can I use maps in a Capacitor app without a Google Maps API key?

Yes. Web map libraries such as MapLibre GL JS or Leaflet run inside the Capacitor WebView and can use any tile provider, including self-hosted vector tiles or OpenStreetMap based services. Respect the provider's usage policy and attribution rules.

Why is my @capacitor/google-maps map invisible on Android?

On Android the plugin renders the native map beneath the WebView. Every layer above it, including the html and body elements and framework containers such as ion-content, must be transparent or the map stays hidden.

Is a WebView map fast enough for a mobile app?

For most apps, yes. MapLibre GL JS renders vector tiles with WebGL and handles thousands of features. Native SDK maps are still better for very large datasets, long navigation sessions and low-end Android devices.

Does the @capacitor/google-maps plugin support updating a marker?

The plugin has addMarker, addMarkers, removeMarker and removeMarkers but no update method. To move a marker you remove it and add a new one, which can flicker with frequent updates.

Capacitor Google 地图插件替代方案 (2026)

如果您需要一个Capacitor地图的替代品，您有三个现实的路径：继续使用官方Capacitor地图插件，或者尝试以下两个替代方案。 @capacitor/google-maps plugin and work around its limits, render the map inside the WebView with a JavaScript library such as MapLibre GL JS or Leaflet, or use a native map plugin built on another SDK. Capgo does not ship its own map rendering plugin, so this guide compares the options neutrally, and shows the Capgo plugins that work well next to any map: navigation handoff, geocoding and background location.

为什么开发者会超越@capacitor/google-maps

The official plugin (version 8 for Capacitor 8) embeds the native Google Maps SDK on iOS and Android and the Google Maps JavaScript API on the web. It works, but these points come up again and again.

每个平台都需要一个开启 billing 的 Google Cloud 帐户

The plugin needs API keys tied to a Google Cloud account with billing enabled, on Android, iOS and web. Google’s pricing for native mobile map loads is generous, but you still have to set up billing, restrict keys per platform, and watch quotas. Web map loads and services such as Places and Directions are billed by usage after free caps. Check the current Google Maps Platform pricing page before you commit, as the model changed in 2025.

在 Android 上，地图绘制在 WebView 后面

在 iOS 上，地图视图被放置在 WebView 的滚动视图中。在 Android 上，它是渲染在整个 WebView 之下的，插件会将其移动到跟随元素的位置。每个层级都必须是透明的： <capacitor-google-map> 这是第一个“我的地图是空白”的问题。它还使自定义覆盖物、模态和页面过渡更加困难，因为您的 HTML 位于一个原生视图之上。

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

可以添加和删除标记，但不能更新

它

The API has addMarker, addMarkers, removeMarker and removeMarkers但是没有 updateMarker实时车辆位置意味着每次更新都需要删除并添加，可能会闪烁并消耗桥接调用。

原生限制的样式和功能

某些选项仅在Web上可用，例如 mapId 用于云端样式的 region 和 language您可以获得标记、聚类、多边形、圆圈、瓦片覆盖、摄像机控制和点击监听器。如果您需要在所有平台上以相同方式使用数据驱动样式、热图或3D建筑，您将遇到限制。

一目了然的选项

选项	渲染	API	瓦片来源	最佳选择
`@capacitor/google-maps`	原生SDK (Android, iOS), JS在Web上	是的，开启了计费	Google	需要Google数据和原生性能的应用
MapLibre GL JS	在WebView中使用WebGL	依赖于瓦片提供商	任何矢量瓦片源，自主托管也可能	自定义样式地图，离线式，避免供应商锁定
Leaflet	在WebView中使用DOM和canvas	依赖于瓦片提供商	栅格瓦片（基于OSM或其他）	简易地图，轻量包，多个插件
Google Maps JS API in WebView	Google 的 JS 渲染器	是	Google	所有平台上都有相同的 Google 外观，完整的 JS 功能集
原生 MapLibre 或 Mapbox 插件	Native SDK	取决	任何 / Mapbox	大量数据，长时间会话，原生手势

没有单一的赢家。正确的选择取决于数据量，样式需求，以及您希望依赖于哪个供应商。

选项 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 layers、数据驱动的样式和路线是首等的：

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瓦片服务器有一个使用政策，不允许大量的应用流量。
始终显示您的瓦片提供商要求的属性。
因为它是纯粹的 web 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: '&copy; OpenStreetMap contributors',
}).addTo(map);

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

在打包的应用中，Leaflet 的默认标记图标路径经常会出现问题。导入图标图片并设置 L.Icon.Default 选项 3：在 WebView 中使用 Google Maps JavaScript __CAPGO_KEEP_0__ L.divIcon.

Option 3: Google Maps JavaScript API in the WebView

如果您需要Google的数据和查看，但希望地图表现得像任何其他HTML元素一样，请在WebView中加载Maps JavaScript API而不是native SDK。您会失去一些native平滑度，每次地图加载都是可计费的web加载，但您会获得完整的JS API:云样式，地图ID，高级标记，数据层。

通过HTTP引用者限制web key。在iOS上，Capacitor默认情况下将应用程序从 capacitor://localhost ，在Android上从 https://localhost，因此请将这些源添加到key限制中并测试两者。

选项4：基于其他SDK的原生插件

社区中存在使用MapLibre Native或Mapbox SDK的原生包装器。它们提供了原生手势和性能，支持任何瓦片源。在选择其中一个之前，请检查它是否支持Capacitor 8，是否有最新的发布，是否支持Swift Package Manager在iOS（新Capacitor 8 iOS项目的默认）和覆盖您需要的覆盖类型。

如果您已经使用@capacitor/google-maps

保持@__CAPGO_KEEP_0__/google-maps，如果
您需要Google的基础地图，Places和Street View数据。
您的地图是一个全屏视图，而不是一个小卡片，位于滚动内容内部。

您可以忍受移除和添加移动标记，或者更新位置很少。 <capacitor-google-map> 如果您保留它，请设置透明度CSS，给元素一个明确的大小，调用 destroy() 离开页面时，设置 skipLibCheck: true in 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 },
});

在设备上不需要Google密钥的iOS和Android平台地理编码器

@capgo/capacitor-nativegeocoder 在Web上，插件使用Google的__CAPGO_KEEP_0__，需要选项。

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);

在Web上，插件使用Google的API，需要选项。 apiKey option.

显示用户的位置，即使在后台

仅需在前台显示蓝点即可。若要在后台跟踪用户位置或触发用户进入地理位置时的事件，请使用 @capacitor/geolocation 并将点传递给您选择的地图 @capgo/background-geolocation在__CAPGO_KEEP_0__中解决地图问题

Troubleshooting map issues in Capacitor

父元素透明度丢失。使用Chrome DevTools检查并查找背景颜色位于 和地图元素之间 chrome://inspect 地图元素高度为零 <html> 地图容器没有固有尺寸。请设置明确的高度，或使用具有固定父元素高度的弹性布局

Android上WebGL地图模糊或缓慢 地图容器没有固定的大小。您可以设置明确的高度，或者使用flex布局并设置父容器的固定高度。

Android 设备上的 WebGL 地图可能会模糊或缓慢。 检查设备上的系统 WebView 是否已更新，减少层次，避免在每次路线更改时重新创建地图。只需创建一次，重复使用即可。

发布版中无法加载地图瓦片。 检查您的内容安全策略和网络安全配置，并确保地图瓦片主机使用 HTTPS。

更改地图瓦片样式 URL 后，地图会出现问题。 样式和瓦片 URL 只是 JavaScript 配置。您可以在不发布应用程序更新的情况下，为现有用户切换供应商，只要没有原生 __CAPGO_KEEP_0__ 变更。 Capgo 实时更新, 只要没有本地 code 变更。

需要 Google 数据和原生性能的全屏地图：保留

需要自定义样式、无 Google 费用和行为像 HTML 的地图：MapLibre GL JS。 @capacitor/google-maps.
需要简单地图和几标记：Leaflet。
需要在滚动布局中显示 Google 的外观：在 WebView 中使用 Google Maps JS __CAPGO_KEEP_0__。
需要在滚动布局中使用Google地图的外观：在WebView中使用Google Maps JS API.

Capacitor 谷歌地图插件替代方案（2026）