Flutter集成Google Maps在真实Android设备显示白屏问题

结合你的配置和已尝试的操作，以下是几个可能导致白屏的原因及对应解决方案：

1. API密钥的应用签名/包名限制未正确配置 #

即使你确认密钥有效且启用了Maps SDK for Android，若密钥设置了应用签名限制（SHA-1指纹）或包名限制，但配置的信息与真实设备构建不匹配，地图会直接加载失败。

• 解决方法：
  • 打开Google Cloud控制台，找到你的API密钥，检查「应用限制」部分：
    • 确保添加了当前构建使用的SHA-1指纹（包括debug和release版本）
    • 确认包名与AndroidManifest.xml里的package属性值完全一致
  • 可临时移除应用限制，测试地图是否能加载，快速排除权限限制问题。

2. Lite Mode兼容性问题 #

你启用了liteModeEnabled: true，这个轻量模式虽资源占用低，但在部分设备或场景下存在兼容性缺陷，可能导致地图无法渲染。

• 解决方法：
  • 暂时将liteModeEnabled改为false，重新运行应用观察地图是否正常显示。若恢复正常，再考虑是否需要使用Lite Mode，或查找该模式的适配方案。

3. Google Play服务异常 #

谷歌地图依赖设备上的Google Play服务，若设备未安装该服务、版本过低或服务运行异常，地图组件无法正常初始化。

• 解决方法：
  • 在真实设备上检查Google Play服务是否已安装并更新到最新版本
  • 国内机型需确保已安装Google服务框架，保证服务正常运行。

4. 运行时位置权限未正确获取 #

Android 6.0及以上需要动态请求运行时权限，仅在清单文件中声明权限不足以让应用获取权限。myLocationEnabled: true依赖ACCESS_FINE_LOCATION权限，未获取到可能影响地图加载。

• 解决方法：
  • 使用permission_handler插件动态请求ACCESS_FINE_LOCATION权限，确保用户授予后再初始化地图
  • 测试时可手动在应用设置中确认位置权限是否已授予。

5. 插件与Flutter版本不兼容 #

你使用的Flutter 3.29.3可能与当前google_maps_flutter插件版本存在兼容性冲突，导致地图渲染失败。

• 解决方法：
  • 查看google_maps_flutter插件文档，确认与Flutter 3.29.3兼容的版本号
  • 更新或降级插件版本到兼容版本，执行flutter pub upgrade或修改pubspec.yaml后重新安装依赖。

6. AndroidManifest.xml重复配置问题 #

你的清单文件中重复添加了flutterEmbedding的meta-data：

<meta-data
    android:name="flutterEmbedding"
    android:value="2" />

虽值相同，但重复配置可能导致解析异常，影响插件初始化。

• 解决方法：
  • 删除其中一个重复的flutterEmbedding配置，保留一个即可。

内容的提问来源于stack exchange，提问作者Muhammad Haddi