1. 环境准备把UE5和Android开发链路先打通这一章会直接决定你后面所有操作的体验。我做AR Android开发用的主力引擎版本是Unreal Engine 5.3原因是这个版本的Google ARCore插件仍然保持稳定、文档齐全网络上的现成案例也最多。如果你已经装的是UE 5.4或者更新版本会发现AR相关插件的位置和命名有所调整部分功能已经被移到了OpenXR体系下概念上会多一层“设备会话”的配置对第一次接触AR的人来说并不友好。所以除非有特殊需要我建议新手先锁定UE 5.3等跑通一个完整流程之后再考虑升级。先说清楚这次要做的东西到底长什么样手机打开App后直接进入相机画面屏幕中央有一个准星或者一个小圆点用户在桌面上、地板上、墙面上来回扫动手机等待系统识别出水平面或垂直面。识别成功之后点击画面上的某个位置一个虚拟物体就会“钉”在现实场景的对应坐标上人从不同角度走近走远物体都还在原来的位置。UE5里AR开发的核心就是让引擎把“虚拟摄像机的运动轨迹”和“真实摄像头的空间移动”绑定在一起同时把真实世界中的平面位置转换成为引擎世界中的锚点坐标。动手之前先把工具链补齐。开发AR Android App至少需要下面这几样东西缺一不可Unreal Engine 5.3可以从Epic Games Launcher安装注意安装时勾选Android支持Android Studio至少到Flamingo版本主要用里面的SDK Manager和Device ExplorerAndroid SDK Platform 33以上对应Google官方推荐的targetSdk等级Android NDK r25c这个版本和UE 5.3是配套的低版本或高版本都可能遇到链接期报错JDK 17UE 5.3的Gradle脚本已经迁移到JDK 17环境还在用JDK 11的容易卡在编译阶段。我见过不少人在这段翻车卡得最狠的不是UE本身而是Android Studio的SDK路径问题。UE默认去安装目录找Android SDK但你如果中途换过Android Studio版本或者自定义过安装路径UE找不到就会反复弹窗让你重新配置。最好的做法是在系统环境变量中新建一个ANDROID_HOME指向你实际安装SDK的目录例如D:\Android\Sdk然后在UE的“项目设置 - 平台 - Android SDK”里把路径也填成完全一致的位置。两个地方都必须对后端打包脚本才会顺利走下去。这里有必要解释一下UE在Android上是怎么工作的。当你在编辑器里点击“打包项目”UE并不会像一个普通游戏那样把字节码和资源直接塞到一个APK里就结束。它会先生成一份完整的Gradle工程放到指定目录再调用Gradle去执行真正的编译和链接任务。Gradle在首次运行时要下载大量依赖从Gradle本身到Android Gradle Plugin、Kotlin标准库、AndroidX库等等。下载速度和网络环境直接相关国内开发者如果网络不稳定可以在Gradle的init脚本中配置阿里云的Maven镜像具体写法网上很成熟我这里不展开了。总之记住一个原则如果打包卡在某个“Downloading”或者“A problem occurred configuring root project”的环节八成不是代码问题而是依赖没拉下来。2. ARCore插件与AR场景搭建从空场景到可识别平面ARCore插件的启用路径在“编辑 - 插件”里搜索“ARCore”把“Google ARCore”勾选上编辑器会提示重启。重启之后在内容浏览器左侧的面板里查看“全部/增强现实”就能看到ARCore相关的类和蓝图节点。很多初学者到了这一步就急着开始堆蓝图我的建议是先建立一个足够简单的测试地图确认ARCore真的能跑起来再谈功能。我采用的项目模板是“第三人称游戏”。选择它的原因很简单模板自带了一个带弹簧臂和摄像机组的Pawn以及一套移动输入绑定。AR应用里虽然不需要玩家用虚拟摇杆控制角色移动但摄像机组件、输入组件这些基础设施可以重复利用省去自己搭建输入映射表的时间。如果你用空模板后面添加触摸事件时还要自己配置Action复杂度会提升一点。创建完关卡之后场景里要添加的核心Actor有三个第一个是“AR Session”它的作用是管理ARCore会话的生命周期。你可以理解成它是连接虚拟世界和真实世界的那条管道所有的相机画面、设备姿态追踪数据都是通过这个会话流入引擎。AR Session通常放置在关卡里即可不需要移动不需要添加网格体也不参与渲染。第二是“AR Session Config”它决定会话以什么模式运行包括是否启用平面检测、是否启用光照估计、是否启用相机画面作为背景。第三是“AR Camera Manager”它负责把真实相机捕获到的画面实时渲染到GameViewport上。在实际的蓝图搭建过程中我的做法是把AR Session和AR Session Config的引用保存到关卡蓝图变量中然后在Event BeginPlay节点里调用Start AR Session。这里有个容易被忽略的参数平面检测模式。ARCore支持“水平面”“垂直面”和“两者都要”三种模式。如果你只想做桌面和地面放置水平面就够了但如果你的应用允许在墙上挂虚拟画框就必须开启垂直面检测。垂直面检测需要更长时间的特征点积累对环境的纹理丰富度要求更高特别是纯色白墙识别率会明显下降。我在测试中遇到过一面近乎无纹理的乳胶漆墙面手机扫了将近二十秒都没有任何反应后来在墙上贴了两张海报几秒钟内就出现了垂直平面。这个案例后面在调试部分还会详细提到。平面检测在ARCore里不是“一次识别永远存在”的。系统会持续更新检测到的平面的边界点甚至可能发现同一个物理平面被识别成多个虚拟平面然后过一会儿自动合并。为了让用户直观看到识别结果我会在节点On AR Tracked Geometry Updated触发时动态生成一个半透明网格体贴合在识别到的平面上。UE的AR插件里有一个“Procedural Mesh Component”的做法可以非常方便地接收平面边界点并生成网格体。简单来说就是拿到ARPlaneGeometry里的边界顶点数组每多一个点就重建一次Mesh。设备性能和网格精度之间需要取舍平面边界点动辄上百个如果每帧都重建Mesh低端手机会明显卡顿我一般只在回调触发时才更新Mesh。场景里还需要解决相机背景的问题。ARCore把真实相机画面送入引擎是通过所谓的“背景相机纹理”完成的。GameViewport的底色必须保持黑色不要放任何天空球或者Static Mesh遮挡背景。UE引擎默认的关卡会带有天光、太阳光和地面网格这些在AR项目中都要清理掉尤其是背景球形物体会盖住真实影像。我常用的做法是新建一个空关卡不放任何几何体只保留一个Directional Light来给虚拟物体打光真实世界的光照则交给ARCore的光照估计功能。光照估计是AR体验完整度提升最大的一个开关。ARCore可以从相机画面中估算当前环境光照的强度和色温并把结果传给引擎。开启之后虚拟物体的阴影方向和亮度会跟着环境变——在室内白炽灯下偏暖在室外阴天偏冷。UE蓝图中有对应节点可以读取估计光照如果要做写实风格的内容这个功能几乎必开。初次搭建场景时建议先把它关掉因为光照估计值变化会导致物体亮度跳变干扰你对模型本身的材质调试。3. Android打包配置权限、CPU架构与纹理压缩决定成败很多人在编辑器里能跑通AR一到打包环节就抓瞎根本原因是对Android平台的打包配置理解不够。这套配置在“项目设置 - 平台 - Android”里一共就几个关键项但每一项都直接影响APK能不能装在手机里、能不能正常调用相机、能不能稳定跑AR。先设置包名。包名的格式是反向域名比如com.yourstudio.armobile。包名一旦发布就不能改否则会被系统视作另一个应用用户无法覆盖安装。测试阶段倒是可以随便改但我建议从一开始就认真起名避免后面做应用市场审核时还要换包名重新提交。紧接着是“最小SDK版本”和“目标SDK版本”。ARCore官方要求最低Android 7.0API 24但UE 5.3的Android平台生成物要求更高我会把最小版本设为Android 8.0API 26目标版本设为Android 13API 33。目标SDK版本过高的另一个坑是Android 11以后系统强制要求共享存储区的访问权限规范如果UE项目里同时开启了“请求所有文件访问权限”之类的高危权限上架时会被应用商店拦截。AR应用本身不需要访问用户文件所以严格控制在申请相机权限即可。CPU架构方面现在的手机几乎全是ARM64ARM64一个选项就足够。老项目中可能同时勾选了ARMv7这会让打包体积变大也会让部分纹理损失质量。我不建议为了一小部分旧设备拉低整体体验直接在架构列表里只保留ARM64。纹理压缩格式是另一个隐性重点。UE在Android平台一般推荐ASTC这是目前校准质量与压缩率最平衡的格式支持范围覆盖近年绝大多数中端机。如果设备太老不支持ASTC也可以退到ETC2。但需要注意材质中的法线贴图在ASTC和ETC2下的质量差异非常明显尤其在AR场景里虚拟物体会贴近真实物体并排对比法线细节如果压缩过度一眼就能看出“塑料感”。权限声明在Android平台设置里有专门的“所需权限”列表必须手动勾选“Camera”。ARCore插件本身在构建时会在Manifest中申请相机权限但我在多次打包实验中发现UE在合并Manifest时并不总是把所有权限都保留有些机型上会出现应用能启动但相机画面黑屏的情况最后就是权限没给到位。在测试阶段我都是把这些权限全部勾上Camera、Internet、Access Network State。访问网络主要是给以后做云锚点或多人在线预留能力提前配上省得忘。打包图形API的选项也容易被忽略。ARCore在Android上支持OpenGL ES 3.1和Vulkan两种API。我建议首次跑通时选择OpenGL ES 3.1原因并不复杂Vulkan的驱动兼容性在不同品牌手机上差异很大尤其是部分国产ROM对Vulkan的优化参差不齐开ARCore会话时会出现间歇性闪帧。OpenGL ES 3.1在UE里的成熟度更高Shader编译稳定。等基础功能跑通了再考虑切换到Vulkan去降低绘制开销。一切配置做完之后点击“文件 - 打包项目 - Android”目标平台如果前面选了ASTC纹理压缩输出目录下就会多出一个Android_ASTC文件夹里面放着APK或者未打包的Gradle工程。首次打包耗时非常长二十分钟到半小时都很正常不是因为机器慢而是Gradle在后台下载各种依赖。第二次打包就会快很多因为依赖已经缓存到本地了。打包完成后UE会在输出目录下同时生成一个install.bat批处理脚本这是给已经连接真机的开发者用的方便直接安装到手机但我个人更推荐用后面的ADB方式因为可控性更高。4. 真机部署与调试从安装到日志抓取的真实链路到了这一步你应该已经拿到一个能在编辑器里显示相机画面、识别平面并放置物体的工程。接下来要解决的核心问题是怎么把它装到手机上并且能不能顺利跑起来。真机安装的第一步是让手机进入开发者模式不同品牌手机打开方式大同小异在“设置”里找到“关于手机”连续点击“版本号”五次左右系统会提示进入开发者模式然后在开发者选项里打开“USB调试”。用数据线连接电脑后打开命令行工具输入adb devices如果能看到一个device状态的设备编号说明连接正常。如果显示为unauthorized检查一下手机上的授权弹窗可能是没有点“允许USB调试”。现在很多国产手机还会默认拦截ADB装的非应用市场应用需要在开发者选项里找到“USB安装”之类的开关手动打开否则安装APK时会提示“安装失败应用未安装”之类的问题。安装APK有两种方式。一种是把UE打包生成的APK直接拖到手机存储里用文件管理器点击安装。这种方式最简单但每次修改代码都要手动拷贝很烦。我更推荐在命令行里用adb install -r 包名.apk-r表示覆盖安装保数据。执行完毕后手机上就会多出以包名命名的App图标。需要注意测试阶段APK的SDK版本如果低于手机系统版本安装没有问题反之如果目标SDK版本高于手机系统版本某些手机也会拒绝安装。应用启动起来看起来一切正常但用户那边说某个场景崩溃了。要知道崩溃原因就必须抓日志。UE在Android上产生的日志会通过Android系统的Logcat统一输出标签名通常是UE4或者UE。命令行里输入adb logcat -s UE4:V AndroidRuntime:V就能看到引擎的日志输出和应用崩溃时的Java异常堆栈。这个命令在排查问题时几乎是万能的。比如最常见的“找不到ARCore服务”类错误日志里会明确出现ARCore not supported或者E/ARCoreService的记录。如果是权限被拒绝日志会有SecurityException: CAMERA的字样。学会看Logcat遇到99%的问题都不需要再到处发帖求助直接看日志定位根因效率最高。UE项目里还有一个重要开关-ForceLog。UE在Release构建里通常会隐藏部分日志输出如果遇到无法在Logcat里看到引擎日志的情况可以在“项目设置 - 打包”里的“额外命令行参数”加上-ForceLog然后重新打包。加上之后日志量会明显变大对定位深层次问题非常有帮助。不过这个选项只适合开发期正式发布时一定要去掉否则日志文件会撑爆存储空间也会增加被逆向分析的风险。还有一个调试技巧是关于断点调试的。UE的蓝图无法直接在真机上断点但可以通过输出节点把关键变量打到日志里。这里要把“输出到屏幕”和“打印字符串”节点区分开——在真机上屏幕输出因为相机背景遮挡几乎看不见所以必须优先使用“打印字符串”并勾选“输出到日志”。我在开发平面检测调试期就是靠着在On AR Tracked Geometry Updated回调里不断打印平面数量、边界点数量和环境光照亮度才把平面识别慢的真实原因摸清楚。这些日志在实际调试中的价值远远超过任何代码审查。5. 真机运行阶段最常见的三类故障环境、权限与性能这一节的内容来自我自己在项目过程中的排障记录。AR开发相对普通手游多了一层对设备和物理世界的依赖所以故障也更有“场景感”。我把常见问题分为三类每一类都附上根因和排查路径。第一类是环境类故障典型表现是打包过程报错、运行时直接闪退退出。打包阶段最常见的错误信息是“NDK not found”或者“SDK component missing”。这类问题通常是因为UE项目设置里指向的SDK目录和实际安装目录不一致。我遇到过一种情况Android Studio新版本强制把SDK放在了C:\Users\xxx\AppData\Local\Android\Sdk而UE还指向旧的D:\Android\Sdk结果SDK Tools和NDK全都找不到。解决办法就是把环境变量ANDROID_HOME统一改成实际路径然后重启电脑和UE编辑器。运行时闪退的另一个高频原因是设备没有安装“Google Play服务”。ARCore不是一个内置在手机系统里的组件它依赖Google Play服务来实际执行相机姿态追踪。国内手机如果系统没有预装Google Play服务ARCore会直接不可用。在测试时首先要确认手机安装并更新了“Google Play服务AR”这个应用。如果没有应用会在启动AR会话时直接崩溃日志里也能看到ARCore服务连接失败的表现。第二类是权限类故障典型表现是应用启动后相机画面是全黑或全灰点击屏幕没任何反应。前面说过UE项目设置里要手动勾选Camera权限但即使勾了Android 8以上系统仍然需要在运行时动态申请权限。我在早期版本里遇到过这样的问题打包后首次安装启动没有弹任何权限请求框相机画面黑屏Logcat里报SecurityException。原因是我使用了第三方登录SDK它在清单中声明了Camera权限但并没有在运行时申请。系统在首次安装时看到Manifest里没有特殊声明就默认把权限设为拒绝。解决方式是在AR会话启动前主动调用一次权限检查函数。在UE里可以通过蓝图节点“检查Android权限”和“请求Android权限”实现ARCore插件在启动时会自动触发一次但为了稳妥建议在BeginPlay时手动请求一次Camera权限。第三类是性能类故障典型表现是高通骁龙7系、天玑8000级别以上手机也出现掉帧发热运行几分钟后系统提示温度过高。AR应用对性能的压力比普通游戏大不少因为相机预览本身就要占用ISP和GPU资源同时ARCore还要持续进行特征点提取、姿态估计。再加上UE5的实时渲染负载叠加非常可观。我用来做性能压测的手机是骁龙870级别的测试机默认画质下跑简单平面检测场景完全没有问题但只要在场景里加入几个高模和实时代理阴影帧率就会跌到20帧以下。针对这个问题需要从三个方向下手。第一个方向是降低视觉渲染负载关闭移动端的后期处理体积把抗锯齿从TAA改成FXAA关闭动态全局光照记录或者直接使用MonoscopicDistanceFieldShadow替代传统的可接触阴影。AR场景中真实环境的光照已经由相机画面提供过度复杂的实时阴影其实没有多少增益反而会因为虚拟物体和真实桌面的阴影方向不完全一致而显得“假”。第二个方向是减少对ARCore实时计算的消耗平面检测的模式如果可以只保留水平面或垂直面其中的一个避免同时跟踪太多平面。平面网格的边界更新频率如果不需要实时可以降低回调频率比如每两帧才更新一次网格顶点。第三个方向是资源层面的控制纹理格式统一ASTC角色模型限制骨骼数和材质数关闭HDR和Bloom这些都能在肉眼几乎无感的前提下腾出大量带宽。还有一个经常被忽略的点是屏幕分辨率。ARCore的相机预览分辨率在很多手机上默认是1280×720如果UE的GameViewport分辨率设置过高相机会把画面拉伸显示不仅模糊还白白增加渲染压力。在项目设置里可以把Screen.Resolution的最大分辨率限制到1920×1080实际在大多数手机上1280×720已经足够用于AR交互。6. 把AR项目往真实产品方向推进的几点建议到这里一个基础的AR Android App已经可以在真机上稳定运行了。你在现实世界任何带纹理的平面上都能看到一个虚拟体被“按住”地放着。但离真正可以交付给用户使用还有一段距离。我个人做AR项目的一个体会是AR内容开发中最后百分之二十的工作量往往花在“真实感”和“交互可靠性”上。技术层面跑通只算完成了骨架距离好看、好用还有很长的路要走。如果你接下来要继续扩展我最建议去尝试的是给放置的模型添加一个“落地平滑动画”也就是当用户点击屏幕、模型生成后从一个悬浮状态缓慢下降贴合到真实平面上。这个小细节在视觉上的提升非常明显用户会明显感觉物体是“放在”场景里而不是凭空“嵌”进去的。实现一次平滑动画只需要在蓝图里做一个位置插值用Lerp节点从初始高度插到平面高度配合时间轴控制两小时之内就能完成。交互层面还有一个实用的方向是“模型旋转缩放”。AR里的缩放和普通射击游戏里的缩放逻辑不同它必须围绕模型自身的中心点否则会出现模型在放大时突然跳走甚至穿模到地下。建议在做这类功能时把所有模型统一挂在同一个根Actor下面然后对这个根Actor做缩放和旋转避免模型自带动画或物理组件干扰变换运算。这个设计思路在后续做AR展示类应用时会非常省心因为你不需要关心每个静态网格体的坐标空间。再远一点可以考虑接入AR云锚点和多人同步。UE在5.x版本中已经为ARCore和多平台会话提供了一定的云端支持你可以把某一个AR会话中识别的锚点上传到云端让另一台手机扫描同一场景时在完全对应的位置看到同一个虚拟物体。这个功能在远程指导、虚拟样板间、多人娱乐中都是刚需。实现起来比单人AR多一个网络同步的中间层但核心逻辑仍然建立在“锚点必须稳定”的基础上——如果你现在做的平面检测和锚点管理本身就不稳云同步会把问题放大。最后再分享一个和打包相关的个人习惯我每次修改完配置或代码都会先打一个Release包在真机上完整跑一遍流程而不是一直用编辑器Play模式。编辑器里运行AR和在真机上运行的差异比想象中大得多相机畸变、设备陀螺仪噪声、CPU降频这些只能在真机上感知到。不要等到要出包给别人演示时才第一次上真机到那个时候发现问题再改代价通常已经非常高了。AR开发的核心是“真实世界的物理体验”尽早进入真实环境调试胜过一切编辑器里的完美预览。