开发未动兼容先行亲妈级攻略一步一截图铲除一切奇怪的报错引言最近在入坑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)这是我们将要进行的配置流程的基本依据。不想看英文也没关系只需看我翻译总结的重点1Unreal使用Android Studio和Android SDK Command-Line Tools来实现安卓应用的打包。新版Unreal使用一个名叫TurnKey的自动化脚本来帮你完成Android开发环境配置的全流程。2使用Turnkey可以自动下载安装Android Studio你需要在Android Studio内勾选安装SDK Command Line ToolsSDK命令行工具。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-强制重新安装SDKTurnKey就会重新下载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的版本更新本文总结的流程也会具有时效性在后续版本中可能会发生变化或失效。具体未尽之处就欢迎大家在评论区补充啦非常感谢。
