Flutter Google Maps插件iOS模拟器仅显示标记地图呈灰色求助

阿华AIGC实验室

2026-5-11

解决Flutter Google Maps在iOS模拟器上地图灰色仅显示标记的问题

嘿，我来帮你排查这个iOS模拟器上地图变灰的问题！结合你提供的代码和配置，我整理了几个最可能的原因和对应的解决方法：

1. 确认Google Maps SDK for iOS已启用

首先，登录你的Google Cloud控制台，检查Maps SDK for iOS服务是否已经启用。很多时候地图变灰就是因为这个SDK没开——你可能只开了Android端的，iOS的忘了启用。

2. 检查API Key的权限和限制

包名（Bundle ID）匹配：确保你在Google Cloud控制台给API Key设置的iOS限制里，Bundle ID和你Xcode项目里的完全一致（比如com.yourcompany.yourapp）。大小写、拼写都不能错！
IP限制问题：如果你的API Key设置了IP地址限制，模拟器的本地IP可能不在允许范围内。可以先暂时移除IP限制测试一下，如果地图能显示了，再把模拟器的IP加进去（或者根据需求调整限制规则）。
确认Key的权限：检查API Key是否拥有Maps SDK for iOS的调用权限，有时候创建Key时没勾选对应的权限也会导致加载失败。

3. 调整AppDelegate中的API Key调用顺序

看你提供的Swift代码，当前是先注册插件再设置API Key，正确的顺序应该是先设置API Key，再注册插件。调整后代码如下：

override func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  GMSServices.provideAPIKey("MY_KEY") // 先设置API Key
  GeneratedPluginRegistrant.register(with: self) // 再注册插件
  return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}

这个顺序问题有时候会导致SDK无法正确读取Key，进而引发地图加载失败。

4. 检查模拟器的网络连接

灰色地图也可能是模拟器没联网，导致无法加载Google的地图瓦片。你可以打开模拟器的Safari，试试访问地图相关站点，如果打不开的话，检查模拟器的网络设置，或者重启模拟器/电脑试试。

5. 补充Info.plist的必要配置

除了io.flutter.embedded_views_preview，建议添加Google Maps所需的位置权限描述（即使你不需要用户的位置，地图加载也可能依赖这个配置），在Info.plist里添加：

<key>NSLocationWhenInUseUsageDescription</key>
<string>需要访问您的位置以显示地图</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>需要访问您的位置以显示地图</string>

虽然不是直接导致地图灰色的原因，但缺少权限可能会引发潜在的加载问题。