调试游戏构建、安装和运行流程

简介

以下指南介绍了如何使用 Firebase SDK for Unity 调试 Unity 游戏的编译和构建流程。此外，它还介绍了如何调查和解决您在为新平台配置和构建游戏时或在更新后可能会遇到的许多常见问题。它是按照流程中可能发生这些错误的时间顺序来撰写的。请按顺序参阅这些错误，并在消除每个错误后继续阅读指南。

除本文档外，您还可以参阅 Firebase for Unity 常见问题解答，了解更多信息。

玩游戏模式编译问题

在您尝试启动移动构建之前，在编辑器中进行测试时可能会出现第一类构建问题。本部分涉及在玩游戏模式之前和玩游戏模式期间出现的所有 Firebase 错误。

Unity 在启动或检测依赖项、代码或其他资产的变化时，会尝试重新构建项目。如果当时项目无法编译，编辑器会将编译错误记录到控制台；如果您尝试进入玩游戏模式，则会在 Unity 的 Scene（场景）标签页中看到一条弹出式错误消息，该消息显示“All compiler errors have to be fixed before you can enter playmode!”（在进入玩游戏模式之前，必须修复所有编译器错误！）。

调试与 Firebase 相关的编译问题

缺少类型、类、方法和成员

出现许多 Firebase 问题是因为编辑器和编译器找不到必需的类型、类、方法和成员。常见的症状有以下几种：

The type or namespace name ‘<CLASS OR NAMESPACE NAME>' could not be found. Are you missing a using directive or an assembly reference?

The type or namespace name <TYPE OR NAMESPACE NAME> does not exist in the namespace ‘Firebase<.OPTIONAL NESTED NAMESPACE NAME PATH>' (are you missing an assembly reference?)

‘<CLASS NAME>' does not contain a definition for ‘<MEMBER VARIABLE OR METHOD NAME>'

解决步骤：

1. 在代码中使用 Firebase 类或方法时，请为所需的特定 Firebase 产品提供正确的 using 指令，以确保这些类或方法可供使用。

   1. MechaHamster: Level Up With Firebase Edition 示例：
      1. using Firebase.RemoteConfig;
      2. using Firebase.Crashlytics;

2. 验证您是否已导入相应的 Firebase 软件包：

   1. 如需导入相应的软件包，请执行以下任一操作：
      1. 将 Firebase Unity SDK 添加为 .unitypackage 或
      2. 查看并执行其他 Unity 安装选项中的替代方案之一。
   2. 确保项目中的每个 Firebase 产品以及 EDM4U 符合以下条件：
      • 版本相同
      • 完全作为 .unitypackage 安装或完全通过 Unity Package Manager 安装。

3. 如果您已将版本“10.0.0”之前的 Firebase Unity SDK 作为 .unitypackage 导入，则 Firebase Unity SDK zip 归档文件包含支持 .NET 3.x 和 .NET 4.x 的软件包。确保您只在项目中添加了兼容的 .NET Framework 级别：

   1. 将 Firebase 添加到您的 Unity 项目中介绍了 Unity Editor 与 .NET Framework 级别的版本之间的兼容性。
   2. 如果您不小心在错误的 .NET Framework 级别导入了 Firebase 软件包，或者需要从使用 .unitypackage 改为使用其他 Unity 安装选项之一，较简洁的方法是通过此迁移部分中提到的方法移除每个 Firebase 软件包，然后再次重新导入所有 Firebase 软件包。

4. 检查编辑器是否正在重新构建您的项目，以及您玩游戏的尝试是否反映了项目的最新状态：

   1. 默认情况下，只要检测到资产或配置更改，Unity Editor 就会设置为重新构建。
   2. 此功能可能已停用，并且 Unity Editor 可能已设置为手动刷新/重新编译。请查看这一情况，如果出现这种情况，请尝试进行手动刷新。

玩游戏模式运行时错误

如果您的游戏可以启动，但在运行期间遇到 Firebase 问题，请尝试以下操作：

确保在 Mac OS 上批准“隐私与安全性”中的 Firebase 软件包

如果在 Mac OS 上的编辑器中启动游戏时系统显示“FirebaseCppApp-<version>.bundle Cannot be opened because the developer cannot be verified.”（FirebaseCppApp-<version>.bundle 无法打开，因为无法验证开发者。）对话框，则您必须在 Mac 的“隐私与安全性”菜单中批准该特定的软件包文件。

为此，请点击 Apple 图标 > 系统偏好设置 > 隐私与安全性

在安全性菜单中，大约在页面中间位置，有一个部分这样写着：“"FirebaseCppApp-<version>.bundle" was blocked from use because it is not from an identified developer.”（“FirebaseCppApp-<version>.bundle”被禁止使用，因为它不是来自所标识的开发者。）

点击 Allow Anyway（仍然允许）按钮。

注意：请勿批准此类文件，除非您信任相应来源或自行编写相关文件，并了解文件的用途以及系统为文件添加标记的原因。

返回 Unity，然后再次按 Play（玩游戏）。

然后，您会看到类似于第一条消息的警告：

按 Open（打开），您的程序将能够继续运行；系统将不会再次向您询问此特定文件。

确保您的项目包含并使用有效的配置文件

1. 务必在 File（文件）> Build Settings（构建设置）中为您的预期目标（iOS 或 Android）设定构建设置。如需了解更完整的讨论内容，请参阅 Unity Build Settings（构建设置）文档。
2. 从 Firebase 控制台的项目设置 > 您的应用中下载应用的配置文件（对于 Android 为 google-services.json；对于 iOS 为 GoogleService-Info.plist）并构建目标：如果您已经有这些文件，请在项目中将其删除，并将其替换为最新版本，确保其拼写与上面显示的拼写完全一致（文件名不带“(1)”或其他数字）。
3. 如果控制台包含关于 Assets/StreamingAssets/ 中的文件的消息，请确保没有任何控制台消息指出 Unity 无法修改文件
4. 请确保 Assets/StreamingAssets/google-services-desktop.json 已生成并且与下载的配置文件匹配。
   • 如果它不是自动生成的且 StreamingAssets/ 不存在，请在 Assets 目录中手动创建此目录。
   • 检查 Unity 现在是否已生成 google-services-desktop.json。

确保每个 Firebase 产品和 EDM4U 都完全通过 .unitypackage 或 Unity Package Manager 安装

1. 检查 Assets/ 文件夹和 Unity Package Manager，确保 Firebase SDK 和 EDM4U 完全由其中一种方法安装。
2. 一些 Google 开发的插件（例如 Google Play）和第三方插件可能依赖于 EDM4U。这些插件可能会在其 .unitypackage 或 Unity Package Manager (UPM) 软件包中包含 EDM4U。确保您的项目中只有一个 EDM4U 副本。如有任何 UPM 软件包依赖于 EDM4U，最好仅保留 EDM4U 的 UPM 版本，这些版本可在 “适用于 Unity Archive 的 Google API”页面中找到。

确保项目中的每个 Firebase 产品都是相同的版本。

1. 如果 Firebase SDK 是通过 .unitypackage 安装的，请检查 Assets/Firebase/Plugins/x86_64/ 下的所有 FirebaseCppApp 库是否为相同的版本。
2. 如果 Firebase SDK 是通过 Unity Package Manager (UPM) 安装的，请打开 Windows（窗口）> Package Manager，搜索“Firebase”，并确保所有 Firebase 软件包都是相同的版本。
3. 如果您的项目包含不同版本的 Firebase SDK，我们建议您先完全移除所有 Firebase SDK，然后再重新安装所有 Firebase SDK，这次请使用相同的版本。较简洁的方法是通过此迁移部分中提及的方法移除每个 Firebase 软件包。

解析器和目标设备构建错误

如果您的游戏可在编辑器中运行（针对您选择的相应构建目标进行配置），接下来请验证 External Dependency Manager for Unity (EDM4U) 是否已正确配置并正常运行。

注意：您将在 Unity Firebase 设置流程中添加 EDM4U。

EDM4U GitHub 代码库包含这部分流程的分步指南，您应该先查看并遵循该指南，然后再继续操作。

“单个 Dex”问题和缩减大小（如果使用 Cloud Firestore，则必须缩减大小）

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

Cannot fit requested classes in a single dex file.

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

您可以执行以下两个步骤；先缩减大小，如果还不能解决问题时，再启用 MultiDex。

启用 Minification

Unity 在 2017.2 中引入了 Minification，以删除未使用的代码，从而减少单个 dex 文件中引用的方法总数。* 可在 Player Settings（玩家设置）> Android > Publishing Settings（发布设置）> Minify（缩减大小）中找到该选项。* 选项可能会因 Unity 版本而异，因此请参阅 Unity 官方文档。

启用 MultiDex

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

• 如果启用了 Player Settings（玩家设置）下的 Custom Gradle Template（自定义 Gradle 模板），请修改 mainTemplate.gradle。
• 如果您使用 Android Studio 构建导出的项目，请修改模块级 build.gradle 文件。

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

了解并修复目标设备运行时错误

如果您的游戏可以在编辑器中运行，并且能够针对目标设备进行构建以及安装到目标设备，但您却遇到运行时错误，请检查并调查设备上生成的日志。

此部分详细介绍了调查日志中可能存在错误的方法，以及一个仅在设备或模拟器上运行时发生的此类错误。

Android

模拟器

• 检查模拟器控制台中显示的日志，或查看 Logcat 窗口。

设备

熟悉 adb 和 adb logcat 以及使用方法。

• 虽然可以使用命令行环境的各种工具来过滤输出，但请考虑查看 Logcat 的选项。

• 启动干净状态的 ADB 会话的一种简单方法如下：

  adb logcat -c && adb logcat <OPTIONS>

  其中 OPTIONS 是您传递给命令行以过滤输出的标志。

通过 Android Studio 使用 Logcat

通过 Android Studio 使用 Logcat 时，可以使用更多搜索工具，这样可以更简单地执行高效的搜索。

iOS

检查日志

如果您运行的是实体设备，请将其连接到计算机。在 Xcode 中检查 lldb。

Swift 问题

如果您看到提及 swift 的错误日志，请参阅关于这些日志的 External Dependency Manager for Unity 部分。

后续步骤

如果您的游戏仍然存在与 Firebase 相关的编译、构建或运行问题，请参阅“Firebase SDK for Unity 问题”页面并考虑提交新问题。此外，请参阅 Firebase 支持页面，了解其他选项。