Flutter集成Google Play Games登录卡加载报12501错误如何解决？

状态码12501以及伴随的ApiException 4是Google Play Games服务身份校验失败的典型错误，除你已经验证过的app_id、包名、SHA1之外，按照以下优先级排查：

• 检查Google Play Console中Play Games服务的发布状态

  这是最容易被忽略的配置项：进入Google Play Console → 游戏服务 → 选择对应项目 → 检查「测试」标签下是否添加了你当前测试使用的谷歌账号为测试账号。如果项目还未正式发布，只有在测试名单内的账号才能正常登录；如果已经准备上线，需要完成所有必填信息配置后将游戏服务正式发布，未发布的游戏服务仅测试账号可访问。

• 检查OAuth 2.0客户端ID配置

  进入Google Cloud控制台对应项目，确认OAuth 2.0客户端ID列表中，同时存在调试版SHA1和发布版SHA1对应的两条记录，很多开发者仅配置了其中一个，导致对应环境运行时校验失败；同时确认所有客户端ID的包名和你应用的包名完全一致，无拼写错误。

• 检查安卓项目基础配置

  确认安卓项目的build.gradle中已经添加Google Play服务依赖：

  dependencies {
    implementation 'com.google.android.gms:play-services-games:23.1.0'
    implementation 'com.google.android.gms:play-services-auth:20.7.0'
  }
  

  同时确认AndroidManifest.xml中已经添加对应权限和元数据配置：

  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  
  <application ...>
    <meta-data
        android:name="com.google.android.gms.games.APP_ID"
        android:value="@string/app_id" />
    <meta-data
        android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version" />
  </application>
  

• 清理本地缓存重试

  卸载测试设备上的当前应用，清空Play Games应用的缓存和数据，重启设备后重新安装应用测试，部分场景是本地缓存的旧身份信息导致校验失败。

• 优化登录调用逻辑

  建议在调用显性登录前先尝试静默登录，避免重复触发登录流程：

  ElevatedButton(
    child: const Text('Sign In'),
    onPressed: () async {
      try {
        await GamesServices.signInSilently();
      } catch (e) {
        await GamesServices.signIn();
      }
    },
  )
  

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