开发未动，兼容先行！

亲妈级攻略，一步一截图！

铲除一切奇怪的报错！

引言

      最近在入坑Unreal Engine，在尝试进行Android打包时遇到了巨大的困难；不管怎么打包都是奇怪的Unknown Error报错，无法发出apk文件。

在网上查了很多教程，但内容质量大多都很差，且普遍有两个问题：

1.版本太老，方法不适配于UE5.4的最新变动；

2.只知其然不知所以然，只讲了某一套可行的操作步骤，但是不总结每一步操作是用来做什么的，具体产生的影响是什么。

恕我直言，很多Step by step攻略的实际操作体验约等于《西游记》中的虎力大仙烧符纸（我的令牌打过了，符纸烧过了，如果还不下雨就不是我的问题了），完全处理不了“龙王不在家”等异常情况。

     针对打包报错的问题，笔者仔细查阅官方文档并进行了一整天的详细测试，终于总结出了打包配置的完整流程，下面请看讲解。

一.从官方文档入手

打开Unreal Engine的官方文档，在【Android】条目中，可以看到这篇英文支持文章：Set Up Android SDK, NDK, and Android Studio using Turnkey for Unreal Engine | 虚幻引擎 5.4 文档 | Epic Developer Community (epicgames.com)

 这是我们将要进行的配置流程的基本依据。不想看英文也没关系，只需看我翻译总结的重点：

（1）Unreal使用Android Studio和Android SDK Command-Line Tools来实现安卓应用的打包。新版Unreal使用一个名叫TurnKey的自动化脚本，来帮你完成Android开发环境配置的全流程。

（2）使用Turnkey可以自动下载安装Android Studio；你需要在Android Studio内勾选安装SDK Command Line Tools（SDK命令行工具）。

（3）手动完成Android Studio的相关操作后，TurnKey还能继续完成安装流程，安装一些其它的东西。全部完成后应重启电脑。

（4）最后是一段非常耐人寻味的摆烂发言：

故障排除
如果您是从新系统安装的，那么上述步骤应该能够完成SDK的设置。但是，旧的环境变量和安装内容可能会导致冲突。有关如何诊断和修复阻止您设置Android SDK的特定问题的信息，请参阅高级Android Studio设置指南。

哈哈哈哈哈哈哈哈哈哈哈哈哈哈，怎么这么好笑。原来Epic官方也知道这个过程可能出现奇怪的问题啊。

 Epic在这里还附上了另一篇支持文章的链接，这篇是有中文版的；

如何为你的虚幻引擎开发环境设置Android SDK和NDK | 虚幻引擎 5.4 文档 | Epic Developer Community (epicgames.com)

这个讲的主要是从旧版UE迁移到UE5.4时如何手动进行SDK配置并保持新旧版之间的兼容性，但也包含了许多有用的信息。由于该指南过于繁琐，且本篇攻略针对的场景是直接安装使用全新的UE5.4进行开发，因此并不会照着里面的步骤做。有需要的读者可以自行阅读。

 二.开始操作

这里我会直接给出自己测了好几天以后总结出的最完善，最可靠的配置步骤，并且会尽量告诉你每一步的作用是什么，如果错了会怎么样。这些内容具体怎么总结出来的就不讲了，说多了都是泪，大家只需要相信最终结论就好。

1.（刚上大学的萌新建议阅读）保证你的电脑基础运行环境是好的。

提示

如果你是计算机、软件、数字媒体等相关专业的新生，对windows不太熟悉，那么请特别注意你手中的电脑有没有正确安装显卡驱动。

对于NVIDIA显卡，务必安装Geforce Experience来更新显卡驱动；对于AMD显卡，请使用AMD SoftWare。数码店铺发货给你的新电脑通常只会附带一个年代非常久远的可用驱动，准确地说是你家显卡的初版或早期版本驱动；这种原厂驱动运行大多数老软件、老游戏是没有问题的，但是在包括UE5在内的新软件上很可能会报错。

为了体现攻略的贴心，我特意重装了远古驱动来模拟这种情况。如果你的UE在启动时出现类似下图的警告，说明你的显卡驱动是有问题的。

其次，保证你的C盘还有至少150GB的剩余存储空间。这是因为下面的步骤会默认将Android Studio安装到C盘。如果C盘容量不足而被迫手动安装到他处，会产生许多不必要的麻烦，对萌新不友好。

此外，你的电脑最低应具备32GB的内存容量；若使用16GB或更少RAM的系统运行UE，可能因RAM容量不足而产生问题。

2.排除其它开发环境可能造成的冲突。

UE5的安卓配置需要用到Android Studio，且在过程中会自动配置若干项系统环境变量；出于保险起见，强烈建议遵循后面讲的自动化流程来执行全新安装&配置，而不是使用先前安装过的旧有版本。

·如果你先前安装了Android Studio，请卸载。

·如果你先前安装了Java相关运行环境（例如 jdk 1.8），请卸载。

·如果你的电脑已经执行过太复杂的开发任务，或者被大量流氓软件和安全软件占据，或者你的运行环境已经因为折腾另一个软件（例如Unity）的Android开发环境而变得千疮百孔了，那么建议重装系统。

在Windows 11中，在开始菜单-搜索栏内搜索“编辑系统环境变量”，进入系统变量设置页，如下图。

如果你的电脑是新的，未用来从事过其它开发工作，那么你的用户变量应该长这样：

如果你先前从事过Android或java开发，那么可能会看到一些别的环境变量：

如果你看到了诸如上图的环境变量，请将它们删除。

3.确保你已经安装了Epic Games Launcher和新版的UE5编辑器。

（本文写于2024年5月，当前的最新版本是Unreal Engine 5.4.1，如图。）

 4.补充安装UE的Android模块。

在Epic Games Launcher-虚幻引擎-库-引擎版本中，找到你使用的引擎版本，点击【启动】按钮旁边的黑色小三角，选择【选项】，勾选【目标平台-Android】，点击【应用】，即可执行增补安装。

5.创建或打开一个项目，并运行TurnKey脚本。

（这里假定你基本熟悉UE5的操作界面，知道怎样创建和保存一个空白关卡，并且知道如何进行windows平台的打包。）

点击【平台-Android】，会看到提示信息，显示Android Studio尚未安装，如下图红框所示。

*如果未看到红框处的文字，说明上一步没有正确安装UE的Android组件。

点击【安装SDK】（如图中黄框处所示），将会开始执行UE5的TurnKey脚本，从而启动Android的自动化配置流程。

这里首先会弹出一个Turnkey提示框，告诉你将要开始自动下载安装Android Studio。点击【确定】开始下载，如图。

在输出日志中可以查看Android Studio下载进度，如图。

下载完成后，会显示一个新的TurnKey弹窗，提示你即将需要在Android Studio中进行一些手动操作。如图。

 选择Run Android Studio......选项，点击【确定】以继续。

重要提示

从这里开始我们需要在Android Studio里进行操作。在这个阶段，TurnKey脚本将会处于暂停并等候的状态——你可以在画面右下角看到持续显示的正在安装Sdk...小窗，并在UE5窗口内看到一个“询问是否重试”的TurnKey弹窗提示。在操作Android Studio期间，注意不要将这两个小窗关闭，也不要在UE引擎内进行任何操作，如图。

如果不慎将这两个小窗关闭了，也不用担心，只要在Android Studio操作完成后，重新点击平台-开始安装SDK即可。

6.在Android Studio中挑选和安装所需组件。

这个时候其实Android Studio已经悄悄安装完成了，你会马上看到Android Studio初次启动的欢迎页面。

首先是隐私选项，选哪个都行。

之后可能会提示安装Android Studio的必要组件，这里没有什么要注意的，只选择默认选项，一路点击【Next】即可。

如果看到用户协议，点击"Accept"接受，如图。

全部完成后，Android Studio会开始下载解压一些初次运行需要的东西，这里不用管它，等待即可。

提示

在上述Android Studio的设置过程中，你可能会看到一些关于网络代理异常的提示，例如"Set proxy......"。目前Android Studio对国内下载的优化还不错，通常可以直接关闭相关提示，不影响设置完成；如果安装还是被阻塞，则应保证你能够连接到Google相关服务。

下载完成的状态如下图，点击Finish即可。

此时会来到Android Studio主界面。点击More Actions-SDK Manager，打开SDK管理页面，如图所示。

提示

如果你的电脑中曾经创建过Android Studio的项目，那么Android Studio可能会直接打开项目，而不是显示主页面。在这种情况下，SDK Manager的入口位于顶部菜单栏的Tools选项卡内，如图所示。

此外你也可以点击顶部菜单栏的File-Close Project，退出工程并返回主页面。

打开SDK Manager之后，选择画面中上方的SDK Tools选项卡，在这里可以挑选安装我们需要的Android SDK组件，如图。

     这里需要注意画面右下角红框处的Show Package Details（显示包细节）选项，这个选项勾选与取消勾选时，你看到的界面将会有很大的区别。

执行以下操作：

 （1）在Show Package Details 取消勾选状态下，选中Android SDK Command-line Tools (latest)选项，如图。

 （2）选好之后，点击右下角Apply按钮，执行所需的安装。

安装完毕后点击Finish，退出Android Studio，返回UE界面。

7.继续执行TurnKey以自动安装NDK。

回到UE界面，会看到TurnKey的弹窗还在，正等着我们继续执行。点击attempt按钮以继续运行脚本。

此时会马上弹出一个windows cmd界面。这个时候脚本在做什么呢？

如果你偷瞄一眼cmd上面的内容，会发现此时正在下载和解压一个特定版本的NDK：

重要补充说明

（本段内容可能会解决你的很多疑惑。但如果你只想完成打包，也可以跳过不看）

这里是整个UE5 Android配置流程里最大的一个坑！

事实上，在脚本里悄悄安装的这个NDK是由Epic指定的——它就是适配于当前UE版本的NDK版本；但是UE的文档里全程都没有提到这件事，并且几乎对NDK的配置只字不提——更没有阐明TurnKey在这个阶段已经悄悄安装了一版NDK。

而在UE5的项目设置-平台-Android SDK页面中，我们可以明确地看到，UE5是需要依赖于NDK进行打包的，并且还给出了NDK目录的填写框，如图。

这个填写框在UE5.4中产生了很大的误导性！

任何一位同学只要有在其它环境中发布Android应用的经验，那么看到这个地方的时候，几乎100%会去想一下，这NDK从哪儿搞到手呢？

事实上，在网上能看到的失败案例中，很大一部分都是因为在这个地方选择“自谋生路”，通过Android Studio或其它途径去下载了不知道什么版本的NDK，然后与UE5编辑器不匹配，从而在打包时产生了未知问题。实际上，正确的方法应当是“无为而治”，将这个NDK填写框的内容留空。

而这个地方可以留空的依据，则是引擎中提供的ToolTip——将鼠标悬停在上图的NDK这一项上，会出现一行解释说明:

这个说明告诉我们，当此处NDK目录留空时，UE5会使用系统环境变量中的NDKROOT，作为NDK的路径。

而在强大的Turnkey的协助下，只要你执行到了自动安装NDK这一步，那么打开系统环境变量，就会有惊人的发现：

NDKROOT已经在系统环境变量中被填好了！并且已经正确定位到了刚才cmd窗口中下载安装的NDK的路径！

也就是说，当你什么都不做——既不去手动安装NDK，也不去手动指定NDK路径，那么UE5在这个流程中就能够正确获得所需的NDK。（此结论对同一页面上显示需要提供的Android SDK和JDK目录也适用，原因相同）而一旦你插手干预，那么原本没问题的NDK配置就肯定要出问题了！

What can I say?

脚本执行完毕后，cmd界面会自动关闭，同时画面右下角出现提示：“需要重启才能应用新设置”，如图。点击【立即重启】，以重开UE5编辑器。

到这里，UE5的Android配置脚本已经全部执行完毕。此时我们需要关闭UE5，重启一次电脑，以保证先前的所有改动都正确生效。

如果不重启电脑就直接打包，可能会产生Unknown Error报错。

8.进行打包

重启电脑以后再次打开UE5编辑器，回到待打包的工程中。此时我们的Android打包环境已经准备就绪，可以进行打包了。

在UE5顶部菜单栏，点击编辑-项目设置-平台-Android，在APK Packaging卷展栏中点击【接受SDK证书】，如图。

然后，为你的应用填写适当的包名（com.xxx.yyy）和应用展示名。

勾选Packge game data inside .apk，使得应用数据能够被封装在单个apk文件中，如下图红框所示。这一步非常重要，不可遗漏——如果没有勾选，打包将会生成适用于Google Play商店分发的.obb文件，无法正常安装使用。

如果打包出来的内容是这样的形式，说明Packge game data inside .apk选项没有勾上。

前往平台-Android SDK页面，将该页面的前三个选项（分别为Android SDK、NDK、JDK安装目录）留空（这样做的原理参见本文第7小节的补充说明部分），后两项填写"latest"，如图所示。

然后再回到平台-Android页面，我们需要填写应用的最低SDK版本（Minimum SDK Version）和目标SDK版本（Target SDK Version）

目前，这两个地方需要填写的具体数值并不重要，只需要随便填写一个UE5能识别的API Level即可，例如图中这里我填了28。

提示

这是因为前面的NDK API Level处已经填写了latest，这意味着UE5会发布尽可能新的API版本；即使你在这里的Minimum SDK Version中指定了较旧的API Level，发布时也会被无视。

至于怎样才能发布适用于旧版本的apk，这会在第10小节中讲解。

填写完毕后回到主界面，点击平台-Android-打包项目，选取一个输出目录，开始发布apk。

这里可能需要等待很长一段时间。

等待30分钟左右，编译完毕后，apk发布成功，输出日志中显示“BUILD SUCCESSFUL”，如图所示。

到这里，如果你的apk发布成功，那么说明你的Android发布环境已经跑通了，可喜可贺！如果显示有报错，没能发布成功，也不要气馁。你可以尝试以下操作：

·仔细阅读报错时的输出日志，看是否有出错原因的说明；

·逐条检查前面讲解过的步骤是否操作正确；

·检查网络连接；

·重启UE5；

·重启电脑；

·在每次尝试发布apk前，在UE5主界面点击平台-刷新平台状态；

这些方法都可能帮助你解决问题。

打开apk发布目录，找到【项目名-arm64.apk】文件，将其安装到Android手机上，运行应用，即可看到游戏画面，如图。

提示

如果安装apk到手机上时提示不兼容，请检查手机的Android版本是否足够新；并且注意应当使用文件名中带有"arm64"而非"x64"的apk文件。

9.适配Android设备特性

安装apk到手机以后，你可能会发现，应用的显示比例、显示范围、旋转方向等外观表现不符合预期。这是因为，你需要在发布前调整一些设置，以适配Android设备的相关特性。

打开项目设置-平台-Android界面，在这里可以调整一些设置项，如图。

·Orientation：应用的显示方向。包括横屏/竖屏，以及是否通过重力感应（Sensor）切换方向。

·Maximum supported aspect ratio：最大屏幕长宽比。以小米14手机为例，其屏幕分辨率为2670*1200，屏幕长宽比为2.225。由于新款手机的屏幕大多比较狭长，因此这里需要设置一个比较大的值（>2.3即可），否则会在横屏显示时出现两侧的黑边。

·Use display cutout region? 是否在屏幕的“刘海”区域显示内容。如果勾选此项，那么显示内容将会占满包含前置摄像头的“刘海”“水滴”“挖孔”等区域；如果不勾选，那么前置摄像头底部以上的屏幕区域将会全部留黑。

·Allow splitscreen resizing? 是否允许在应用分屏显示时调整画面比例;

·Allow fold/flip size changes? 勾选此项，可以适配折叠屏手机的fold/flip特性。 

调整以上选项以后重新发布应用，即可看到针对手机的相应适配效果。

10.发布旧版本Android应用

如果要让较旧的设备机型也能够运行我们的应用，就需要发布支持更早版本Android的apk包。要实现这一点，我们就需要在Android Studio中安装旧版本的Build Tools。

执行以下操作：

（1）打开Android Studio，进入SDK Manager-SDK Tools页面。

（2）在Show Package Details 勾选状态下，点开Android SDK Build Tools选项（不要与Command Line Tools混淆！）。这里可以观察一下，发现Android Studio内已经装好了一个或几个较新的API版本，如图。（例如我这里截图显示的API 34/33，即Android 14/13）

补充说明

    准确地说，这里的API  34是Android Studio初始默认安装的，而API 33是由TurnKey脚本安装的。因此也可以理解为，API 33就是当前版本UE5的"Android建议版本"。在本文的第8小节中，不做特别配置的情况下，UE5默认打出来的包版本就是API 33。

     在后续工作中，如果你在Android Studio中删除了API 33的BuildTools，那么只要在UE5中点击平台-Android-强制重新安装SDK，TurnKey就会重新下载API 33并将其自动装回你的Android Studio。

不难看出，我们目前只安装了较新版本的Android SDK Build Tools。如果一直保持这种状态发布应用，而不使用任何旧版API的话，那么只要是稍微旧一点的手机，就无法安装你发布的应用。

在Android官方文档中可以查阅API Level与Android版本号的对应关系，这里我直接贴出来：

SDK 平台版本说明  |  Android Studio  |  Android Developers (google.cn)

假定我们的应用需要支持Android 9 (API 28) 以上的版本。在这里，我们勾选安装API28（注意勾选Show Package Details，否则看不到选项），点击Apply执行安装，如图。（这里我勾选了API28的所有小版本。为了防止出现问题，安装旧版API时尽量都像这样全部勾上，不要只勾选一个。这样可以降低打包出问题的概率）

重要提示

接下来我们需要进行一个“四码合一”的操作，在UE5的四个不同填写框中填入我们需要的API版本号，即28。

安装完毕后回到UE5-项目设置-平台-Android SDK页面，在SDK API Level【1】和NDK API Level【2】填写框中填入"android-28"，注意不要有任何字符错误，如图。

注意到填写框左边括号里的说明了吗？SDK API Level填写框中也可以填写"matchndk"，含义一样。

切换到平台-Android页面，在Minimum SDK Version【3】和Target SDK Version【4】中填入"28"，如图。

再次进行打包操作。这次就会获得适用于Android 9的apk，不过看上去和先前的apk不会有什么区别，如图。

如何验证这个apk真的适用于旧版Android呢？用旧手机进行测试当然是可以的，但我们手边不一定有如此旧的设备。不用着急，因为我们可以使用Android Studio的Profile or Debug APK功能，对该apk文件进行解析：

阅读manifests/AndroidManifest.xml文件，找到其中的<uses-sdk  android:minSdkVersion字段，可以看到最低版本号为28，说明确实适配了旧版Android。 

 重要提示

1.需要注意的是，我们只需在Android Studio中补充安装旧版的Android SDK Build Tools，即可发布旧版本apk。在Android Studio中，我们不难发现用到的其它工具（例如Command Line Tools）也存在许多旧版本，但是它们与发布旧版apk的需求均无关。

如图，请不要试图安装使用那些旧版本，以免画蛇添足，导致打包出现问题。

2.（重要，重要，非常重要！）由于Android API版本繁多，加之UE5能够支持的Android版本种类有限，因此在实际测试中，存在【某一个Android API版本无论如何都发布不出来】的情况。例如在笔者的当前环境下（UE5.4.1），实测Android API 30是无论如何都发布不了的，会显示UnknownError报错，如图。

而API30的前后两个版本，API 29和API 31，却都是可以正常发布的！

如果你也遇到了相同的问题，记得换成别的Android旧版本再试试看。

因为本人不是Android原生开发者，所以目前无法找到这个问题的成因；但这个点实在是坑中之坑，无力吐槽。毕竟如果我不讲的话，读者可能会恰好尝试发布有问题的那个版本，然后发不出来，误认为是自己配置的问题；然后就把本来配置好的环境又改坏了。

至此，我们就可以发布需要的旧版本apk啦。

做一下总结：

·发布UE5默认的新版本apk时，在SDK API Level和NDK API Level中填写"latest"，在Minimum SDK Version和Target SDK Version中随便填； 

·发布特定旧版本的apk时，在SDK API Level和NDK API Level中填写"android-[API Level]",在Minimum SDK Version和Target SDK Version中填写[API Level]，即“四码合一”。

三.后记 

      到这里，UE5.4版本的Android打包配置流程和全部注意事项都已经讲解完毕！不得不说的是，UE打包的这套配置流程对用户是不太友好的。

· 一方面，配置过程中需要半途切换到Android Studio继续操作这种做法，显得繁琐而诡异，且坑点、易错点众多，很容易让人无所适从；

· 另一方面，在UE5的项目设置中，有4个不同位置都需要填写API Level，填得稍有问题就会报错；这一过程明显缺少提示引导和故障排除机制，而且填写规则还颇为烧脑——很难想象有人能在不做反复测试的情况下，一次就猜对。

由于水平有限，本人所做的测试难免有遗漏之处，或许还有更高效、更稳定的配置流程或操作技巧尚未提及；此外，本文中的流程并未在UE5.4以前的旧版本进行测试——如果你需要使用UE旧版本，建议查阅更早期的配置攻略，切勿照搬本文内容进行操作。

而且可以预见的是，随着UE和Android Studio的版本更新，本文总结的流程也会具有时效性，在后续版本中可能会发生变化或失效。具体未尽之处，就欢迎大家在评论区补充啦，非常感谢。