Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

解决 Android 系统上的崩溃问题

当你的游戏在安卓平台上发生崩溃时，你通常会在 Play 管理中心或其他崩溃报告工具（例如 Firebase Crashlytics）中看到模糊不清的堆栈跟踪信息。为了使这些堆栈跟踪信息更易于阅读（符号化），你需要与游戏导出版本对应的原生调试符号（native debug symbols）。

Godot 现在为每个官方导出模板提供可下载的原生调试符号。

获取官方模板的原生调试符号

每个稳定版的 Godot 都提供了原生调试符号文件，可以从 GitHub 发布页面 下载。

例如，要获取版本 4.5.1.stable 的原生调试符号：

获取自定义构建的原生调试符号

导出的模板及其原生调试符号必须来自 同一构建版本 ，因此只有在使用 官方导出模板 时才能使用官方符号。如果你构建的是 自定义导出模板 ，则需要自行生成匹配的符号文件。

为此，请在 scons 构建命令中添加 debug_symbols=yes separate_debug_symbols=yes 。这将生成一个名为 android- template -release-native-symbols.zip 的文件，其中包含自定义构建的原生调试符号。

例如，

scons platform=android target=template_release debug_symbols=yes separate_debug_symbols=yes generate_android_binaries=yes

如果你为多个架构构建，应该仅在最后一个构建命令中包含 separate_debug_symbols=yes，类似于使用 generate_android_binaries=yes 的方式。

scons platform=android arch=arm32 target=template_release debug_symbols=yes
scons platform=android arch=arm64 target=template_release debug_symbols=yes
scons platform=android arch=x86_32 target=template_release debug_symbols=yes
scons platform=android arch=x86_64 target=template_release debug_symbols=yes separate_debug_symbols=yes generate_android_binaries=yes

将符号上传到 Google Play Console

按照以下步骤上传原生调试符号：

  1. 打开 Play Console。

  2. 选择任一 app。

  3. 在左侧菜单中，导航到 Test and release > Latest releases and bundles。

../../../_images/play_console_latest_release_bundles.webp

  1. 现在选择相关的 bundle 并打开它。

../../../_images/play_console_latest_release_bundles2.webp

  1. 选择 Downloads 标签页，然后向下滚动到 Assets 部分。

../../../_images/play_console_app_bundle_explorer.webp

  1. 在 Native debug symbols 旁边，点击上传箭头图标。

../../../_images/play_console_app_bundle_explorer2.webp

  1. 选择并上传对应构建版本的原生调试符号文件。

../../../_images/play_console_upload_native_debug_symbols.webp

或者，你也可以在创建新版本时上传符号：

  1. 在创建发布页面，找到你新发布的 bundle。

../../../_images/play_console_create_new_release.webp

  1. 点击旁边三个点样式的菜单。

  2. 从菜单中选择 Upload native debug symbols (.zip)。

../../../_images/play_console_create_new_release2.webp

  1. 选择并上传对应构建版本的原生调试符号文件。

手动符号化崩溃日志

你也可以使用 Android NDK 中包含的 ndk-stack 工具手动符号化崩溃日志。

备注

如果你已经安装了 Android SDK，可以在 SDK 安装目录中的 ndk 文件夹里找到 ndk-stack 工具。否则，你可以直接从 NDK 下载页面 下载 NDK。

  1. 解压你之前下载的原生调试符号 zip 文件（或使用自定义构建生成的文件）。

  2. 将崩溃日志保存为文本文件（例如，crash.txt）。

重要

ndk-stack 在解析崩溃日志时会查找以星号开头的行。确保你的 crash.txt 以以下内容开头：

*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

  1. 使用与崩溃的 CPU 架构匹配的符号目录路径（例如，arm64-v8a）运行 ndk-stack：

ndk-stack -sym path/to/native_debug_symbols/arm64-v8a/ -dump crash.txt

  1. 输出将显示符号化的堆栈跟踪，展示 Godot 源代码（或你的自定义构建）中的文件名和行号。