You need to enable JavaScript to run this app. Flutter集成Google Maps时报PlatformException:API密钥未找到
优惠活动
大模型
产品
解决方案
定价
更多

Flutter集成Google Maps时报PlatformException:API密钥未找到

异常核心原因

这是Android端Google Maps SDK初始化时,未读取到合法、可用的API密钥触发的运行时异常,按以下顺序逐一排查即可定位解决:

排查修复步骤
  • 检查AndroidManifest.xml的配置位置正确性
    • 存放API密钥的<meta-data>标签必须是<application>标签的直接子节点,不能嵌套在<activity>、<intent-filter>等其他标签内部,嵌套位置错误会导致SDK完全扫描不到这个配置项。
    • 标签的android:name属性必须严格匹配固定值com.google.android.geo.API_KEY,不能使用旧版地图SDK的com.google.android.maps.v2.API_KEY这类过期命名,否则SDK无法识别到密钥配置。
    • 正确配置参考示例:
      <application
          android:label="你的应用名"
          android:icon="@mipmap/ic_launcher">
          <!-- 必须放置在application标签的直接子级 -->
          <meta-data
              android:name="com.google.android.geo.API_KEY"
              android:value="你从Google Cloud控制台申请的实际API密钥"/>
          <!-- 其他Activity、服务等组件配置 -->
      </application>
      
  • 校验API密钥本身的可用性
    • 确认申请密钥时已经在Google Cloud控制台开启了Maps SDK for Android的服务权限,未开启对应服务的密钥就算配置位置完全正确,也会被SDK判定为无效,触发密钥找不到的报错。
    • 如果密钥设置了应用调用限制,需要把当前应用的包名、签名证书的SHA-1指纹添加到密钥的允许调用列表中,不要将密钥限制为仅Web服务调用,否则Android端SDK无法完成鉴权流程。
  • 清理构建缓存后重新运行
    • 频繁修改Manifest配置后,Gradle和Flutter的构建缓存可能导致实际打包进APK的配置还是旧版本,执行以下操作刷新构建环境:
      • 项目根目录运行flutter clean
      • 删除项目下.dart_tool缓存文件夹
      • 执行flutter pub get同步依赖后,重新构建运行应用
  • 排查插件版本兼容问题
    • 检查pubspec.yaml中google_maps_flutter的版本,过旧的插件版本对应的底层SDK逻辑和当前设备的Google Play服务版本不匹配时,也会出现密钥读取失败的误报,建议升级到稳定版的最新插件版本,避免使用未稳定的测试分支版本。
  • 检查Manifest的配置作用域
    • 注意区分app/src/main/AndroidManifest.xml、app/src/debug/AndroidManifest.xml、app/src/release/AndroidManifest.xml三个文件的作用域,如果仅在debug目录的Manifest中配置了密钥,release构建时就会出现密钥缺失的问题,建议把通用的API密钥配置放在main目录的公共Manifest中,保证两种构建模式都能读取到。

内容的提问来源于stack exchange,提问作者hamza yunus bolat

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.29 21:27:07