针对 Android 和 Firebase 的问题排查及常见问题解答

本页针对在使用 Firebase 时可能会遇到的特定于 Android 的问题提供提示和问题排查方法。

还有其他难题，或是您的问题未在下面列出？请查看Firebase 的主要常见问题解答，详细了解针对整个 Firebase 以及特定产品的常见问题解答。

您还可以查看 Firebase Android SDK GitHub 代码库，获取已报告问题和问题排查的最新列表。同时，我们也鼓励您提交与 Firebase Android SDK 相关的问题。

我收到一条错误消息，指出 ktx 库无法解析或找不到。

出现此错误的原因很可能是您使用了 Firebase BoM 并将 KTX 模块指定为产品库依赖项。

2025 年 7 月，我们停止发布 KTX 模块的新版本，并从 Firebase Android BoM (v34.0.0) 中移除了 KTX 库。

如果您使用之前发布的 KTX 模块中的 KTX API，我们建议您迁移应用以改为使用主模块中的 KTX API。如需了解详情，请参阅关于此计划的常见问题解答。

将 Android 应用添加到 Firebase 项目时，我需要提供 SHA-1 吗？

Firebase Authentication（使用 Google 登录或电话号码登录时）和 Firebase Dynamic Links 需要 SHA-1 信息。如果您未使用这些功能，则无需提供 SHA-1。

我如何解决以下错误：“其他项目中已存在使用此软件包名称和 SHA-1 的 OAuth2 客户端”？

如果我们检测到其他 Firebase 或 Google Cloud 项目中存在使用您指定的软件包名称和 SHA-1 的 OAuth 2.0 客户端 ID，就会发送此错误消息。了解如何解决此错误。

将 Firebase 添加到我的 Android 项目中时，收到一条“找不到”错误消息。

此错误通常表示您的应用缺少对 Google Maven 代码库的一个或多个引用。请务必在 Gradle 配置文件中包含 Google 的 Maven 制品库 (google())。

• 如果您的项目使用的是 plugins 语法，请将其添加到 settings.gradle.kts 或 settings.gradle 文件的 plugins 部分中。
• 如果您的项目使用的是 buildscript 语法，请将其添加到项目级 build.gradle.kts 或 build.gradle 文件的 buildscript 和 allprojects 部分中。

将 Firebase SDK 添加到我的 Android 项目时，我收到了关于调用自定义支持和启用脱糖的错误消息。

2021 年 5 月 (Firebase BoM v28.0.0)，Firebase 停用了其所有 Android 库的脱糖（请参阅版本说明）。

这项变化意味着使用 Android Gradle 插件 (AGP) v4.2 或更早版本的 Gradle 构建需要启用 Java 8 支持。否则，添加 Firebase SDK 时，这些 Android 项目将遇到以下构建失败问题：

D8: Invoke-customs are only supported starting with Android O (--min-api 26)
Caused by: com.android.builder.dexing.DexArchiveBuilderException: Error while dexing.
The dependency contains Java 8 bytecode. Please enable desugaring by adding the following to build.gradle
android {
    compileOptions {
        sourceCompatibility 1.8
        targetCompatibility 1.8
    }
}
See https://developer.android.com/studio/write/java8-support.html for details.
Alternatively, increase the minSdkVersion to 26 or above.

为解决此构建失败问题，您可以采用以下两种方案中的一种：

• 将错误消息中列出的 compileOptions 添加到您的应用级 build.gradle.kts 或 build.gradle 文件中。
• 将 Android 项目的 minSdkVersion 提升到 26 或更高。

当我发布应用后，Google 登录显示错误“12500:”。如何解决此问题？

发生这种情况的原因可能有两种：您尚未提供支持电子邮件地址或缺少 SHA 密钥。如需修复此错误，请确保满足以下所有条件：

• 您在 Firebase 控制台中为项目的常规设置添加了支持电子邮件地址。
• 您在 Firebase 控制台中将发布/生产密钥库中的 SHA-1 证书指纹添加到了 Firebase Android 应用中（前往项目设置，向下滚动到“您的应用”，然后选择您的 Android 应用）。
• 您在 Firebase 控制台中将 Google Play 管理中心内的 SHA-1 证书指纹添加到了 Firebase Android 应用中（前往项目设置，向下滚动到“您的应用”，然后选择您的 Android 应用）。

如何使用 buildscript 语法将 Firebase 插件添加到 Android 项目中？

提示：建议您从 buildscript 语法迁移到 plugin 语法，因为这将允许 Android Studio 执行代码补全并提供其他实用建议。

Firebase 具有以下 Gradle 插件：

插件名称	Maven 坐标	最新版本	插件 ID
Google Play 服务插件	com.google.gms:google-services	4.4.3	com.google.gms.google-services
App Distribution 插件	com.google.firebase:firebase-appdistribution-gradle	5.1.1	com.google.firebase.appdistribution
Crashlytics 插件	com.google.firebase:firebase-crashlytics-gradle	3.0.6	com.google.firebase.crashlytics
Performance Monitoring 插件	com.google.firebase:perf-plugin	2.0.1	com.google.firebase.firebase-perf

将 Firebase 插件添加到仍在使用 buildscript 语法的 Android 项目的方法如下：

1. 在您的根级（项目级）Gradle 文件（<project>/build.gradle.kts 或 <project>/build.gradle）中，使用 Maven 坐标将该插件添加为依赖项：

   Kotlin

   buildscript {
   
       repositories {
         // Make sure that you have the following two repositories
         google()  // Google's Maven repository
         mavenCentral()  // Maven Central repository
       }
   
       dependencies {
         ...
   
         // Add the Maven coordinates and latest version of the plugin
         classpath ("PLUGIN_MAVEN_COORDINATES:PLUGIN_VERSION")
       }
   }
   
   allprojects {
     ...
   
     repositories {
       // Make sure that you have the following two repositories
       google()  // Google's Maven repository
       mavenCentral()  // Maven Central repository
     }
   }
   

   Groovy

   buildscript {
   
       repositories {
         // Make sure that you have the following two repositories
         google()  // Google's Maven repository
         mavenCentral()  // Maven Central repository
       }
   
       dependencies {
         ...
   
         // Add the Maven coordinates and latest version of the plugin
         classpath 'PLUGIN_MAVEN_COORDINATES:PLUGIN_VERSION'
       }
   }
   
   allprojects {
     ...
   
     repositories {
       // Make sure that you have the following two repositories
       google()  // Google's Maven repository
       mavenCentral()  // Maven Central repository
     }
   }
   

2. 在您的模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，使用插件 ID 添加该插件：

   Kotlin

   plugins {
       id("com.android.application")
   
       // Add the ID of the plugin
       id("FIREBASE_PLUGIN_ID")
       ...
   }
   

   Groovy

   plugins {
       id 'com.android.application'
   
       // Add the ID of the plugin
       id 'FIREBASE_PLUGIN_ID'
       ...
   }