Version: 6000.3
语言: 中文
在 Android 设备上调试
模拟 Android 设备

Android 符号

为了帮助您调试应用程序,Unity 可以生成一个包,其中包含带有本机 Unity 库调试元数据的符号文件。符号文件包含一个名为符号表 (.symtab),将活动内存地址转换为您可以使用的信息,例如方法名称。翻译过程称为符号化。您可以将符号包上传到 Google Play 管理中心,以便在 Android Vitals 信息中心上查看人类可读的堆栈跟踪记录。

有关可执行文件 (ELF) 部分的更多信息,请参阅维基百科

Unity 为以下库生成符号文件:

  • libmain:负责初始 Unity 引擎加载逻辑。符号文件是预编译的。

  • libunity:Unity 的引擎代码:

    • 如果禁用了“剥离引擎代码”属性,则会预编译符号文件。
    • 如果启用了 Strip Engine Code 属性,Unity 会在构建过程中编译符号文件。
  • libil2cpp:包含 C#脚本一段代码,允许您创建自己的组件、触发游戏事件、随时间修改组件属性以及以您喜欢的任何方式响应用户输入。更多信息
    请参阅术语表
    :

    • 如果不导出项目,Unity 会在构建过程中编译符号文件。
    • 如果导出项目,Gradle一种 Android 构建系统,可自动执行多个构建过程。这种自动化意味着许多常见的生成错误不太可能发生。更多信息
      请参阅术语表
      编译符号文件。

Gradle 通过剥离.symtab.debug*共享库中的可执行文件部分。如果共享库不包含这些部分,Gradle 将不会为其生成符号文件。

根据应用程序构建格式,Unity 通过两种方式生成符号文件:

  • 作为可以为两者生成的 zip 文件apkaab.
  • 直接将符号文件嵌入到aab.Unity 不会将符号文件嵌入到apk.

使用 UserBuildSettings.DebugSymbols.format API 设置符号包的格式。

符号文件的类型

Unity 使用 Gradle 的 debugSymbolLevel 属性生成符号文件。有两种类型的符号文件:

  • 公共:包含符号表部分的小文件。有关详细信息,请参阅公共符号
  • 调试:包含公共符号文件包含的所有内容,以及可用于更深入调试的完整调试信息。有关详细信息,请参阅调试符号

使用 UserBuildSettings.DebugSymbols.level 生成所需类型的符号文件。

注意:默认情况下,Gradle 生成带有.so.sym.so.dbg扩展。某些数字分发服务无法识别这些扩展名,并且需要文件.so外延。在这种情况下,请使用 Unity.Android.Types.DebugSymbolFormat.LegacyExtensions API 创建带有.so外延。

UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle | DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;

公共符号

公共符号文件包含将函数地址解析为人类可读字符串的信息。这些文件不包含调试信息。这使得公共符号文件小于调试符号文件。

调试符号

调试符号文件包含完整的调试信息和符号表部分。使用它来:

  • 解析堆栈跟踪并调试您有可用源代码的应用程序。
  • 将本机调试器附加到应用程序并调试代码。

注意:如果调试符号不可用,Unity 会在构建时在项目中放置一个公共符号文件。对于libmainlibunity库、调试符号不可用,并且 Unity 始终生成公共文件。

自定义符号

您可以指示 Unity 包含其他符号文件。如果您使用共享库并希望本地调试器和 Google Play 在应用程序崩溃时解析共享库堆栈跟踪,这将非常有用。

要使 Unity 包含自定义符号文件,请执行以下作:

  1. 项目窗口一个窗口,显示您的内容Assets文件夹(项目选项卡)更多信息
    术语表中查看
    ,选择插件在 Unity 外部创建的一组代码,用于在 Unity 中创建功能。可以在 Unity 中使用两种插件:托管插件(使用 Visual Studio 等工具创建的托管 .NET 程序集)和本机插件(特定于平台的本机代码库)。更多信息
    请参阅术语表
    有一个.so文件扩展名。
  2. 检查器一个 Unity 窗口,显示有关当前选定游戏对象、资产或项目设置的信息,允许您检查和编辑值。更多信息
    请参阅术语表
    ,找到平台设置部分。
  3. CPU 设置为符号文件兼容的 CPU 架构。
  4. 共享库类型设置为符号

每当 Unity 生成符号包时,它都会将其他符号文件添加到符号包中。

重要:如果将共享库类型设置为可执行文件,并且共享库包含.symtab.debug*可执行文件部分时,Gradle 会生成一个符号文件,用于覆盖您的自定义符号文件。

如果要使 Unity 包含来自 C# 脚本的自定义符号文件,则 UnityEditor.Android 命名空间包含以下 API,分别用于设置 CPU共享库类型

注意:符号文件名必须与符号文件所针对的共享库的名称匹配。例如,如果共享库名为 mylibrary.so,则符号文件也必须命名为 mylibrary.so。避免文件名碰撞当物理引擎检测到两个游戏对象的碰撞器接触或重叠时,当至少一个游戏对象具有刚体组件并且处于运动状态时,就会发生碰撞。更多信息
请参阅术语表
,符号文件和共享库必须位于单独的目录中。

重要:确保符号文件是最新的,并且与包含可执行代码的共享库兼容。否则,本地调试器和 Google Play 将无法解析共享库中代码的堆栈跟踪。

Inspector 中的自定义插件。
Inspector 中的自定义插件。

生成符号包

有两种方法可以为您的应用程序启用符号包生成:

要通过“构建配置文件”窗口启用符号包生成,请执行以下作:

  1. 打开“构建配置文件”窗口(菜单:“文件”>“构建配置文件”)。

  2. 平台(Platforms) 面板的平台列表中,选择 Android 或为 Android 平台创建构建配置文件

  3. 调试符号(Debug Symbols) 设置为以下选项之一:

  4. 符号输出选项设置为.zip

启用符号包生成后,构建项目会生成一个.zip文件,其中包含libmainlibunity图书馆。如果您将脚本后端为Unity中的脚本提供支持的框架。Unity 支持三种不同的脚本后端,具体取决于目标平台:Mono、.NET 和 IL2CPP。但是,通用 Windows 平台仅支持两个:.NET 和 IL2CPP。更多信息
请参阅术语表
IL2CPP Unity 开发的脚本后端,在为某些平台构建项目时,可以将其用作 Mono 的替代方案。更多信息
请参阅术语表
.zip还包含一个用于libil2cpp图书馆。Unity 将此符号包放置在输出目录中。

如果您在 Android 构建设置中启用 Export Project,Unity 不会构建项目。相反,它会为 Android Studio 导出项目,并为libmainlibunity,并将它们放在unityLibrary/symbols/<architecture>/在输出目录中。当您从 Android Studio 构建导出的项目时,Gradle 会生成libil2cppsymbol 文件并将其放置在unityLibrary/symbols/<architecture>/目录旁边的libmainlibunity符号文件。

在 Google Play 管理中心中使用符号

嵌入符号

如果您要制作 Android App Bundle (aab),则可以将符号直接嵌入到aab并将其上传到 Google Play。

注意:Unity 不会将符号嵌入到apk.在这种情况下,您必须单独上传带有符号的 zip 文件。

UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle;

压缩符号

要生成压缩符号包,请使用以下代码:

UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;

将应用程序上传到 Google Play 后,您可以上传公共符号 zip 包。有关如何执行此作的信息,请参阅 Google 的文档:反混淆或符号化崩溃堆栈跟踪。

注意:Google Play 不会对您的应用在您上传符号包之前收到的崩溃进行符号化表示表示。

在 Android 设备上调试
模拟 Android 设备