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

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

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

使用 Unity 2017.x 及更高版本时的 .NET 兼容性

在 Unity 2017 及更高版本中，Firebase 对 .NET 4.x 的支持是作为一个实验性构建选项提供的。Firebase 插件使用 Parse SDK 的组件来在更早版本的 .NET 中提供某些 .NET 4.x 类。

因此，Firebase Unity SDK 5.4.0 及更高版本在 Firebase Unity SDK 的 dotnet3 和 dotnet4 目录中提供与 .NET 3.x 或 .NET 4.x 兼容的插件。

如果导入与项目中启用的 .NET 版本不兼容的 Firebase 插件，您会发现 .NET 框架中由 Parse SDK 实现的某些类型存在编译错误。

要在使用 .NET 3.x 的情况下解决编译错误，请执行如下操作：

  1. 针对所有平台移除或停用以下 DLL：
    • Parse/Plugins/dotNet45/Unity.Compat.dll
    • Parse/Plugins/dotNet45/Unity.Tasks.dll
  2. 针对所有平台启用以下 DLL：
    • Parse/Plugins/Unity.Compat.dll
    • Parse/Plugins/Unity.Tasks.dll

要在使用 .NET 4.x 的情况下解决编译错误，请执行如下操作：

  1. 针对所有平台移除或停用以下 DLL：
    • Parse/Plugins/Unity.Compat.dll
    • Parse/Plugins/Unity.Tasks.dll
  2. 针对所有平台启用以下 DLL：
    • Parse/Plugins/dotNet45/Unity.Compat.dll
    • Parse/Plugins/dotNet45/Unity.Tasks.dll

如果您导入的是其他 Firebase 插件：

  • 在 Unity 项目中，依次转到 Assets > Play Services Resolver > Version Handler > Update，以便为您的项目启用正确的 DLL。

.NET 4.x 项目中的 Unity 2017.1 IL2CPP 编译

在 Unity 2017 及更高版本中，Firebase 对 .NET 4.x 的支持是作为一个实验性构建选项提供的。Firebase 插件使用 Parse SDK 的组件来在更早版本的 .NET 中提供某些 .NET 4.x 类。

因此，Firebase Unity SDK 5.4.0 及更高版本提供了类型转发 DLL，将 Parse 类型（例如 System.Threading.Tasks.Task 的 Parse 实现）转发到 .NET Framework。遗憾的是，在 Unity 2017.1.x 中提供的 IL2CPP（将 C# 转换为 C++ 的转译器 (transpiler)）无法正确处理类型转发 DLL，因而会导致如下构建错误：

Fatal error in Unity CIL Linker Mono.Cecil.ResolutionException: Failed to
resolve System.Threading.Tasks.TaskCompletionSource`1<T>

Unity 2017.1 中的 .NET 4.x IL2CPP 构建错误目前没有解决办法，因此您必须升级到 Unity 2017.2 或更高版本，才能在通过 IL2CPP 编译的项目中使用 .NET 4.x。

Unity 2017.2 网络

Firebase Realtime Database 通过 .NET 网络堆栈创建 TLS 网络连接。使用 .NET 4.6 时，Unity 2017.2 中的 TLS 功能会受到影响，从而导致 Realtime Database 插件无法在编辑器和桌面上运行。

此问题没有解决方法，因此您必须使用其他版本的 Unity，例如版本 2017.1 或 2017.3。

Unity 2020 中没有 Firebase Android 配置文件

为支持无法自定义 Gradle 构建的 Unity 版本，Firebase 编辑器工具生成了 Assets/Plugins/Android/Firebase/res/values/google-services.xml 作为要封装到 Android 构建中的 Android 资源，以便 Firebase SDK 可使用它来初始化默认的 FirebaseApp 实例。

在 Unity 2020 中，所有 Android 资源都必须位于带 .androidlib 后缀的目录中。如果您的项目使用生成 Assets/Plugins/Android/Firebase 目录的 Firebase SDK，请将其重命名为 Assets/Plugins/Android/Firebase.androidlib。确保它包含 AndroidManifest.xml、project.properties 和 res/values/google-services.xml。

构建 Android 应用时的单个 dex 问题

构建 Android 应用时，您可能会遇到与单个 dex 文件相关的构建失败。如果您的项目配置为使用 Gradle 构建系统，则错误消息类似于以下内容。

Cannot fit requested classes in a single dex file.

Dalvik Executable (.dex) 文件用于保存 Android 应用 (.apk) 的一组类定义及其相关附属数据。单个 dex 文件仅限引用 65,536 种方法。如果项目中所有 Android 库的方法总数超过此限制，构建将会失败。

Unity 在 2017.2 中引入了 Minification，它使用 Proguard（在某些版本的 Unity 中为其他工具）来删除未使用的代码，从而减少单个 dex 文件中引用的方法总数。可在 Player Settings > Android > Publishing Settings > Minify 中找到该选项。选项可能会因 Unity 版本而异，因此请参阅 Unity 官方文档。

如果引用的方法数量仍超过此限制，另一个选项是启用 multidex。可通过以下几种方法在 Unity 中实现这一点：

  • 如果启用了 Player Settings 下的 Custom Gradle Template，请修改 mainTemplate.gradle。
  • 如果您使用 Android Studio 构建导出的项目，请修改模块级 build.gradle 文件。

如需了解详细信息，请参阅 MultiDex 用户指南。

针对 Unity 2017 和 Unity 2018（Firebase Unity SDK 8.0.0 及更高版本）中的 Android build 的 Java 8 支持和脱糖

2021 年 5 月 (Firebase BoM v28.0.0)，Firebase 停用了其所有 Android 库的脱糖（请参阅版本说明）。使用 Firebase Unity SDK（8.0.0 及更高版本）构建 Android 应用时，您可能会看到以下构建错误：

> Error while dexing.
 The dependency contains Java 8 bytecode. Please enable desugaring by adding the following to build.gradle

此变更仅影响 Unity 2017 和 Unity 2018 中的 Android build。默认情况下，较新版本的 Unity 会在 Gradle build 文件中添加 compileOptions 代码块。 如需在 Unity 2017 和 Unity 2018 中修复此构建错误，请执行以下某项操作：

  • 将 compileOptions 块添加到 Gradle 模板：

    1. 使用 Gradle 作为构建系统。
    2. 在 Player Settings 下启用 Custom Gradle Template。

    3. 将以下行添加到 mainTemplate.gradle（如果导出 Android Studio 项目，则添加到模块级 build.gradle）：

      android {
    compileOptions {
        sourceCompatibility 1.8
        targetCompatibility 1.8
    }
}

  • 或者，将 Android 项目的 minSdkVersion 提高至 26 或更大数字。

另请参阅 Android 问题排查 - 对构建失败进行脱糖。

使用 CocoaPods 构建 iOS 应用时遇到的问题

在构建 iOS 应用时，Cocoapod 安装可能会失败，并返回有关语言语言区域或 UTF-8 编码的错误。目前，此问题有几种不同的解决方法。

  • 从终端直接运行 pod install，然后打开生成的 xcworkspace 文件。

  • 将 CocoaPods 版本降级到 1.10.2。该问题仅存在于 1.11 版及更高版本中。

  • 在 ~/.bash_profile 或等效项中，添加 export LANG=en_US.UTF-8

如何更新 Firebase Unity SDK 的版本

更新 Firebase Unity SDK 版本的过程取决于其最初导入的方式。有两种可互相替代的导入方法：

  • 导入项目 Assets/ 目录下的 .unitypackage 文件
  • 使用 Unity Package Manager (UPM) 导入
    • 这是在 Unity 2018.4 及更高版本中管理软件包的推荐方法。
    • 使用此方法可以简化未来的版本更新，并使您的 Assets/ 目录更清晰。

在 Unity 项目中，您应仅使用一种导入方法来管理所有 Firebase 软件包。以下说明不仅可以用于更新各个软件包的版本，还可用于视需要改为使用 UPM（推荐的导入方法）进行软件包管理。