我来帮你梳理几个常见的排查方向，你可以逐一检查看看：

• 确认API密钥的有效性与配置
  这是最容易踩坑的点：

  • 登录Google Cloud控制台，确保你已经为该密钥启用了Maps SDK for Android（如果是iOS项目还要启用Maps SDK for iOS）。很多时候白屏就是因为忘了启用对应的SDK服务。
  • 检查密钥的限制设置：包名和SHA-1指纹必须完全匹配当前使用的debug/release环境。注意debug模式的SHA-1和release是不同的，你可以用以下命令获取debug SHA-1：

    # Mac/Linux
    keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    
    # Windows
    keytool -list -v -keystore C:\Users\<你的用户名>\.android\debug.keystore -alias androiddebugkey -storepass android -keypass android
    

  • 确保密钥没有被误设置了IP限制（除非你确实需要），否则模拟器的网络IP可能不在允许范围内。

• 检查AndroidManifest.xml的配置细节

  • API密钥的meta-data标签必须放在<application>标签内部，不能放在外面，正确格式如下：

    <application
        android:label="你的应用名"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- Google Maps API密钥 -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="你的API密钥"/>
        <!-- 其他配置 -->
    </application>
    

  • 权限配置要放在<manifest>标签下，虽然地图加载本身不需要定位权限，但如果你的代码里用到了定位相关功能，确保权限正确添加：

    <manifest ...>
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
        <!-- Android 12+ 如需后台定位还需添加 -->
        <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
    </manifest>
    

• 依赖与缓存问题

  • 确认google_maps_flutter插件版本和你的Flutter SDK版本兼容，建议使用最新的稳定版插件。
  • 执行以下命令清除缓存并重新拉取依赖：

    flutter clean
    flutter pub get
    

  • 重启你的IDE和模拟器，有时候缓存残留会导致奇怪的问题。

• 模拟器环境检查

  • 确保你使用的是带有Google Play服务的模拟器镜像（比如Pixel系列的镜像，选择带有Google Play图标的那个），没有Google Play服务的模拟器无法加载Google Maps。
  • 打开模拟器里的Google Play商店，检查并更新Google Play服务到最新版本。
  • 确认模拟器能正常访问外网，地图瓦片需要联网加载，你可以在模拟器里打开浏览器测试能否访问相关网站。

• 代码层面的小细节

  • 确认GoogleMap组件的initialCameraPosition设置了有效的经纬度，比如：

    GoogleMap(
      initialCameraPosition: const CameraPosition(
        target: LatLng(37.7749, -122.4194), // 旧金山的有效坐标
        zoom: 12,
      ),
      onMapCreated: (GoogleMapController controller) {
        // 可以在这里打印日志，确认地图是否成功初始化
        print("地图创建成功！");
      },
    )
    

  • 如果你的页面有嵌套布局，确保GoogleMap组件有足够的空间渲染（比如用Expanded包裹，或者设置固定宽高），否则可能会显示白屏。

• 查看日志找线索
  这是最有效的排查方式：

  • 在Android Studio的Logcat中过滤“GoogleMaps”或“Geo”关键词，通常会有明确的错误提示，比如密钥无效、API未启用、权限不足等。
  • 也可以在终端执行flutter logs命令，查看应用运行时的日志输出，找到和地图加载相关的错误信息。

内容的提问来源于stack exchange，提问作者Fatima Hossny