📚 课程目录第2章 Firebase项目创建与google-services.json集成

第2章 Firebase项目创建与google-services.json集成：控制台配置、Gradle依赖、文件导入

2.1 原理概述

Firebase Cloud Messaging (FCM) 的后台唤醒能力依赖于 Android 应用与 Firebase 项目之间建立的持凭通道。该通道的建立分为两个层面：

项目级绑定： 在 Firebase 控制台创建项目并注册 Android 应用，获得唯一的 google-services.json 配置文件。该文件包含 Firebase 项目的、应用 ID、项目编号等敏感凭据。
应用级注入： 通过 Google Services Gradle 插件，将 google-services.json 中的字段解析到 AndroidManifest.xml 和运行时资源中，使 FCM SDK 能正确向 Firebase 服务器注册推送令牌。

只有完成这两步集成，Android 应用才能接收 FCM 消息并触发后台任务唤醒。下图概括了从控制台到代码的完整集成流程。

2.2 Firebase 控制台配置步骤

访问 Firebase 控制台： 登录 console.firebase.google.com，点击「创建项目」或「添加项目」。
创建项目： 输入项目名称（例如「FCMWakeupDemo」），选择或跳过 Google Analytics（推送场景通常无需 Analytics）。等待项目创建完成。
添加 Android 应用： 在项目概览页点击 Android 图标（</> 形），输入包名（必须与 build.gradle 中 applicationId 一致）。

可选但推荐： 填写调试签名 SHA1 和发布版 SHA1。SHA1 可通过以下命令获取：

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

下载配置文件： 注册完成后，点击「下载 google-services.json」按钮，保存到本地。

提示： 如果项目后续需要使用 Google 登录、动态链接或 Analytics，SHA1 必须提前配置。仅使用 FCM 时，SHA1 非强制，但建议填写以避免后续扩展冲突。

2.3 Gradle 依赖配置

打开项目根目录的 build.gradle（Project 级别），添加 Google Services 插件：

// Top-level build.gradle
buildscript {
    repositories {
        google()  // 必须包含
        mavenCentral()
    }
    dependencies {
        classpath 'com.google.gms:google-services:4.4.2'   // 使用最新稳定版
        // 如果你的项目使用 Kotlin 1.9+，无需额外配置
    }
}

在模块级 build.gradle（app 级别）末尾应用插件并加入 FCM 依赖：

// app/build.gradle
plugins {
    id 'com.android.application'
    id 'com.google.gms.google-services'   // 应用 Google Services 插件
}

dependencies {
    implementation platform('com.google.firebase:firebase-bom:33.5.0')
    implementation 'com.google.firebase:firebase-messaging'   // FCM 核心库
    // 可选：实现后台任务唤醒时需要的工作管理器
    implementation 'androidx.work:work-runtime:2.9.1'
}

版本一致性： 使用 Firebase BoM（Bill of Materials）可自动对齐 FCM 与其他 Firebase 库的版本，避免依赖冲突。建议定期检查 Firebase Android Release Notes 更新 BoM 版本。

2.4 文件导入与同步

放置文件： 将下载的 google-services.json 复制到 app/ 目录下（与 build.gradle 同一级）。
检查文件内容： 确认 google-services.json 中的 package_name 字段与你的应用包名一致，否则构建时会报错。
同步项目： 在 Android Studio 中点击「Sync Now」或运行 ./gradlew assembleDebug。Gradle 执行 google-services 插件时会自动解析 JSON 文件并生成资源。
验证集成： 构建成功后，在 Build/Outputs/apk/debug 中生成 APK，或使用 adb install 安装。应用运行时，调用 FirebaseMessaging.getInstance().getToken() 即可获取 FCM 令牌。

常见错误： 如果构建时出现 File google-services.json is missing 或 Default FirebaseApp is not initialized，请检查文件是否放置在 app/ 目录下，而不是项目根目录。另外，确保模块级 build.gradle 中 com.google.gms.google-services 插件置于文件末尾（在 dependencies 块之后亦可，但插件必须应用）。

2.5 常见错误与调试

错误现象	原因	解决方案
`FCM_ 为 null`	google-services.json 未正确解析，或网络权限未声明	检查文件路径、Gradle 插件版本；确保 AndroidManifest 包含 `INTERNET` 权限
`Default FirebaseApp is not initialized`	应用未正确初始化 FirebaseApp	确认 `com.google.gms.google-services` 插件已应用，并执行了 Sync
`package_name 不匹配`	控制台注册的包名与 app/build.gradle 中 applicationId 不同	重新在 Firebase 控制台添加应用，使用正确的包名
`SHA1 证书指纹验证失败`	调试/发布 APK 签名密钥与 Firebase 注册的 SHA1 不一致	在控制台添加所有使用的签名密钥的 SHA1（调试与发布）

性能与稳定性优化建议：

始终使用 Firebase BoM 统一版本管理，避免子依赖版本冲突导致运行时崩溃。
将 google-services.json 加入 .gitignore？不建议：因为该文件属于构建必需配置，但若仓库公开需注意泄露风险，可考虑使用 Firebase App Distribution 或 CI 环境变量变通。
在 CI/CD 环境中，可以通过 google-services.json 的模板化替换（例如使用 jsonnet 或 envsubst）来管理多环境配置。