构建APK后Google API无法正常工作，求排查解决方案

一、逐步排查步骤 #

• 验证API Key的签名与包名绑定
  登录Google Cloud控制台，找到对应API Key的限制设置：
  1. 确认已添加Release APK的SHA-1指纹（debug和release签名文件生成的SHA-1完全不同，不要只加debug的）
  2. 检查绑定的包名与Release APK的包名完全一致（注意大小写，Android包名区分大小写）
• 确认API服务已启用
  在Google Cloud控制台的「API与服务」→「已启用的API与服务」中，确认你使用的Google API（如Maps、Places等）处于启用状态
• 查看Logcat错误日志
  连接设备或模拟器，过滤包含GoogleApi、AUTH_ERROR、API_NOT_ENABLED、OVER_QUERY_LIMIT的日志，错误信息会直接提示根因（比如密钥不匹配、API未启用、配额耗尽）
• 校验Release APK的签名信息
  使用命令行查看APK的SHA-1：

  apksigner verify --print-certs your-release.apk
  

  或通过Android Studio的「Build」→「Generate Signed Bundle/APK」→「APK」→「Next」查看签名文件的SHA-1，确保与Google Cloud控制台的记录一致
• 检查Manifest配置完整性
  确认Manifest中：
  1. 已添加必要权限（如ACCESS_FINE_LOCATION、INTERNET）
  2. Google API的meta-data标签正确（比如Maps的com.google.android.geo.API_KEY，不要写错name属性）
  3. 已声明Google Play Services的依赖（如<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>）
• 检查API配额与付费状态
  部分Google API有免费配额限制，在Google Cloud控制台的「API与服务」→「配额」中查看是否已超出配额；如果是付费API，确认账号没有欠费

二、常见易忽略陷阱 #

• 签名配置不一致
  Debug和Release构建使用不同的签名文件，很多开发者只在Google Cloud配置了debug的SHA-1，导致Release APK无法通过API密钥验证
• ProGuard/R8隐式优化（即使minify=false）
  即使minifyEnabled=false，R8可能仍会对Google API相关类进行优化，导致反射或动态调用失败，需在proguard-rules.pro中添加对应规则：

  # Google Play Services通用规则
  -keep class com.google.android.gms.** { *; }
  -keep interface com.google.android.gms.** { *; }
  -dontwarn com.google.android.gms.**
  
  # 针对特定API（如Maps）的额外规则
  -keep class com.google.android.gms.maps.** { *; }
  -keep interface com.google.android.gms.maps.** { *; }
  

• API Key的环境区分缺失
  建议在build.gradle中通过buildConfigField为debug和release构建分配不同的API Key，避免混用：

  buildTypes {
      debug {
          buildConfigField "String", "GOOGLE_API_KEY", "\"your-debug-key\""
      }
      release {
          buildConfigField "String", "GOOGLE_API_KEY", "\"your-release-key\""
      }
  }
  

• 网络访问限制
  国内设备需确保能正常访问Google服务；同时检查AndroidManifest中是否添加了INTERNET权限，以及设备是否开启了代理/防火墙拦截Google API请求
• 版本兼容性问题
  确保项目中com.google.android.gms依赖的版本与compileSdkVersion、targetSdkVersion兼容，避免因版本不匹配导致API调用失败
• 后台权限限制（Android 10+）
  如果API需要位置信息，Android 10及以上版本需额外申请ACCESS_BACKGROUND_LOCATION权限，否则后台无法获取位置导致API失效
• 配置生效延迟
  Google Cloud控制台修改API Key配置后，可能需要5-10分钟才能全局生效，修改后不要立即测试，等待配置同步完成

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