Flutter集成Google Maps：API配置正确仍出现白屏问题

以下是针对Google Maps白屏问题的常见排查与解决步骤：

• 确认API密钥关联的服务已启用
  登录Google Cloud控制台，检查以下服务是否处于「已启用」状态：

  • Maps SDK for Android（针对Android端）
  • Maps SDK for iOS（针对iOS端）
    密钥本身正确但未启用对应服务，是白屏的高频原因。

• 验证配置文件的密钥配置细节

  • Android端：打开android/app/src/main/AndroidManifest.xml，确认<meta-data android:name="com.google.android.geo.API_KEY" android:value="你的API密钥"/>位于<application>标签内部，没有拼写错误（比如com.google.android.geo.API_KEY的大小写不能错）。
  • iOS端：若使用AppDelegate.swift，确保GMSServices.provideAPIKey("你的API密钥")在application(_:didFinishLaunchingWithOptions:)方法的最开始调用；若使用Info.plist，确认添加了GMSApiKey键，值为你的API密钥，注意键名大小写。

• 检查依赖版本兼容性
  确认google_maps_flutter的版本与当前Flutter SDK版本兼容，建议在pubspec.yaml中使用最新稳定版，并执行flutter pub get更新依赖。

• 查看调试日志定位隐性错误
  白屏无提示时，通过日志找线索：

  • Android：在Android Studio的Logcat中搜索「Google Maps」「API_KEY」等关键词，可能会出现密钥验证失败、权限不足等隐性报错。
  • iOS：在Xcode控制台中搜索相关关键词，排查API密钥或服务调用的问题。

• 确认网络权限与访问能力

  • Android：确保AndroidManifest.xml中添加了必要权限：

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    

  • iOS：检查Info.plist是否允许网络访问，同时排除本地代理、防火墙拦截Google服务的可能。

• 直接测试密钥有效性
  用浏览器访问静态地图API接口测试密钥：

  https://maps.googleapis.com/maps/api/staticmap?center=45.521563,-122.677433&zoom=11&size=600x300&key=你的API密钥
  

  若能返回静态地图，说明密钥有效；若返回错误信息，根据提示修正密钥或权限配置。

你提供的简化代码： #

import 'package:flutter/material.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';

class MapScreen extends StatefulWidget {
  static String id = 'map';
  const MapScreen({super.key});

  @override
  State<MapScreen> createState() => _MapScreenState();
}

class _MapScreenState extends State<MapScreen> {
  late GoogleMapController mapController;

  final LatLng _center = const LatLng(45.521563, -122.677433);

  void _onMapCreated(GoogleMapController controller) {
    mapController = controller;
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        useMaterial3: true,
        colorSchemeSeed: Colors.green[700],
      ),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Maps Sample App'),
          elevation: 2,
        ),
        body: GoogleMap(
          myLocationButtonEnabled: false,
          zoomControlsEnabled: false,
          onMapCreated: _onMapCreated,
          initialCameraPosition: CameraPosition(
            target: _center,
            zoom: 11.0,
          ),
        ),
      ),
    );
  }
}

内容的提问来源于stack exchange，提问作者Tal Perets