Flutter Google Sign-In 完整集成指南

记录 Flutter 项目中接入 Google 登录的完整过程。从 Firebase 控制台配置到代码实现，希望你少踩点坑。

使用的插件是官方的 **google_sign_in**，这个插件底层依赖 Firebase 认证服务。

---

前置准备

开始之前，确保你有：

• 一个可用的 Google 账号
• 你的 Flutter 项目已经创建好
• 知道项目的包名（Android 是 applicationId，iOS 是 Bundle Identifier）

我的示例项目包名：

• Android: com.kele.best
• iOS: com.kele.best

---

第一步：注册 Firebase 账号

打开 Firebase 控制台，用 Google 账号登录。第一次使用需要接受一些服务条款，按照提示走就行。

---

第二步：创建 Firebase 项目

登录后点击「创建项目」：

给项目起个名字，比如 MyFlutterApp，然后一路下一步完成创建。

---

第三步：在项目中添加应用

进入项目后，我们需要分别添加 Android 和 iOS 两个应用。

点击项目概览页面上的图标，开始添加应用：

3.1 添加 Android 应用

选择 Android 图标，填写应用信息：

• Android 软件包名称：填你项目的 applicationId，在 android/app/build.gradle 里能找到
• 应用别名：随便填，自己认得就行
• 调试签名证书 SHA-1：这个很重要，后面细说

填完点击「注册应用」。

关于 SHA-1 证书指纹

Google 登录必须要 SHA-1，调试和发布版本都需要。获取方式：

# Mac/Linux 调试证书默认位置
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# 如果你用的是自定义签名
keytool -list -v -keystore <你的.jks文件路径>

输出结果里找到 SHA1 那一行，复制过来填进去。

注意：如果你要发布到 Google Play，还需要填 Play 商店签名的 SHA-1，在 Play 控制台里能找到。

注册完成后，会让你下载 google-services.json。如果你只用 Google 登录功能，这个文件其实不是必须的。但建议还是下载下来，后面可能会用到其他 Firebase 服务。

下载后把文件放到 android/app/google-services.json。

配置 Android 项目设置

注册完应用后，去项目设置里添加 SHA-1：

把调试和发布的 SHA-1 都加进去，每个 SHA-1 对应一个 OAuth 客户端 ID。

3.2 添加 iOS 应用

回到项目概览，点击添加 iOS 应用：

• Apple 软件包 ID：填你项目的 Bundle Identifier，在 Xcode 里或者 ios/Runner.xcodeproj/project.pbxproj 里能找到
• 应用别名：随便填
• App Store ID：如果还没上架，可以先不填

点击「注册应用」后，会提示下载 GoogleService-Info.plist 文件。这个文件需要放到 ios/Runner/ 目录下。

然后在 Xcode 里打开项目，右键点击 Runner 文件夹 → Add Files to “Runner”，选择刚才下载的 plist 文件，确保勾选「Copy items if needed」。

---

第四步：配置 OAuth 权限请求页面

这是最容易踩坑的地方。打开 Google Cloud 控制台，左上角切换到你在 Firebase 创建的项目，如果找不到，试试看看[全部]选项。

4.1 配置 OAuth 权限请求页面

然后点击左侧菜单「OAuth权限请求页面」，配置你的项目信息；：

• 应用名称：填你的应用名
• 用户支持电子邮件：选你的邮箱
• 开发者联系信息：填你的邮箱

保存后进入「凭据」页面，你应该能看到几个 OAuth 2.0 客户端 ID：

• Web 客户端（自动创建的）
• Android 客户端（如果你填了 SHA-1）
• iOS 客户端（自动创建的）

如果 Android 客户端没有自动创建，可以手动添加，类型选「Android」。

---

第五步：安装插件并配置

5.1 添加依赖

在 pubspec.yaml 里添加(版本以新的为准)：

dependencies:
  google_sign_in: ^6.2.1

然后运行 flutter pub get。

5.2 Android 配置

确保 android/app/build.gradle 里的 minSdkVersion 至少为 21：

android {
    defaultConfig {
        minSdkVersion 21
        // ...
    }
}

5.3 iOS 配置

在 ios/Runner/Info.plist 里添加 URL Scheme 配置：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <!-- 这里的值是你在 Firebase 里 iOS 应用的 REVERSED_CLIENT_ID -->
            <!-- 可以在 GoogleService-Info.plist 里找到 -->
            <string>com.googleusercontent.apps.xxxxxxx</string>
        </array>
    </dict>
</array>

---

第六步：代码实现

基础登录代码

import 'package:google_sign_in/google_sign_in.dart';

//google登录
final GoogleSignIn googleSignIn = GoogleSignIn(scopes: ['email']);

void googleLogin() async {
    GoogleSignInAccount? googleResult = await googleSignIn.signIn();
    if (account != null) {
      print('登录成功: ${account.displayName}');
      print('邮箱: ${account.email}');
      print('头像: ${account.photoUrl}');
    }
}

处理切换账号的需求

Google 账号会保持登录状态一段时间，如果你想每次点击都弹出账号选择框（方便切换账号）：

void googleLoginWithSwitch() async {
  // 先检查是否已登录
  bool isSignedIn = await _googleSignIn.isSignedIn();
  
  if (isSignedIn) {
    // 先退出当前账号
    await _googleSignIn.signOut();
  }
  
  // 再调用登录，就会弹出账号选择框
  GoogleSignInAccount? account = await _googleSignIn.signIn();
  print(account);
}

获取用户信息

登录成功后，可以获取到这些信息：

属性	说明
displayName	用户显示名称
email	用户邮箱
id	Google 用户唯一 ID
photoUrl	用户头像 URL
serverAuthCode	服务端授权码（用于后端验证）

Future<void> signInAndVerifyWithServer() async {
  final account = await _googleSignIn.signIn();
  if (account != null) {
    final auth = await account.authentication;
    
    // 把 idToken 或 serverAuthCode 传给后端
    final idToken = auth.idToken;
    final serverAuthCode = account.serverAuthCode;
    
    // 调用你的后端 API 进行验证
    // await yourBackendApi.verifyGoogleToken(idToken);
  }
}

---

遇到的问题

问题一：Android 报错 ApiException: 10

错误信息：

PlatformException(sign_in_failed, com.google.android.gms.common.api.ApiException: 10: , null, null)

这个报错我折腾了好几个小时。一开始以为是 SHA-1 配置有问题，反复重新生成证书、重新配置，都没用。

后来在 GitHub 上搜到 Issue #33393，提到 OAuth 配置的问题。我检查了 OAuth 权限请求页面，该填的都填了。

最后发现是 OAuth 凭据里没有自动创建 Android 客户端 ID：

图上那个 Android 是我后来手动加的。iOS 和 Web 都是自动创建的，但 Android 不知道为什么没有。手动添加一个类型为「Android」的 OAuth 2.0 客户端 ID 后，问题就解决了。

奇怪的是：我把 Firebase 里 Android 应用的 SHA-1 全删了，竟然还能正常登录。可能是 OAuth 凭据一旦创建就独立存在了。不过为了保险，我还是把 debug 和 release 的 SHA-1 都配置上了。

后来新建其他应用时，发现只要填了 SHA-1，Android 的 OAuth 客户端 ID 是会自动创建的。看来那次只是个偶然的 bug，希望你们别遇到。

问题二：iOS 登录后白屏

检查 Info.plist 里的 URL Scheme 是否配置正确，特别是 REVERSED_CLIENT_ID 的值要和 GoogleService-Info.plist 里的一致。

问题三：Release 包无法登录

确保 release 版本的 SHA-1 也添加到 Firebase 项目设置里了。如果你用 Google Play 的签名，要去 Play 控制台找签名指纹。

---

参考链接：

• google_sign_in 插件文档
• Firebase 官方文档