Version: 2021.1
自定义 Android 启动画面
Android 清单

Gradle for Android

Gradle is an Android build system that automates a number of build processes and prevents many common build errors. In Unity, Gradle reduces the method reference count in DEX (Dalvik Executable format) files, which means you are less likely to come across DEX limit problems.

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

Unity 版本 Gradle 版本
2020.1 5.6.4
2018.4 starting from 2018.4.4f1
2019.1 starting from 2019.1.7f1, 2019.2, 2019.3, and 2019.4
5.1.1
2018.3, 2018.4 up to and including 2018.4.3f1
2019.1 up to and including 2019.1.6f1
4.6
2018.2 4.2.1
2018.1 4.0.1
2017.4, starting from 2017.4.17 4.6
2017.4 到 2017.4.16(含) 4.0.1
2017.1, 2017.2 2.14

了解更多相关信息:

构建或导出 Gradle 项目

要构建 Gradle 项目,请执行以下步骤:

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

Android 的 Build Settings
Android 的 Build Settings

选择:

  • 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 应用程序模块。您可以将其替换为自己的应用程序。
Android 的 Build Settings
Android 的 Build Settings

build.gradle 模板

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

Gradle 模板包含以下文件:

文件 位置 包含
baseProjectTemplate.gradle In the exported project, root/build.gradle folder 所含的配置会在其他所有模板/Gradle 项目之间共享(代码仓库以及对 Android Gradle 插件的依赖关系)。
launcherTemplate.gradle_ In the exported project, root/launcher/build.gradle folder 包含有关如何构建 Android 应用程序的指令(捆绑、签名、APK 拆分)。它依赖于 unityLibrary 项目并输出 .apk 文件或应用程序捆绑包。
mainTemplate.gradle In the exported project, root/unityLibrary/build.gradle folder Contains instructions on how to build Unity as a Library. Outputs an .aar file. You can override the Unity template with a custom template in the Unity Editor. See the Providing a custom Gradle build template section on this page for more details.
libTemplate.gradle 因情况而异 如果 Unity 项目包含 Android 库项目作为插件,则会使用此文件。

自定义 Gradle 构建

You can provide a custom Gradle build template and select minification options in the Publishing Settings section of the Player Settings window.

Gradle-specific settings in the Publishing Settings section of the Player settings window

提供自定义 Gradle 构建模板

You can use a custom build.gradle file for the unityLibrary module when you build the APK from Unity. This file contains specific build instructions specified in template variables. For a list of template variables, see the next section.

To use your own build.gradle file for the unityLibrary module, follow these steps:

  1. In the Unity Editor, open the Player Settings window (menu: Edit > Project Settings > Player), and select Android.
  2. In the Publishing Settings section, enable the Custom Main Gradle Template setting.

Unity then generates a default mainTemplate.gradle file in your Project’s Assets/Plugins/Android/ folder. The path to the new file also appears under the Custom Main Gradle Template option in the Player Settings. Double-click the mainTemplate.gradle file in the Project view to open it in an external text editor.

mainTemplate.gradle file in the Project view for the unityLibrary module
mainTemplate.gradle file in the Project view for the unityLibrary module

By default, Unity uses the settingsTemplate.gradle file from the Unity install directory to create the settings.gradle file for your build. The settings.gradle file contains project components which are involved in the build process. Unity creates the following components by default, which should always be included in the settings.gradle file:

  • launcher
  • unityLibrary

Additionally, if you add Android library plugins to your project, Unity automatically includes them in the settings file by replacing the **INCLUDES** entry.

If you want to add additional components to the settings.gradle file that Unity doesn’t include by default, create a settingsTemplate.gradle file in your project’s Assets/Plugins/Android/ folder. This overrides the default template.

If you use your own settingsTemplate.gradle file, it must contain the following lines:

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

IPostGenerateGradleAndroidProject

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

模板变量

The mainTemplate.gradle file can contain the following variables:

变量: 描述:
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 Custom user proguard file (for example, proguard-user.txt).
SIGN 完成 signingConfigs 部分(如果该构建已签名)。
SIGNCONFIG 设置为 signingConfig signingConfig.release(如果该构建已签名)。
DIR_GRADLEPROJECT Unity 创建 Gradle 项目的目录。
DIR_UNITYPROJECT Unity 项目的目录。

缩小

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

  1. Open the Player Settings window (menu: Edit > Project Settings > Player), and select Android. 2.在 Publishing Settings 部分中的 Minify 下,为发布版本和/或调试版本选择 Proguard

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

To generate a custom proguard.txt file, enable the User Proguard File setting in the Publishing Settings section of the Player Settings. This immediately generates the proguard.txt file in your Project’s Assets/Plugins/Android/ folder.

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

使用 Gradle 进行构建时的错误

If an error occurs when you use Gradle to build your app for Android, Unity displays an error dialog box. Select the Troubleshoot button to open the Gradle troubleshooting Unity documentation in your system’s browser.


  • 2019.3 中添加了“Unity 用作 Android 库”。NewIn20193
自定义 Android 启动画面
Android 清单