简介AR-Android是一套面向Android平台的增强现实开发框架及配套Unity示例工程适合有一定Android或Unity基础、希望在移动端快速集成AR功能的开发者使用。资源包内包含完整的Unity项目文件Assets、ProjectSettings、Packages以及可直接安装的Test.apk便于对照学习追踪技术、图像处理、3D渲染与用户交互等关键模块的实现方式。压缩包共49个文件以asset、meta、unity等Unity工程资源为主另含json配置、材质与测试包整体仅17.68MB结构清晰可直接导入Unity编辑器或安装到设备上体验。已有188人学习下载尤其适合作为入门AR-Android框架、理解工程组织与后续二次开发移植的参考样例。 当年我们团队从零开始接AR项目的时候第一个问题不是“怎么做”而是“在哪儿做”。iOS那边生态封闭、设备统一反而好办Android这边机型五花八门系统版本碎片化严重摄像头规格、传感器参数、屏幕比例全都不一样光是想到这些就头大。但真把一条路走通之后你会发现Android做AR反而有它的独特优势开放、灵活、可定制范围大尤其AR眼镜、车机这类新兴硬件基本都优先跑Android。这篇就想把我们在AR-Android项目里的完整思路整理出来包括环境搭建、核心功能实现、性能调优和踩坑记录给正在做或准备做Android端AR开发的同学做个参考。我默认你至少有Android开发基础知道Activity、Service、Gradle这些概念但不用精通图形学和OpenGL。涉及AR绘制的部分我会尽量讲清楚原理再给你能直接跑通的代码和配置。1. 内容整体设计与思路拆解1.1 先想清楚AR功能需要哪些底层能力AR增强现实的本质是把虚拟内容叠加到现实画面里并且让它看起来“钉”在真实世界上。要实现这个效果至少需要三块能力实时取景摄像头画面要能流畅地显示在屏幕上这是AR的地基。Android上取景方案有CameraX、Camera2还有基于SurfaceView/TextureView的自定义方案。姿态追踪手机要能算出自己在三维空间里的位置和朝向。这部分通常依赖设备自带的IMU惯性测量单元就是陀螺仪加速度计磁力计和视觉特征点配合。ARCore帮你做了这件事你不需要从零写视觉定位算法。虚拟内容渲染把3D模型、UI控件或粒子效果叠加到相机画面上并且跟随姿态变化实时更新。渲染可以用OpenGL ES、Vulkan或者现成的3D引擎比如Unity。从零实现这三块不是不行但工程量巨大而且精度很难赶上ARCore、ARKit这种成熟框架的水平。我们当时的决定很简单视觉追踪和空间理解直接用ARCore渲染交给OpenGL ES 自定义绘制层UI层保留Android原生View体系。这样既保证了核心体验的稳定性又保留了UI灵活定制的空间。1.2 为什么不直接上Unity非要选原生Android开发这是项目启动时团队内部吵得最凶的问题。Unity做AR确实方便Asset Store里一大堆现成插件场景搭建可视化多人协作也成熟。但对于我们这个项目来说原生开发反而是当时环境下的合理选择。原因一是包体敏感。我们的应用需要下发到多款中低端设备上Unity引擎本身至少十几MB起步加上AR Foundation和相关依赖包体直接多出几十MB对下载转化率和低配机性能都有影响。原生ARCore SDK只有几百KB配合MediaPipe手势识别和UI组件整体增量可以控制在几MB。原因二是Andro生生态的定制能力。我们需要和系统的蓝牙、文件存储、外设驱动比如i2c设备通信交互Unity在这些底层能力上封装比较厚调试起来绕路。直接使用Android原生API是最短的路径。再加上我们团队本身就有长期Android开发积累周边库、代码复用、性能分析工具都比较熟原生路线能最大程度发挥现有经验。这里不是劝退Unity方案而是想说技术选型没有绝对的对错要看你手里的约束条件。如果你的团队Unity功底更强、产品重交互场景且不苛求包体那Unity完全没问题。但如果产品业务逻辑和Android系统能力耦合很深原生方向值得认真考虑。1.3 技术栈全景图我们到底用了哪些东西项目落地时用到的核心依赖和工具大致如下模块选型用途说明语言Kotlin Java混编Kotlin负责业务逻辑Java保留部分遗留模块AR能力ARCore SDK姿态追踪、平面检测、光照估计相机CameraX处理相机生命周期、预览、拍摄兼容性好手势识别MediaPipe Task Library手部关键点检测用于AR交互渲染OpenGL ES 3.0绘制虚拟模型、覆盖层平衡兼容与性能UI原生View体系 ConstraintLayout控制面板、状态栏、提示文案构建Gradle AGP 8.x模块化构建多渠道打包这个栈搭配下来一个相机预览AR模型叠加手势交互的Demo大约需要两周时间后面主要精力都花在调优和适配上了。2. 核心细节解析与实操要点2.1 ARCore工作原理解读它凭什么能算出手机在哪儿ARCore的追踪能力由三个引擎协同完成理解它们对后续调参会很有帮助动作追踪Motion Tracking通过IMU的数据计算手机在三维空间中的相对位移和旋转解决“动没动、怎么动”的问题。IMU有累积误差时间一长会漂移所以需要第二块来矫正。环境理解Environmental Understanding通过摄像头逐帧捕捉图像识别特征点找出平面地板、桌面、墙面。这个环节解决了“世界长什么样”的问题为虚拟内容提供落脚点。光照估计Light Estimation分析当前环境的光照强度和色温让虚拟物体在光影上与真实场景匹配增强沉浸感。这三块加在一起ARCore才能真正把虚拟坐标和真实世界锚定。这也是为什么AR功能对相机和传感器要求很高——中低端机传感器性能弱追踪精度下降表现就是AR模型总在飘。2.2 CameraX还是Camera2这是个值得想清楚的问题相机是AR的眼睛选错了后面全是坑。我们早期尝试用Camera2直接对接API表面看定制性最强但代码量非常大需要处理大量的状态回调和旋转逻辑。尤其当ARCore和相机同时打开时冲突处理一不小心就会让预览黑屏。CameraX完美解决了大部分痛点生命周期感知CameraX和Activity或Fragment的生命周期绑定你不用手动管理释放和重新绑定用例组合方便Preview、ImageAnalysis、ImageCapture可以同时使用互不干扰设备兼容性底层帮你兼容了绝大多数厂商的相机HAL实现省去了几千行适配代码我建议新项目直接用CameraX除非你的相机应用场景特殊到需要直接操作Camera2参数比如自定义曝光时间、特殊HDR策略否则不要自己去造相机轮子。// CameraX绑定预览用例的简化示例 val preview Preview.Builder() .setTargetResolution(Size(1280, 720)) .build() val previewView findViewByIdPreviewView(R.id.preview_view) preview.setSurfaceProvider(previewView.surfaceProvider) cameraProvider.unbindAll() cameraProvider.bindToLifecycle( this, CameraSelector.DEFAULT_BACK_CAMERA, preview )比较关键的一点是预览分辨率的选择。720p到1080p之间是平衡点太高会影响帧率太低画面模糊。我们实测在大部分设备上720p预览配合ARCore追踪帧率能稳定在30fps左右。2.3 手势识别集成MediaPipe和AR结合的交互思路很早我们就有个直觉AR加手势才是未来的交互方式纯点按屏幕太没想象空间了。当时调研了几套开源方案最后选定MediaPipe。它在Android上集成相对简单支持CPU/GPU加速模型体积小尤其手部关键点检测速度很快。MediaPipe的最新版本推荐用Task Library方式集成比老的Solution API更简洁而且支持流式处理。典型流程如下// 使用MediaPipe HandLandmarker的伪代码示例 val options HandLandmarkerOptions.builder() .setBaseOptions(BaseOptions.builder().setModelAssetPath(hand_landmarker.task).build()) .setMinHandDetectionConfidence(0.5f) .setMinHandPresenceConfidence(0.5f) .setMinTrackingConfidence(0.5f) .setNumHands(1) .build() val handLandmarker HandLandmarker.createFromOptions(context, options)模型文件从官方站点下载注意要和库版本匹配不然运行时报错。此外还要注意MediaPipe需要相机权限同时建议将相机预览帧转换为YUV_420_888格式再输入模型避免RGB转换带来的额外开销。手势识别在AR里能做什么我们实现了几个典型玩法手势指向检测到食指关键点方向生成一条射线用户可以用手“指”按钮手掌遮挡把虚拟物体挡在手后面增强真实感捏合缩放拇指和食指间距控制模型缩放和手机双指缩放体验一致实现难度从低到高但也别指望像科幻电影里那样精确流畅。实际体验中手势识别延迟在100ms左右是正常水平我们花了很多精力做平滑算法关键点位置加权平均、数据插值才让手势看起来不那么“抖”。2.4 AR眼镜和i2c这类外设在Android端的接入思路AR项目的终极形态不是手机屏幕而是AR眼镜。我们当时也顺便调研了AR眼镜在Android上的接入方式。市面上很多AR眼镜本质是外接显示器使用USB/DP协议直接通过USB-C连接手机后就能镜像屏幕画面虽然能做到左右眼分屏显示3D效果但交互和传感器信息无法回传体验受限。如果要做更深的交互就需要和眼镜端的光学模组、姿态传感器通信。比如i2c设备在Android上可以通过Linux的i2c-dev节点直接读写。但Android系统本身默认不允许普通应用访问i2c总线需要root或系统级签名权限。热词里有人搜“i2c-tools在Android上使用”说明这个需求真实存在。实际使用时要么在Rom层把权限放开要么通过厂商提供的SDK走OEM通道建议优先联系眼镜厂商拿官方SDK不要自己啃硬件协议。3. 实操过程与核心环节实现3.1 完整实操流程从新工程到AR模型上屏下面我把最具代表性的一条主线流程完整走一遍初始化ARCore会话、绑定相机预览、识别平面、放置模型。这套流程几乎是所有AR应用的标准骨架后面加什么功能都是在这个骨架上长出来的。第一步确认设备支持ARCore在真机上运行前必须检查ARCore是否可用否则会在初始化阶段直接异常退出。val isArCoreSupported arCoreApk.checkAvailability(this) when (isArCoreSupported) { SUPPORTED - Log.i(AR, 设备支持ARCore) SUPPORTED_APK_TOO_OLD - promptUserToUpdate() UNSUPPORTED - Toast.makeText(this, 设备不支持AR, Toast.LENGTH_LONG).show() }这里有个容易忽略的点ARCore要求设备达到一定性能基线很多低端机或小厂平板不在支持列表里。Google官方有个已认证设备列表上线前一定要做机型白名单不然用户在旧手机上点击“开始AR”会瞬间崩溃。第二步配置Manifest权限ARCore必须的权限包括相机权限如果用到存储、网络也要在Manifest里明确声明。uses-permission android:nameandroid.permission.CAMERA / uses-feature android:nameandroid.hardware.camera.ar android:requiredtrue / meta-data android:namecom.google.ar.core android:valuerequired /requiredtrue这点要谨慎。如果设为trueGoogle Play会在不支持的设备上直接隐藏你的应用降低曝光量。如果只是AR作为运营位功能比如相机滤镜建议改成requiredfalse用代码动态排查能力。第三步ARCore会话初始化与配置val session Session(this) val config Config(session) config.planeFindingMode Config.PlaneFindingMode.HORIZONTAL session.configure(config)这里的平面检测模式按需调整水平平面适合放置物品竖直平面适合贴海报类效果。配置项还包括光照估计模式、深度模式、焦点模式等。我们项目最终选择了水平面光照估计的组合因为核心场景是桌面展示光照估计能显著提高模型质感。第四步把模型画上去ARCore本身不负责渲染它只提供数据和坐标系。渲染这块我们用的是SceneView一款开源的AR渲染库它在ARCore之上封装了3D场景、光照和相机控制代码简洁很多。io.github.sceneview.ar.ArSceneView android:idid/ar_scene_view android:layout_widthmatch_parent android:layout_heightmatch_parent /val arSceneView findViewByIdArSceneView(R.id.ar_scene_view) arSceneView.session session // 监听点击在点击位置放置模型 arSceneView.setOnTouchListener { _, event - if (event.action MotionEvent.ACTION_UP) { val hitResult arSceneView.hitTest(event.x, event.y) if (hitResult ! null) { val node Node() node.parent arSceneView node.position hitResult.position node.renderable ModelLoader.loadModel(this, R.raw.my_model) } } true }这段代码的逻辑是用户点击屏幕进行射线检测hitTest拿到点击位置在真实世界中的三维坐标然后把3D模型放到这个位置上。实际项目中还要加模型朝向调整、缩放限制、多个模型同时存在时的管理逻辑。3.2 没有真机时虚拟设备能不能跑AR答案很干脆不能。ARCore依赖真实的摄像头和IMU数据Android模拟器尽管有虚拟摄像头可以投屏一张图片但姿态和传感器数据是模拟的ARCore的追踪算法在模拟器里几乎无法正常工作。你会发现模型浮在画面中转动机身毫无反应完全无法验证体验。所以AR开发必备一台真机。如果条件有限建议优先保证以下几类测试品牌机型齐备性能旗舰如高通8系处理器机型、中端走量机骁龙7系、天玑8系、入门机骁龙6系。这几种梯度覆盖了AR性能差异的大部分场景。3.3 机型适配的三个细节屏幕比例、相机镜像、传感器方向屏幕比例不同机型屏幕高宽比差异大虚拟内容的坐标范围要按屏幕宽高动态计算否则会出现内容偏移或超出屏幕。相机镜像前置摄像头出图是镜像的AR标注定位时如果不做镜像翻转手指点击的坐标和识别到的内容位置会对不上。传感器方向有些设备的传感器安装角度特殊特别是平板上导致俯仰角数据偏转需要根据官方参考校准。这三个问题本质上都是同一件事Android设备参数的多样性和操作系统的碎片化。所以AR项目的测试矩阵要远大于普通应用提前安排一定数量的真机测试能省下后面上线后处理差评的功夫。4. 常见问题与排查技巧实录4.1 AGP版本和Android Studio版本对不上开发阶段最常见的报错就是类似“Android Studio Hedgehog | 2023.1.1 Patch 2支持AGP 8版本吗”这类问题。实际答案是Hedgehog版本内置支持AGP 8.0-8.2你手动改成AGP 8.3以上也大概率能跑但不保证官方支持。Gradle插件版本和IDE版本有严格的兼容矩阵踩踏这类问题浪费的时间最多。解决方案很简单打开项目的build.gradle文件查看并调整AGP版本号至与你的IDE版本匹配的稳定版本。例如Hedgehog对应AGP 8.1.2Iguana对应AGP 8.3.0。// 项目根目录build.gradle plugins { id com.android.application version 8.1.2 apply false id com.android.library version 8.1.2 apply false }不要盲目追求最新版插件稳定比新功能重要。4.2 “Could not load compiled classes for settings file” 怎么解决这个报错的背景是Gradle同步时缓存损坏。当时的排查路径很清楚先确认是不是settings.gradle文件本身写错了括号不匹配、plugin声明冲突确认无误后直接删除项目根目录下的.gradle文件夹然后执行File - Invalidate Caches and Restart让Gradle重新解析。如果还不行检查是否有多个Gradle守护进程冲突在命令行执行./gradlew stop杀掉全部守护进程再重新构建。我在Windows上遇到过几次文件占用导致的缓存损坏基本上重置缓存就能解除。4.3 Android 11以上文件访问权限变化AR项目如何适配AR项目需要加载本地3D模型文件或导出录屏视频所以文件访问是绕不开的问题。Android 11及以上版本对Android/data目录访问限制很严格AR项目常见的一个报错就是对content://com.android.externalstorage.documents路径解析失败。我的建议是不要直接用file:///storage/emulated/0/Android/data/...路径读写。正确做法是使用IntentACTION_OPEN_DOCUMENT让用户选择文件系统会返回content://开头的URI借助ContentResolver打开文件流避免大量权限声明和路径兼容问题。对于AR模型这类资源能打包到APK的尽量打包进去既不依赖运行时权限也简化用户使用路径。4.4 Android Studio火焰图定位AR卡顿的实战方法用户反映AR画面卡顿这是个玄学问题解决起来很痛苦。刚开始靠猜后来用了Android Studio自带的Profile工具很快定位到问题出在模型渲染线程上。操作大致是这样连上真机并打开应用进入Profiler面板选择CPU并录制一段卡顿时间段的火焰图数据。火焰图里每一根横条代表一个函数调用横条宽度代表调用耗时宽条在图顶端然后向下延伸形成“火苗”状所以叫火焰图。实际排查看火焰图的时候重点盯住两个东西顶层横条是否被某个函数占了大半宽度如果有说明该函数是主要耗时点有没有同步I/O或Object的序列化操作卡在渲染线程这些往往是性能瓶颈我们那次在火焰图里发现GLSurfaceView.onDrawFrame阻塞在bitmap.copy上原因是每帧都会重新加载纹理资源。优化方式是把纹理加载移到初始化阶段缓存运行时只做GPU上传和复用。经过这个优化帧率从18fps提到了30fps观感提升非常明显。火焰图的核心价值一句话它让你不靠猜测就能看到代码在真实设备上的执行时间分布。对AR这类对帧率敏感的App来说这个工具应该成为日常标配。4.5 AR应用被杀掉后重启的问题有次测试发现杀进程后重进AppAR界面恢复得特别慢甚至黑屏。排查后确认原因是ARCore会话被强制杀死后重新初始化Session需要几秒钟期间相机预览和渲染都处于等待状态。优化思路是让ARCore的初始化尽早执行在冷启动阶段预创建Session并把相机启动和ARCore初始化做成并行而不是串行。另一个常见的坑是应用被系统放在后台时间过长后再次回到前台会触发“应用杀掉就重启”的体验问题。解决方案是把AR相关状态做持久化比如把标识、锚点坐标保存到SharedPreferencesApp再次拉起时可以快速恢复场景不用用户重新摆放模型。4.6 部分Android应用被限制访问网络AR模型怎么加载有用户遇到AR模型加载失败后来发现是系统App管理里这个应用被限制了网络访问。这个算是个冷门问题常见于国产定制ROM小米、华为等的“联网控制”功能。App默认处于受限模式导致云端模型无法下载。排查思路很简单检查NetworkSecurityConfig配置、确认应用没有开启省流量模式、检查系统的联网控制白名单。如果是走HTTPS下载模型还要确认证书链完整不要用自签名证书上线。模型资源如果能打进APK就最好打进APK既能规避网络问题也减少首屏加载时间。4.7 其他零碎但坑人的问题汇总Android 14 root相关正常应用开发不需要考虑root如果测试机root了反而可能出现权限弹窗异常。建议至少保留一台纯净版系统的测试机。Android蓝牙与AR联动AR眼镜或外部控制器连接时蓝牙权限要在Android 12动态申请否则直接崩溃。协调布局Banner广告AR页面上方如果叠加了Banner要注意遮挡和触控事件透传问题。Banner会吃掉触摸事件导致AR场景无法进行旋转等手势操作。Android反编译相关AR应用一般涉及模型资源或SDK密钥需要做代码混淆和资源混淆R8开启后要确认ARCore和MediaPipe的混淆规则没有误伤。5. 深入思考模块化、扩展性与上线前的检查清单AR-Android这个方向单纯做出来只是第一步。一个产品要长期维护代码结构必须从一开始就为扩展留好空间。5.1 模块划分建议不管团队大小建议从项目早期就把模块边界划清楚app/ // 壳工程负责依赖注入和组装 |- features/ |- av/ // AR核心功能相机、追踪、渲染 |- ai/ // 推理相关MediaPipe手势识别、OCR等 |- libs/ // 蓝牙、传感器、外设通信 |- common/ // 工具类、网络、UI基础组件这样做的核心好处是方便回归测试和多人并行开发。AR核心功能有问题时只改一个模块不会牵连其他部分。AI模块模型升级时接口不变就能无缝替换。工程实践上我们踩过最大的坑是模块间互相引用。如果AR模块直接调用了蓝牙模块的内部类后续蓝牙链路升级时AR那边几乎必受影响。建议模块间尽量只依赖接口通过依赖注入框架如Hilt解耦。5.2 AR内容生产管线模型从哪来怎么优化AR模型的产出和优化流程经常被技术团队忽略但这部分是体验的关键。我们趟过的路可以整理成一条基线流程建模和动画美术用Blender/3ds Max/Maya产出glTF或FBX格式文件模型导出优先转成glTF 2.0格式理由是体积小、支持PBR材质而且SceneView支持好资源压缩纹理转成KTX2格式网格用Quantization压缩体积能缩小一半以上对低端机加载速度帮助很大运行时加载大模型肯定不能同步加载需要异步加载进度提示否则冷启动时间会不可接受我们有一个不到10MB的模型直接加载花了近5秒用户的耐心完全不够用。后来优化成异步多线程加载加了一个极小体积的占位体数据加载完成后再替换成真实模型体验好了很多。5.3 上线前检查清单最后分享一份我们整理的上线前检查清单不一定全但都是踩过坑的真机兼容性至少跑过覆盖Top 30机型中的10台以上重点看中低端性能权限申请流程首次进入页面的权限引导是否清晰拒绝后是否有二次引导ARCore降级方案设备不支持ARCore时页面是否有合理的回退交互比如提示使用普通模式模型拉伸/适配超大屏、带刘海屏、折叠屏三种规格是否都有验证性能监控帧率、内存占用、崩溃率是否达到内部基准帧率≥25fps内存≤300MB混淆规则包括ARCore、MediaPipe、SceneView的混淆规则全部验证过审核规范应用内是否有明确的隐私政策和用户告知相机权限用途描述要写得清楚这份清单不花哨但每一条背后都是真金白银的用户反馈换来的。6. 写在最后的一点体会做AR-Android项目这两年最大的感受是AR开发不能只盯代码你要对整个Android生态有足够宽的知识。相机、传感器、图形渲染、系统权限、厂商定制ROM每一层都可能成为你的拦路虎。但换个角度想如果你能把这条链路摸透你的经验价值也远超普通Android开发。AR是个很有想象力的方向从手机到眼镜到车载每一步都值得认真跟。希望这篇内容能帮你少走一些弯路。本文还有配套的精品资源点击获取
Android AR开发实战：ARCore、CameraX与性能调优指南
简介AR-Android是一套面向Android平台的增强现实开发框架及配套Unity示例工程适合有一定Android或Unity基础、希望在移动端快速集成AR功能的开发者使用。资源包内包含完整的Unity项目文件Assets、ProjectSettings、Packages以及可直接安装的Test.apk便于对照学习追踪技术、图像处理、3D渲染与用户交互等关键模块的实现方式。压缩包共49个文件以asset、meta、unity等Unity工程资源为主另含json配置、材质与测试包整体仅17.68MB结构清晰可直接导入Unity编辑器或安装到设备上体验。已有188人学习下载尤其适合作为入门AR-Android框架、理解工程组织与后续二次开发移植的参考样例。 当年我们团队从零开始接AR项目的时候第一个问题不是“怎么做”而是“在哪儿做”。iOS那边生态封闭、设备统一反而好办Android这边机型五花八门系统版本碎片化严重摄像头规格、传感器参数、屏幕比例全都不一样光是想到这些就头大。但真把一条路走通之后你会发现Android做AR反而有它的独特优势开放、灵活、可定制范围大尤其AR眼镜、车机这类新兴硬件基本都优先跑Android。这篇就想把我们在AR-Android项目里的完整思路整理出来包括环境搭建、核心功能实现、性能调优和踩坑记录给正在做或准备做Android端AR开发的同学做个参考。我默认你至少有Android开发基础知道Activity、Service、Gradle这些概念但不用精通图形学和OpenGL。涉及AR绘制的部分我会尽量讲清楚原理再给你能直接跑通的代码和配置。1. 内容整体设计与思路拆解1.1 先想清楚AR功能需要哪些底层能力AR增强现实的本质是把虚拟内容叠加到现实画面里并且让它看起来“钉”在真实世界上。要实现这个效果至少需要三块能力实时取景摄像头画面要能流畅地显示在屏幕上这是AR的地基。Android上取景方案有CameraX、Camera2还有基于SurfaceView/TextureView的自定义方案。姿态追踪手机要能算出自己在三维空间里的位置和朝向。这部分通常依赖设备自带的IMU惯性测量单元就是陀螺仪加速度计磁力计和视觉特征点配合。ARCore帮你做了这件事你不需要从零写视觉定位算法。虚拟内容渲染把3D模型、UI控件或粒子效果叠加到相机画面上并且跟随姿态变化实时更新。渲染可以用OpenGL ES、Vulkan或者现成的3D引擎比如Unity。从零实现这三块不是不行但工程量巨大而且精度很难赶上ARCore、ARKit这种成熟框架的水平。我们当时的决定很简单视觉追踪和空间理解直接用ARCore渲染交给OpenGL ES 自定义绘制层UI层保留Android原生View体系。这样既保证了核心体验的稳定性又保留了UI灵活定制的空间。1.2 为什么不直接上Unity非要选原生Android开发这是项目启动时团队内部吵得最凶的问题。Unity做AR确实方便Asset Store里一大堆现成插件场景搭建可视化多人协作也成熟。但对于我们这个项目来说原生开发反而是当时环境下的合理选择。原因一是包体敏感。我们的应用需要下发到多款中低端设备上Unity引擎本身至少十几MB起步加上AR Foundation和相关依赖包体直接多出几十MB对下载转化率和低配机性能都有影响。原生ARCore SDK只有几百KB配合MediaPipe手势识别和UI组件整体增量可以控制在几MB。原因二是Andro生生态的定制能力。我们需要和系统的蓝牙、文件存储、外设驱动比如i2c设备通信交互Unity在这些底层能力上封装比较厚调试起来绕路。直接使用Android原生API是最短的路径。再加上我们团队本身就有长期Android开发积累周边库、代码复用、性能分析工具都比较熟原生路线能最大程度发挥现有经验。这里不是劝退Unity方案而是想说技术选型没有绝对的对错要看你手里的约束条件。如果你的团队Unity功底更强、产品重交互场景且不苛求包体那Unity完全没问题。但如果产品业务逻辑和Android系统能力耦合很深原生方向值得认真考虑。1.3 技术栈全景图我们到底用了哪些东西项目落地时用到的核心依赖和工具大致如下模块选型用途说明语言Kotlin Java混编Kotlin负责业务逻辑Java保留部分遗留模块AR能力ARCore SDK姿态追踪、平面检测、光照估计相机CameraX处理相机生命周期、预览、拍摄兼容性好手势识别MediaPipe Task Library手部关键点检测用于AR交互渲染OpenGL ES 3.0绘制虚拟模型、覆盖层平衡兼容与性能UI原生View体系 ConstraintLayout控制面板、状态栏、提示文案构建Gradle AGP 8.x模块化构建多渠道打包这个栈搭配下来一个相机预览AR模型叠加手势交互的Demo大约需要两周时间后面主要精力都花在调优和适配上了。2. 核心细节解析与实操要点2.1 ARCore工作原理解读它凭什么能算出手机在哪儿ARCore的追踪能力由三个引擎协同完成理解它们对后续调参会很有帮助动作追踪Motion Tracking通过IMU的数据计算手机在三维空间中的相对位移和旋转解决“动没动、怎么动”的问题。IMU有累积误差时间一长会漂移所以需要第二块来矫正。环境理解Environmental Understanding通过摄像头逐帧捕捉图像识别特征点找出平面地板、桌面、墙面。这个环节解决了“世界长什么样”的问题为虚拟内容提供落脚点。光照估计Light Estimation分析当前环境的光照强度和色温让虚拟物体在光影上与真实场景匹配增强沉浸感。这三块加在一起ARCore才能真正把虚拟坐标和真实世界锚定。这也是为什么AR功能对相机和传感器要求很高——中低端机传感器性能弱追踪精度下降表现就是AR模型总在飘。2.2 CameraX还是Camera2这是个值得想清楚的问题相机是AR的眼睛选错了后面全是坑。我们早期尝试用Camera2直接对接API表面看定制性最强但代码量非常大需要处理大量的状态回调和旋转逻辑。尤其当ARCore和相机同时打开时冲突处理一不小心就会让预览黑屏。CameraX完美解决了大部分痛点生命周期感知CameraX和Activity或Fragment的生命周期绑定你不用手动管理释放和重新绑定用例组合方便Preview、ImageAnalysis、ImageCapture可以同时使用互不干扰设备兼容性底层帮你兼容了绝大多数厂商的相机HAL实现省去了几千行适配代码我建议新项目直接用CameraX除非你的相机应用场景特殊到需要直接操作Camera2参数比如自定义曝光时间、特殊HDR策略否则不要自己去造相机轮子。// CameraX绑定预览用例的简化示例 val preview Preview.Builder() .setTargetResolution(Size(1280, 720)) .build() val previewView findViewByIdPreviewView(R.id.preview_view) preview.setSurfaceProvider(previewView.surfaceProvider) cameraProvider.unbindAll() cameraProvider.bindToLifecycle( this, CameraSelector.DEFAULT_BACK_CAMERA, preview )比较关键的一点是预览分辨率的选择。720p到1080p之间是平衡点太高会影响帧率太低画面模糊。我们实测在大部分设备上720p预览配合ARCore追踪帧率能稳定在30fps左右。2.3 手势识别集成MediaPipe和AR结合的交互思路很早我们就有个直觉AR加手势才是未来的交互方式纯点按屏幕太没想象空间了。当时调研了几套开源方案最后选定MediaPipe。它在Android上集成相对简单支持CPU/GPU加速模型体积小尤其手部关键点检测速度很快。MediaPipe的最新版本推荐用Task Library方式集成比老的Solution API更简洁而且支持流式处理。典型流程如下// 使用MediaPipe HandLandmarker的伪代码示例 val options HandLandmarkerOptions.builder() .setBaseOptions(BaseOptions.builder().setModelAssetPath(hand_landmarker.task).build()) .setMinHandDetectionConfidence(0.5f) .setMinHandPresenceConfidence(0.5f) .setMinTrackingConfidence(0.5f) .setNumHands(1) .build() val handLandmarker HandLandmarker.createFromOptions(context, options)模型文件从官方站点下载注意要和库版本匹配不然运行时报错。此外还要注意MediaPipe需要相机权限同时建议将相机预览帧转换为YUV_420_888格式再输入模型避免RGB转换带来的额外开销。手势识别在AR里能做什么我们实现了几个典型玩法手势指向检测到食指关键点方向生成一条射线用户可以用手“指”按钮手掌遮挡把虚拟物体挡在手后面增强真实感捏合缩放拇指和食指间距控制模型缩放和手机双指缩放体验一致实现难度从低到高但也别指望像科幻电影里那样精确流畅。实际体验中手势识别延迟在100ms左右是正常水平我们花了很多精力做平滑算法关键点位置加权平均、数据插值才让手势看起来不那么“抖”。2.4 AR眼镜和i2c这类外设在Android端的接入思路AR项目的终极形态不是手机屏幕而是AR眼镜。我们当时也顺便调研了AR眼镜在Android上的接入方式。市面上很多AR眼镜本质是外接显示器使用USB/DP协议直接通过USB-C连接手机后就能镜像屏幕画面虽然能做到左右眼分屏显示3D效果但交互和传感器信息无法回传体验受限。如果要做更深的交互就需要和眼镜端的光学模组、姿态传感器通信。比如i2c设备在Android上可以通过Linux的i2c-dev节点直接读写。但Android系统本身默认不允许普通应用访问i2c总线需要root或系统级签名权限。热词里有人搜“i2c-tools在Android上使用”说明这个需求真实存在。实际使用时要么在Rom层把权限放开要么通过厂商提供的SDK走OEM通道建议优先联系眼镜厂商拿官方SDK不要自己啃硬件协议。3. 实操过程与核心环节实现3.1 完整实操流程从新工程到AR模型上屏下面我把最具代表性的一条主线流程完整走一遍初始化ARCore会话、绑定相机预览、识别平面、放置模型。这套流程几乎是所有AR应用的标准骨架后面加什么功能都是在这个骨架上长出来的。第一步确认设备支持ARCore在真机上运行前必须检查ARCore是否可用否则会在初始化阶段直接异常退出。val isArCoreSupported arCoreApk.checkAvailability(this) when (isArCoreSupported) { SUPPORTED - Log.i(AR, 设备支持ARCore) SUPPORTED_APK_TOO_OLD - promptUserToUpdate() UNSUPPORTED - Toast.makeText(this, 设备不支持AR, Toast.LENGTH_LONG).show() }这里有个容易忽略的点ARCore要求设备达到一定性能基线很多低端机或小厂平板不在支持列表里。Google官方有个已认证设备列表上线前一定要做机型白名单不然用户在旧手机上点击“开始AR”会瞬间崩溃。第二步配置Manifest权限ARCore必须的权限包括相机权限如果用到存储、网络也要在Manifest里明确声明。uses-permission android:nameandroid.permission.CAMERA / uses-feature android:nameandroid.hardware.camera.ar android:requiredtrue / meta-data android:namecom.google.ar.core android:valuerequired /requiredtrue这点要谨慎。如果设为trueGoogle Play会在不支持的设备上直接隐藏你的应用降低曝光量。如果只是AR作为运营位功能比如相机滤镜建议改成requiredfalse用代码动态排查能力。第三步ARCore会话初始化与配置val session Session(this) val config Config(session) config.planeFindingMode Config.PlaneFindingMode.HORIZONTAL session.configure(config)这里的平面检测模式按需调整水平平面适合放置物品竖直平面适合贴海报类效果。配置项还包括光照估计模式、深度模式、焦点模式等。我们项目最终选择了水平面光照估计的组合因为核心场景是桌面展示光照估计能显著提高模型质感。第四步把模型画上去ARCore本身不负责渲染它只提供数据和坐标系。渲染这块我们用的是SceneView一款开源的AR渲染库它在ARCore之上封装了3D场景、光照和相机控制代码简洁很多。io.github.sceneview.ar.ArSceneView android:idid/ar_scene_view android:layout_widthmatch_parent android:layout_heightmatch_parent /val arSceneView findViewByIdArSceneView(R.id.ar_scene_view) arSceneView.session session // 监听点击在点击位置放置模型 arSceneView.setOnTouchListener { _, event - if (event.action MotionEvent.ACTION_UP) { val hitResult arSceneView.hitTest(event.x, event.y) if (hitResult ! null) { val node Node() node.parent arSceneView node.position hitResult.position node.renderable ModelLoader.loadModel(this, R.raw.my_model) } } true }这段代码的逻辑是用户点击屏幕进行射线检测hitTest拿到点击位置在真实世界中的三维坐标然后把3D模型放到这个位置上。实际项目中还要加模型朝向调整、缩放限制、多个模型同时存在时的管理逻辑。3.2 没有真机时虚拟设备能不能跑AR答案很干脆不能。ARCore依赖真实的摄像头和IMU数据Android模拟器尽管有虚拟摄像头可以投屏一张图片但姿态和传感器数据是模拟的ARCore的追踪算法在模拟器里几乎无法正常工作。你会发现模型浮在画面中转动机身毫无反应完全无法验证体验。所以AR开发必备一台真机。如果条件有限建议优先保证以下几类测试品牌机型齐备性能旗舰如高通8系处理器机型、中端走量机骁龙7系、天玑8系、入门机骁龙6系。这几种梯度覆盖了AR性能差异的大部分场景。3.3 机型适配的三个细节屏幕比例、相机镜像、传感器方向屏幕比例不同机型屏幕高宽比差异大虚拟内容的坐标范围要按屏幕宽高动态计算否则会出现内容偏移或超出屏幕。相机镜像前置摄像头出图是镜像的AR标注定位时如果不做镜像翻转手指点击的坐标和识别到的内容位置会对不上。传感器方向有些设备的传感器安装角度特殊特别是平板上导致俯仰角数据偏转需要根据官方参考校准。这三个问题本质上都是同一件事Android设备参数的多样性和操作系统的碎片化。所以AR项目的测试矩阵要远大于普通应用提前安排一定数量的真机测试能省下后面上线后处理差评的功夫。4. 常见问题与排查技巧实录4.1 AGP版本和Android Studio版本对不上开发阶段最常见的报错就是类似“Android Studio Hedgehog | 2023.1.1 Patch 2支持AGP 8版本吗”这类问题。实际答案是Hedgehog版本内置支持AGP 8.0-8.2你手动改成AGP 8.3以上也大概率能跑但不保证官方支持。Gradle插件版本和IDE版本有严格的兼容矩阵踩踏这类问题浪费的时间最多。解决方案很简单打开项目的build.gradle文件查看并调整AGP版本号至与你的IDE版本匹配的稳定版本。例如Hedgehog对应AGP 8.1.2Iguana对应AGP 8.3.0。// 项目根目录build.gradle plugins { id com.android.application version 8.1.2 apply false id com.android.library version 8.1.2 apply false }不要盲目追求最新版插件稳定比新功能重要。4.2 “Could not load compiled classes for settings file” 怎么解决这个报错的背景是Gradle同步时缓存损坏。当时的排查路径很清楚先确认是不是settings.gradle文件本身写错了括号不匹配、plugin声明冲突确认无误后直接删除项目根目录下的.gradle文件夹然后执行File - Invalidate Caches and Restart让Gradle重新解析。如果还不行检查是否有多个Gradle守护进程冲突在命令行执行./gradlew stop杀掉全部守护进程再重新构建。我在Windows上遇到过几次文件占用导致的缓存损坏基本上重置缓存就能解除。4.3 Android 11以上文件访问权限变化AR项目如何适配AR项目需要加载本地3D模型文件或导出录屏视频所以文件访问是绕不开的问题。Android 11及以上版本对Android/data目录访问限制很严格AR项目常见的一个报错就是对content://com.android.externalstorage.documents路径解析失败。我的建议是不要直接用file:///storage/emulated/0/Android/data/...路径读写。正确做法是使用IntentACTION_OPEN_DOCUMENT让用户选择文件系统会返回content://开头的URI借助ContentResolver打开文件流避免大量权限声明和路径兼容问题。对于AR模型这类资源能打包到APK的尽量打包进去既不依赖运行时权限也简化用户使用路径。4.4 Android Studio火焰图定位AR卡顿的实战方法用户反映AR画面卡顿这是个玄学问题解决起来很痛苦。刚开始靠猜后来用了Android Studio自带的Profile工具很快定位到问题出在模型渲染线程上。操作大致是这样连上真机并打开应用进入Profiler面板选择CPU并录制一段卡顿时间段的火焰图数据。火焰图里每一根横条代表一个函数调用横条宽度代表调用耗时宽条在图顶端然后向下延伸形成“火苗”状所以叫火焰图。实际排查看火焰图的时候重点盯住两个东西顶层横条是否被某个函数占了大半宽度如果有说明该函数是主要耗时点有没有同步I/O或Object的序列化操作卡在渲染线程这些往往是性能瓶颈我们那次在火焰图里发现GLSurfaceView.onDrawFrame阻塞在bitmap.copy上原因是每帧都会重新加载纹理资源。优化方式是把纹理加载移到初始化阶段缓存运行时只做GPU上传和复用。经过这个优化帧率从18fps提到了30fps观感提升非常明显。火焰图的核心价值一句话它让你不靠猜测就能看到代码在真实设备上的执行时间分布。对AR这类对帧率敏感的App来说这个工具应该成为日常标配。4.5 AR应用被杀掉后重启的问题有次测试发现杀进程后重进AppAR界面恢复得特别慢甚至黑屏。排查后确认原因是ARCore会话被强制杀死后重新初始化Session需要几秒钟期间相机预览和渲染都处于等待状态。优化思路是让ARCore的初始化尽早执行在冷启动阶段预创建Session并把相机启动和ARCore初始化做成并行而不是串行。另一个常见的坑是应用被系统放在后台时间过长后再次回到前台会触发“应用杀掉就重启”的体验问题。解决方案是把AR相关状态做持久化比如把标识、锚点坐标保存到SharedPreferencesApp再次拉起时可以快速恢复场景不用用户重新摆放模型。4.6 部分Android应用被限制访问网络AR模型怎么加载有用户遇到AR模型加载失败后来发现是系统App管理里这个应用被限制了网络访问。这个算是个冷门问题常见于国产定制ROM小米、华为等的“联网控制”功能。App默认处于受限模式导致云端模型无法下载。排查思路很简单检查NetworkSecurityConfig配置、确认应用没有开启省流量模式、检查系统的联网控制白名单。如果是走HTTPS下载模型还要确认证书链完整不要用自签名证书上线。模型资源如果能打进APK就最好打进APK既能规避网络问题也减少首屏加载时间。4.7 其他零碎但坑人的问题汇总Android 14 root相关正常应用开发不需要考虑root如果测试机root了反而可能出现权限弹窗异常。建议至少保留一台纯净版系统的测试机。Android蓝牙与AR联动AR眼镜或外部控制器连接时蓝牙权限要在Android 12动态申请否则直接崩溃。协调布局Banner广告AR页面上方如果叠加了Banner要注意遮挡和触控事件透传问题。Banner会吃掉触摸事件导致AR场景无法进行旋转等手势操作。Android反编译相关AR应用一般涉及模型资源或SDK密钥需要做代码混淆和资源混淆R8开启后要确认ARCore和MediaPipe的混淆规则没有误伤。5. 深入思考模块化、扩展性与上线前的检查清单AR-Android这个方向单纯做出来只是第一步。一个产品要长期维护代码结构必须从一开始就为扩展留好空间。5.1 模块划分建议不管团队大小建议从项目早期就把模块边界划清楚app/ // 壳工程负责依赖注入和组装 |- features/ |- av/ // AR核心功能相机、追踪、渲染 |- ai/ // 推理相关MediaPipe手势识别、OCR等 |- libs/ // 蓝牙、传感器、外设通信 |- common/ // 工具类、网络、UI基础组件这样做的核心好处是方便回归测试和多人并行开发。AR核心功能有问题时只改一个模块不会牵连其他部分。AI模块模型升级时接口不变就能无缝替换。工程实践上我们踩过最大的坑是模块间互相引用。如果AR模块直接调用了蓝牙模块的内部类后续蓝牙链路升级时AR那边几乎必受影响。建议模块间尽量只依赖接口通过依赖注入框架如Hilt解耦。5.2 AR内容生产管线模型从哪来怎么优化AR模型的产出和优化流程经常被技术团队忽略但这部分是体验的关键。我们趟过的路可以整理成一条基线流程建模和动画美术用Blender/3ds Max/Maya产出glTF或FBX格式文件模型导出优先转成glTF 2.0格式理由是体积小、支持PBR材质而且SceneView支持好资源压缩纹理转成KTX2格式网格用Quantization压缩体积能缩小一半以上对低端机加载速度帮助很大运行时加载大模型肯定不能同步加载需要异步加载进度提示否则冷启动时间会不可接受我们有一个不到10MB的模型直接加载花了近5秒用户的耐心完全不够用。后来优化成异步多线程加载加了一个极小体积的占位体数据加载完成后再替换成真实模型体验好了很多。5.3 上线前检查清单最后分享一份我们整理的上线前检查清单不一定全但都是踩过坑的真机兼容性至少跑过覆盖Top 30机型中的10台以上重点看中低端性能权限申请流程首次进入页面的权限引导是否清晰拒绝后是否有二次引导ARCore降级方案设备不支持ARCore时页面是否有合理的回退交互比如提示使用普通模式模型拉伸/适配超大屏、带刘海屏、折叠屏三种规格是否都有验证性能监控帧率、内存占用、崩溃率是否达到内部基准帧率≥25fps内存≤300MB混淆规则包括ARCore、MediaPipe、SceneView的混淆规则全部验证过审核规范应用内是否有明确的隐私政策和用户告知相机权限用途描述要写得清楚这份清单不花哨但每一条背后都是真金白银的用户反馈换来的。6. 写在最后的一点体会做AR-Android项目这两年最大的感受是AR开发不能只盯代码你要对整个Android生态有足够宽的知识。相机、传感器、图形渲染、系统权限、厂商定制ROM每一层都可能成为你的拦路虎。但换个角度想如果你能把这条链路摸透你的经验价值也远超普通Android开发。AR是个很有想象力的方向从手机到眼镜到车载每一步都值得认真跟。希望这篇内容能帮你少走一些弯路。本文还有配套的精品资源点击获取
