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密钥的
- 校验API密钥本身的可用性
- 确认申请密钥时已经在Google Cloud控制台开启了Maps SDK for Android的服务权限,未开启对应服务的密钥就算配置位置完全正确,也会被SDK判定为无效,触发密钥找不到的报错。
- 如果密钥设置了应用调用限制,需要把当前应用的包名、签名证书的SHA-1指纹添加到密钥的允许调用列表中,不要将密钥限制为仅Web服务调用,否则Android端SDK无法完成鉴权流程。
- 清理构建缓存后重新运行
- 频繁修改Manifest配置后,Gradle和Flutter的构建缓存可能导致实际打包进APK的配置还是旧版本,执行以下操作刷新构建环境:
- 项目根目录运行
flutter clean - 删除项目下
.dart_tool缓存文件夹 - 执行
flutter pub get同步依赖后,重新构建运行应用
- 项目根目录运行
- 频繁修改Manifest配置后,Gradle和Flutter的构建缓存可能导致实际打包进APK的配置还是旧版本,执行以下操作刷新构建环境:
- 排查插件版本兼容问题
- 检查
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
相关产品推荐
相关产品推荐

