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 平台编译

参见

本页面描述的是如何从源码编译 Android 编辑器和导出模板二进制文件。如果你想要将项目导出到 Android，请移步《为 Android 导出》。

注意

对于大多数情况, 使用内置部署程序和导出模板就足够了. 手动编译Android APK对于部署程序的自定义版本或自定义程序包最有用.

此外, 在尝试构建自定义导出模板之前, 你仍然需要按照 为 Android 导出 教程中提到的步骤进行操作.

需求

要在Windows, Linux或macOS下进行编译, 需要以下内容:

  • Python 3.9+。

  • SCons 4.4+ 构建系统。

  • Android SDK

    • 要安装 Android SDK，请按照 here 的步骤操作。

    • 在 Linux 上，请勿使用发行版仓库提供的 Android SDK，因为通常是过时的。

    • 在 macOS 上，请勿使用 Homebrew 提供的 Android SDK，因为安装位置不统一。

  • Gradle（如果缺少，将自动下载并安装）。

  • JDK 17（OpenJDK 或 Oracle JDK）。

    • 你可以从 Adoptium 下载一个构建版本。

参见

关于获取 Godot 源码以便进行编译，请参见 获取源代码。

有关 Godot 的 SCons 用法的一般概述，请参阅 构建系统介绍。

设置构建系统

  • 将环境变量 ANDROID_HOME 设置为指向你的 Android SDK 目录。如果你下载的是 Android 命令行工具（command-line tools），那么这个路径就是你当初解压 ZIP 压缩包后得到的那个文件夹。

    • Windows 用户： Windows + R，输入 "control system"，然后点击左侧面板里的 高级系统设置 ，接着在弹出的窗口中点击 环境变量 。

    • Linux 或 macOS 用户：在你的 .bashrc 或 .zshrc 文件中，添加 export ANDROID_HOME="/path/to/android-sdk" 这行文字。其中， /path/to/android-sdk 需要替换成你电脑上安卓 SDK 根目录的实际路径。

  • 在配置好 SDK 和环境变量之后，请务必 重启你的终端 ，以便让更改生效。如果你使用的是带有集成终端的 IDE，则需要重启整个 IDE。

  • 运行 scons platform=android。如果这一步失败了，请返回去仔细检查前面的步骤。如果你的环境配置完全正确，NDK（安卓原生开发工具包）就会开始自动下载。如果你是想编译 GDExtension（Godot 的 C++ 扩展），你需要先编译一次引擎来触发 NDK 的下载，等下载完成后，再去编译你的 GDExtension。

构建导出模板

Godot 需要三个安卓导出模板：优化后的 "发布版" 模板（android_release.apk）、调试版模板（android_debug.apk）以及 Gradle 构建模板（android_source.zip）。由于 Google 自 2019 年 8 月起要求所有 APK 必须包含 ARMv8（64位/64-bit）库，因此下面的命令将会构建出同时包含 ARMv7 和 ARMv8 库的模板。

编译标准导出模板的方法是在Godot根目录下调用SCons, 参数如下:

  • 发布版模板（在没有勾选 启用调试 （Debugging Enabled）进行导出时使用）

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_android_binaries=yes

  • 调试版模板（在勾选了 启用调试 （Debugging Enabled）进行导出时使用）

scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_android_binaries=yes

生成的模板将位于 bin 目录下：

  • bin/android_release.apk 用于调试版（release ）模板

  • bin/android_debug.apk 用于调试版（debug）模板

  • bin/android_source.zip 用于 Gradle 构建模板

备注

  • 如果你要更改正在构建的架构列表，记得在你要构建的 最后一个 架构中添加 generate_android_binaries=yes，以便在构建后生成模板文件。

  • 如果你想在生成的模板中启用开发构建（dev build，通常在排查故障时使用），只需要在 SCons 命令中加上 dev_build=yes 这个参数即可。

  • 如果想把调试符号（debug symbols）包含在生成的模板中，只需在 SCons 编译命令里加上 debug_symbols=yes 这个参数即可。

    • 请注意，你可以加上 separate_debug_symbols=yes 这个参数，这样调试符号就会被单独生成到一个 *-native-debug-symbols.zip 文件里。

参见

如果你想启用 Vulkan 验证层，请查看： Vulkan validation layers on Android。

添加对 x86 设备的支持

如果你还想加入对 x86 和 x86_64 架构设备的支持，那么在用 Gradle 打包生成 APK 之前，你需要分别加上 arch=x86_32 和 arch=x86_64 这两个参数，把 SCons 编译命令再额外运行两次。举个例子，如果是编译发布版（release）模板的话：

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

这将创建适用于所有平台的模板二进制文件。导出项目的最终二进制文件大小取决于你在导出时选择支持的平台；换句话说，未使用的平台将从二进制文件中移除。

清理生成的导出模板

你可以使用以下命令删除生成的导出模板:

cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

使用导出模板

Godot 需要与编辑器相同版本/提交编译的发布版和调试版二进制文件。如果你使用官方二进制文件作为编辑器，请确保安装匹配的导出模板，或者从相同版本构建自己的模板。

导出游戏时，Godot 使用模板作为基础，并根据需要更新其内容。

安装模板

新编译出来的模板文件（ android_debug.apk 、 android_release.apk 和 android_source.zip ）必须保持它们原本的名字，并复制到 Godot 的模板文件夹中。这个模板文件夹通常位于以下位置：

  • Windows: %APPDATA%\Godot\export_templates\<version>\

  • Linux: $HOME/.local/share/godot/export_templates/<version>/

  • macOS: $HOME/Library/Application Support/Godot/export_templates/<version>/

<version> 的格式应该是 major.minor[.patch].status （也就是 主版本号.次版本号[.补丁号].状态），具体的数值直接参考你 Godot 源码仓库里 version.py 文件中的内容就行（比如 4.1.3.stable 或者 4.2.dev ）。此外，你还需要把这个一模一样的版本字符串，写进一个放在导出模板旁边的 version.txt 文件里。

但是，如果你要编写自定义模块或自定义 C++ 代码，则可能需要将模板二进制文件配置为项目导出菜单中的自定义导出模板。你必须启用 高级选项 才能进行此设置。

../../../_images/andtemplates.webp

你甚至不需要复制它们, 只需引用在Godot源文件夹的 bin\ 目录中生成的文件, 因此下次构建时, 将自动引用自定义模板.

构建 Godot 编辑器

编译编辑器需要在 Godot 的根目录下调用 SCons 来完成，并且需要带上以下的参数：

scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_android_binaries=yes

  • 你可以加上 dev_build=yes 这个参数，来生成一个 Godot 编辑器的开发版（dev build）。

  • 你可以添加 debug_symbols=yes 这个参数，把调试符号包含在生成的构建版本里。

    • 请注意，你可以在编译 最后 一个架构时，在命令里加上 separate_debug_symbols=yes 参数，这样就能把调试符号单独生成到一个名为 *-native-debug-symbols.zip 的压缩文件里。

  • 你可以根据你的目标设备，跳过某些架构的编译，从而加快编译速度。

记得在你要构建的 最后一个 架构中添加 generate_android_binaries=yes，以便在构建后生成二进制文件。

得到的二进制文件在 bin/android_editor_builds/ 中。

移除编辑器二进制文件

可以使用以下命令移除生成的编辑器二进制文件：

 cd platform/android/java
 # On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

安装 Godot 编辑器 APK

在启用了开发者选项的 Android 设备上，通过 USB/USB-C 端口的充电线将 Android 设备连接到你的计算机。打开终端/命令提示符并在根目录使用以下参数运行命令：

adb install ./bin/android_editor_builds/android_editor-android-debug.apk

故障排除

平台未在 SCons 中出现

仔细检查一下，确认你已经设置好了 ANDROID_HOME 环境变量。这是让安卓平台出现在 SCons 检测到的平台列表中的必要条件。更多详细信息，请参见： Setting up the buildsystem 。

应用程序未安装

Android可能会抱怨该应用程序未正确安装. 如果是这样的话:

  • 检查是否正确生成了调试密钥库。

  • 检查jarsigner可执行文件是否来自JDK 8.

如果仍然失败, 请打开命令行并运行 logcat:

adb logcat

然后在安装应用程序时检查输出；错误消息应该在此处显示. 如果无法解决, 请寻求帮助.

应用程序秒退

如果应用程序运行但秒退, 则可能是以下原因之一:

  • 确保使用与你的编辑器版本匹配的导出模板；如果你使用的是新版Godot, 则还 必须 更新模板.

  • libgodot_android.so 这个文件不在 libs/<arch>/ 目录下，其中 <arch> 代表的是设备架构。

  • 设备的体系结构与导出的体系结构不匹配. 确保你的模板是针对该设备的体系结构构建的, 并且导出设置包括对该体系结构的支持.

无论如何, adb logcat 也应显示错误原因.