Gradle for Android

Gradle 是一种 Android 构建系统，可自动执行许多构建过程并预防许多常见的构建错误。在 Unity 中，Gradle 可减少 DEX（Dalvik 可执行文件格式）文件中的方法引用数量，这意味着可降低遇到 DEX 限制问题的可能性。

Unity 将 Gradle 用于所有 Android 构建。可以在 Unity 中构建输出包（.apk、.aab），也可以从 Unity 导出 Gradle 项目，然后通过外部工具（如 Android Studio）进行构建。

Unity 版本	Gradle 版本
2020.3 始自 2020.3.15f1	6.1.1
2020.1、2020.2、2020.3 直至并包含 2020.3.14f1	5.6.4
2019.4	5.1.1

了解更多相关信息：

• Gradle，请参阅 Gradle 用户手册。
• 构建输出包 (.apk)，请参阅 Android 开发者文档中有关配置构建的部分。
• 构建输出包 (.aab)，请参阅 Android 开发者文档中有关 Android 应用程序捆绑包的部分。

构建或导出 Gradle 项目

要构建 Gradle 项目，请执行以下步骤：

1. 在 Unity Editor 中，打开项目的 Build Settings 窗口（菜单：File > Build Settings）。
2. 在 Platform 列表中，确保将 Android 选为构建目标。如果 Android 不是当前构建目标，请在 Platform 列表中选择 Android，然后选择 Switch Platform 按钮。

选择：

• Build 按钮，用于生成 .apk 文件。
• Build and Run 按钮，用于生成 .apk 文件，将其部署到连接的设备，然后运行。

要将 Unity 项目导出为 Gradle 项目，请启用 Export Project 设置，然后选择 Export 按钮。进行此操作后，Unity 会在指定文件夹中生成 Gradle 项目，不会构建 .apk 文件。将此项目导入 Android Studio 或另一外部工具以进行进一步修改或在其中进行构建。

导出的 Gradle 项目结构

Unity 2019.3 和更高版本所创建的 Gradle 项目具有两个模块：

• UnityLibrary 模块：包含 Unity 运行时和项目数据。该模块是可以集成到其他任何 Gradle 项目中的一种库。这个模块可以用于将 Unity 嵌入现有的 Android 应用程序中。
• Launcher 模块：包含应用程序的名称及其所有图标。这是一个可启动 Unity 的简单 Android 应用程序模块。您可以将其替换为自己的应用程序。

build.gradle 模板

Gradle 模板描述并配置如何使用 Gradle 来构建 Android 应用程序。每个 Gradle 模板代表一个 Gradle 项目。Gradle 项目可以包括和依赖于其他 Gradle 项目。

Gradle 模板包含以下文件：

文件	位置	包含
baseProjectTemplate.gradle	在导出的项目中，root/build.gradle 文件夹	所含的配置会在其他所有模板/Gradle 项目之间共享（代码仓库以及对 Android Gradle 插件的依赖关系）。
launcherTemplate.gradle_	在导出的项目中，root/launcher/build.gradle 文件夹	包含有关如何构建 Android 应用程序的指令（捆绑、签名、APK 拆分）。它依赖于 unityLibrary 项目并输出 .apk 文件或应用程序捆绑包。
mainTemplate.gradle	在导出的项目中，root/unityLibrary/build.gradle 文件夹	包含关于如何将 Unity 构建为库的指令。输出 .aar 文件。在 Unity 编辑器中，可以用自定义模板来覆盖 Unity 模板。请参阅本页的提供自定义 Gradle 构建模板部分以了解更多详细信息。
libTemplate.gradle	因情况而异	如果 Unity 项目包含 Android 库项目作为插件，则会使用此文件。

自定义 Gradle 构建

在 Player Settings 窗口的 Publishing Settings 部分中可以提供自定义 Gradle 构建模板并选择缩小选项。

提供自定义 Gradle 构建模板

从 Unity 构建 APK 时，可以将自定义 build.gradle 文件用于 unityLibrary 模块。该文件包含 template variables 中指定的特定构建指令。有关模板变量的列表，请参阅下一部分。

要将您自己的 build.gradle 文件用于 unityLibrary 模块，请执行以下操作：

1. 在 Unity 编辑器中，打开 Player Settings 窗口（菜单：Edit > Project Settings > Player），然后选择 Android。
2. 在 Publishing Settings 部分中，启用 Custom Gradle Template 设置。

随后，Unity 在项目的 Assets/Plugins/Android/ 文件夹中生成默认的 mainTemplate.gradle 文件。新文件的路径也显示在 Player Settings 中的 Custom Main Gradle Template 选项之下。双击 Project 视图中的 mainTemplate.gradle 文件，从而在外部文本编辑器中打开此文件。

!Project 视图中，unityLibrary 模块的 mainTemplate.gradle 文件

默认情况下，Unity 使用 Unity 安装目录的 settingsTemplate.gradle 文件创建settings.gradle 文件用于您的构建。settings.gradle 文件包含参与构建过程的项目组件。Unity 默认创建以下组件，这些组件应始终包含在 settings.gradle 文件中：

• launcher
• unityLibrary

此外，如果您将 Android 库插件添加到项目中，Unity 会通过替换 **INCLUDES** 条目自动将它们包含在设置文件中。

如果您要向 settings.gradle 添加 Unity 默认不包含的额外组件，请在项目的 Assets/Plugins/Android/ 文件夹中创建一个 settingsTemplate.gradle 文件。这将覆盖默认的模板。

如果您使用自己的 settingsTemplate.gradle 文件，它必须包含以下行：

include ':launcher', ':unityLibrary'
**INCLUDES**

IPostGenerateGradleAndroidProject

IPostGenerateGradleAndroidProject 返回 unityLibrary 模块的路径。这使得一切都与 Unity 2019.3 之前的版本保持相似，无需任何进一步更改，这意味着 Unity 可以在各版本之间以一致的方式访问应用程序的清单和资源。

模板变量

mainTemplate.gradle 文件可以包含以下变量：

变量：	描述：
DEPS	项目依赖项（即，项目使用的库）的列表。
APIVERSION	构建针对的 API 版本（例如 25）。
MINSDKVERSION	最低 API 版本（例如，25）。
BUILDTOOLS	使用的 SDK 构建工具（例如 25.0.1）。
TARGETSDKVERSION	目标 API 版本（例如，25）。
APPLICATIONID	Android 应用程序 ID（例如，com.mycompany.myapp）。
MINIFY_DEBUG	允许为调试版本缩小（true 或 false）。
PROGUARD_DEBUG	在调试版本中，使用 proguard 进行缩小（true 或 false）。
MINIFY_RELEASE	允许为发布版本缩小（true 或 false）。
PROGUARD_RELEASE	在发布版本中，使用 proguard 进行缩小（true 或 false）。
USER_PROGUARD	自定义用户 proguard 文件（例如 proguard-user.txt）。
SIGN	完成 signingConfigs 部分（如果该构建已签名）。
SIGNCONFIG	设置为 signingConfig signingConfig.release（如果该构建已签名）。
DIR_GRADLEPROJECT	Unity 创建 Gradle 项目的目录。
DIR_UNITYPROJECT	Unity 项目的目录。

缩小

可以使用 Proguard 缩小选项来缩小和优化您的应用程序。要激活此选项，请执行以下步骤：

1. 打开 Player Settings 窗口（菜单：Edit > Project Settings > Player），然后选择 Android。
2. 在 Publishing Settings 部分中的 Minify 下，为发布版本和/或调试版本选择 Proguard。

注意：Proguard 可能会剥离应用程序所需的重要代码，因此请谨慎使用这些选项。

要生成自定义 proguard.txt 文件，请启用 Player Settings 的 Publishing Settings 部分中的 User Proguard File 设置。这样会立即在项目的 Assets/Plugins/Android/ 文件夹中生成 proguard.txt 文件。

要了解有关 ProGuard 的更多信息，请参阅 ProGuard 手册。

使用 Gradle 进行构建时的错误

如果在使用 Gradle 为应用程序进行 Android 版本构建时发生错误，Unity 将显示“错误”对话框。请选择 Troubleshoot 按钮，在系统的浏览器中打开有关 Gradle 故障排除的 Unity 文档。

---

• 在 2019.3 中添加了“Unity 用作 Android 库”。NewIn20193