Flutter安卓应用Google Maps API密钥受限后失效的解决方法

问题核心 #

当API密钥配置Android包名+SHA1限制后，google_maps_flutter（原生地图组件）的请求由Android系统发起，不会走Flutter层的HTTP Headers；而google_place/google_maps_webservice的HTTP请求需要正确传递身份头，两者的配置逻辑不同，不能只靠Flutter层的Headers解决。

分步解决方案 #

1. 确认Google Cloud API密钥的限制配置完全正确 #

登录Google Cloud控制台，找到你的API密钥，检查以下几点：

• 限制类型选择Android应用
• 包名必须与android/app/src/main/AndroidManifest.xml中package属性完全一致（比如com.my.app，大小写敏感）
• SHA1密钥必须是当前使用的签名密钥的SHA1：
  • 调试密钥：执行命令获取

    keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    

  • 发布密钥：用你打包的keystore文件执行相同命令，注意区分调试和发布环境的密钥
• 确保已启用所需API：Maps SDK for Android、Places API（Autocomplete属于Places API的子服务）

2. 配置google_maps_flutter的原生Android参数 #

google_maps_flutter的地图加载请求是原生发起的，不需要Flutter层配置Headers，只需在AndroidManifest中正确配置API密钥：
打开android/app/src/main/AndroidManifest.xml，在<application>标签内添加：

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="你的Google Maps API密钥"/>

确保这个配置没有遗漏，且API密钥的限制规则与当前应用的包名、签名SHA1匹配。

3. 修正google_place/google_maps_webservice的Headers配置 #

这两个包通过HTTP请求调用API，必须传递正确的身份头，注意以下细节：

• SHA1格式必须是冒号分隔的大写十六进制字符串（比如AA:BB:CC:DD:...，不能有空格、小写或其他格式）
• 避免覆盖Headers，用addAll而非直接赋值：

  Map<String, String> headers = {};
  final targetPlatform = defaultTargetPlatform;
  
  if (targetPlatform == TargetPlatform.android) {
    headers.addAll({
      'x-android-package': ENV.package, // 与AndroidManifest的package完全一致
      'x-android-cert': ENV.SHA1, // 正确格式的SHA1
    });
  } else if (targetPlatform == TargetPlatform.iOS) {
    headers.addAll({
      'x-ios-bundle-identifier': Env().bundleIdentifier,
    });
  }
  
  // 初始化GooglePlace实例
  googlePlace = GooglePlace(URLConstants.googleMapApiKey, headers: headers);
  

• 如果单独使用google_maps_webservice，也要传递相同Headers：

  final placesService = GoogleMapsPlaces(
    apiKey: URLConstants.googleMapApiKey,
    headers: headers,
  );
  

4. 调试与验证 #

• 查看Google Cloud控制台的API密钥使用统计，检查是否有API_KEY_INVALID或API_KEY_RESTRICTED的错误日志，定位具体问题
• 用抓包工具（如Charles、Proxyman）检查HTTP请求是否携带了正确的x-android-package和x-android-cert头
• 临时移除API密钥的限制，确认功能正常后再逐步添加限制，排查哪一步配置出错

5. 常见坑点规避 #

• 混淆配置：如果开启了代码混淆，在android/app/proguard-rules.pro中添加规则避免Google类被混淆：

  -keep class com.google.android.gms.** { *; }
  -keep class com.google.maps.** { *; }
  

• 调试/发布密钥混淆：测试时用调试密钥，发布时用发布密钥，确保两个密钥都添加到API密钥的限制列表中
• 包名大小写：Android包名区分大小写，必须与Google Cloud配置的完全一致

内容的提问来源于stack exchange，提问作者Arnab Ghosh