1. 项目概述与核心价值最近在社区里看到不少朋友对Unity的AR开发感兴趣但往往卡在第一步——环境安装和基础配置上。网上的教程要么过于零散要么版本老旧照着做总会出现各种奇怪的报错。今天我就结合自己这几年在移动AR项目上的踩坑经验给大家从头到尾捋一遍一个标准的Unity ARFoundation演示项目的搭建流程。这不仅仅是点几个按钮我会把每一步背后的逻辑、为什么要这么选、以及可能遇到的坑都讲清楚。无论你是刚接触AR的开发者还是从其他引擎转过来想快速上手的这篇指南都能让你在半小时内拥有一个可以跑在真机Android/iOS上、能识别平面并放置虚拟物体的基础AR应用。我们最终的目标是得到一个干净、可扩展的项目基底而不是一个充满未知依赖的“黑箱”。ARFoundation是Unity官方推出的跨平台AR开发框架它本身是一个抽象层底层需要依赖ARKitiOS或ARCoreAndroid这样的平台提供商插件Provider Plugin来实现具体功能。所以我们的安装配置核心就是三步准备好Unity编辑器环境、通过Package Manager安装正确的ARFoundation及其提供者插件包、最后在项目设置中进行必要的平台配置。听起来简单但版本兼容性、包依赖、构建设置这三个地方最容易出问题我会重点展开。2. 环境准备与Unity编辑器配置在开始安装任何包之前一个稳定的“地基”——也就是Unity编辑器本身——至关重要。很多人忽视这一步直接用现有项目或随意下载一个版本导致后续问题不断。2.1 Unity版本选择与安装首先打开 Unity Hub 。我强烈建议使用Unity Hub来管理你的多个Unity版本和项目这比直接下载编辑器要方便得多。版本选择策略对于ARFoundation开发版本不是越新越好而是需要追求稳定性与生态兼容性。根据官方文档和社区反馈我推荐使用Unity 2021.3 LTS长期支持版或 2022.3 LTS。LTS版本经过长期测试Bug较少并且市面上大多数插件和教程都基于这些版本遇到问题更容易找到解决方案。避免使用最新的Tech Stream技术流版本它们可能包含不稳定的改动。在Unity Hub的“安装”标签页点击“安装编辑器”。选择推荐的LTS版本后在“添加模块”步骤务必根据你的目标平台勾选相应的构建支持模块开发Android应用勾选“Android Build Support”并且务必包含其子项“OpenJDK”和“Android SDK NDK Tools”。Unity会帮你安装这些必要的工具链省去手动配置环境变量的麻烦。开发iOS应用勾选 **“iOS Build Support”****。这需要在macOS系统上进行。注意即使你目前只开发一个平台也建议把另一个平台的构建支持一并装上。因为ARFoundation的包管理器解析依赖时可能会检查所有平台的设置缺失模块有时会引起不必要的警告。安装完成后通过Unity Hub创建一个新项目。模板选择“3D (Core)”即可。不要选择URP通用渲染管线或HDRP高清渲染管线的模板除非你明确知道你的AR项目需要这些高级渲染特性。基础3D模板使用内置渲染管线与ARFoundation的兼容性最广出问题概率最低。项目名称和路径避免使用中文或特殊字符。2.2 项目初始设置检查创建项目后先别急着装包进行两项快速检查颜色空间Color Space进入Edit - Project Settings - Player在任意平台下找到Other Settings部分中的Rendering。将Color Space从默认的Gamma改为Linear。线性颜色空间能提供更真实的光照和颜色混合是现代图形项目的标准也是许多AR效果如环境光估计正确工作的基础。图形APIGraphics API同样在Player Settings的Other Settings-Rendering下查看Auto Graphics API。对于Android确保Vulkan没有被放在OpenGL ES3之前。由于部分ARCore设备的驱动兼容性问题建议在Android平台禁用Vulkan只使用OpenGL ES3。你可以取消勾选Auto Graphics API然后移除Vulkan只保留OpenGL ES3。对于iOSMetal是唯一且最优的选择保持默认即可。这些前置工作能避免很多后期难以排查的渲染异常问题。3. 核心组件安装Package Manager 详解这是整个配置的核心环节。Unity的Package Manager是管理功能模块的工具我们需要通过它安装ARFoundation及其平台插件。3.1 打开与界面认知在Unity编辑器顶部菜单栏点击Window - Package Manager会打开包管理器窗口。窗口左上角的下拉菜单Packages默认显示In Project已安装的包。我们需要将其切换为Unity Registry。这里列出了Unity官方认证和托管的所有包。窗口视图通常有两种Simple和Advanced。确保你点击窗口右上角的Advanced下拉按钮并勾选了Show preview packages。因为AR相关的包有时会处于预览状态勾选后才能看到它们。3.2 安装 AR Foundation 核心包在Unity Registry列表中找到AR Foundation。点击它在右侧详情面板中你会看到版本选择下拉菜单。版本选择原则不要盲目选择最新的版本。点击版本号旁边的“查看文档”图标会跳转到该包的官方文档页面。查看文档的发布说明确认其兼容的Unity编辑器版本。对于Unity 2021.3 LTSAR Foundation 4.1.x 或 4.2.x是经过充分测试的稳定选择。我当前项目使用的是4.1.11非常稳定。选择好版本后点击右下角的Install按钮。安装过程会自动解析并安装其依赖包如XR Plugin Management、XR Interaction Toolkit基础版等。3.3 安装平台提供者插件 (Provider Plugins)AR Foundation是“大脑”它还需要“手脚”来操作具体设备。这就是平台提供者插件。对于 Android 开发在Package Manager的Unity Registry中搜索并安装ARCore XR Plugin。同样需要注意版本它必须与已安装的AR Foundation版本兼容。通常同一个大版本号下的两者是兼容的例如AR Foundation 4.1.x 对应 ARCore XR Plugin 4.1.x。安装时它会自动依赖Google ARCore SDK for Android等子包。对于 iOS 开发在Package Manager的Unity Registry中搜索并安装ARKit XR Plugin。版本选择逻辑与ARCore一致。重要提示如果你计划开发同时支持Android和iOS的应用两个平台插件都需要安装。Unity在构建时会根据目标平台自动选择激活对应的插件。3.4 处理依赖与版本冲突安装后如果包管理器窗口顶部出现黄色警告条提示“Validation failed”或存在版本冲突需要手动处理。解决冲突点击警告条查看详情。通常是某个间接依赖的包版本不一致。你可以尝试点击“Fix”按钮让Unity自动解决或者手动去Manifest.json文件位于项目根目录的Packages文件夹内中调整版本号。手动调整需要谨慎建议先备份。验证安装安装完成后回到Package Manager将视图切换为In Project。你应该能看到AR Foundation、ARCore XR Plugin和/或ARKit XR Plugin、XR Plugin Management等包已列出且状态正常没有警告图标。4. 项目设置与XR插件管理包安装好了但Unity还不知道你要用哪个AR插件以及如何为不同平台配置。这就需要配置XR Plugin Management。4.1 启用插件与平台设置进入Edit - Project Settings在设置窗口中找到XR Plug-in Management并点击。你会看到顶部有多个平台标签页如Android、iOS、Windows等。确保你正在为正确的平台进行配置。以Android平台为例勾选ARCore前面的复选框。这表示在构建Android应用时启用ARCore插件。勾选Initialize on startup推荐。这会让AR子系统在应用启动时自动初始化简化代码。在ARCore插件下方可能有一个Requirements选项将其设置为Optional。这意味着即使设备不支持ARCore你的应用也能安装和运行尽管AR功能不可用这有助于提高应用商店的兼容性。切换到iOS平台标签页如果你开发iOS勾选ARKit复选框。同样勾选Initialize on startup并将Requirements设为Optional对于iOSARKit的Optional设置影响的是iOS版本兼容性而非硬件。4.2 Player Settings 关键配置回到Project Settings - Player。这里有许多针对特定平台的构建设置。Android 平台配置点击Android平台图标。在Other Settings部分Graphics APIs如之前所述建议移除Vulkan只保留OpenGLES3。这能避免部分设备的兼容性问题。IdentificationMinimum API Level设置为Android 7.0 (API Level 24)或更高。这是ARCore支持的最低要求。为了更好的兼容性可以设为Android 8.0 (API Level 26)。Target API Level设置为你测试设备对应的API级别或最新的稳定版。ConfigurationScripting Backend选择IL2CPP。这是发布应用的标准支持64位架构并且代码执行效率更高。Target Architectures勾选ARM64。这是现代Android设备的必需架构。可以同时勾选ARMv7以兼容一些老旧设备但会增加包体大小。Permission在Android Manifest相关设置中确保Camera权限是声明的。ARFoundation通常会自动添加但最好检查一下。iOS 平台配置点击iOS平台图标。在Other Settings部分Camera Usage Description必须填写。这是一个字符串描述你的应用为何需要使用摄像头例如“用于增强现实体验”。这是App Store审核的强制要求如果不填应用将无法访问摄像头AR功能失效。Target minimum iOS Version设置为11.0或更高。这是ARKit支持的最低版本。Architecture选择ARM64。Scripting Backend同样选择IL2CPP。5. 构建第一个AR场景与基础功能验证配置完成后我们来创建一个最简单的AR场景验证一切是否工作正常。5.1 创建基础AR场景组件在Hierarchy窗口右键选择XR - AR Session Origin。Unity会自动创建一个包含ARSessionOrigin和ARSession组件的GameObject。ARSession管理AR会话的生命周期启动、暂停、停止。一个场景中通常只需要一个。ARSessionOrigin代表AR世界的原点。所有被跟踪的物体如点云、平面、锚点的位置都是相对于它的。它下面通常挂载各种AR Manager组件。选中ARSessionOrigin对象在Inspector窗口中点击Add Component添加以下管理器AR Plane Manager用于检测和可视化现实世界中的水平平面如地板、桌面。AR Point Cloud Manager用于可视化特征点云帮助你理解设备正在识别哪些环境特征。AR Raycast Manager允许你从屏幕点发射射线与AR跟踪的几何体如平面进行交互这是放置物体的关键。为了放置物体我们还需要一个视觉反馈。创建一个简单的3D CubeGameObject - 3D Object - Cube将其Scale设置为(0.1, 0.1, 0.1)然后将其拖成Prefab拖入Project窗口的Assets文件夹。将这个Prefab赋值给AR Plane Manager组件中的Plane Prefab字段。这样当检测到平面时会用这个缩小的Cube来可视化平面边界。5.2 编写简单的交互脚本创建一个C#脚本命名为PlaceOnPlane.cs将其挂载到ARSessionOrigin上。using UnityEngine; using UnityEngine.XR.ARFoundation; using UnityEngine.XR.ARSubsystems; public class PlaceOnPlane : MonoBehaviour { public GameObject placementPrefab; // 要放置的物体Prefab private ARRaycastManager raycastManager; private GameObject spawnedObject; // 已生成的物体实例 void Start() { // 获取组件 raycastManager GetComponentARRaycastManager(); if (raycastManager null) { Debug.LogError(ARRaycastManager not found on this GameObject.); } } void Update() { // 如果没有触摸输入直接返回 if (Input.touchCount 0) return; Touch touch Input.GetTouch(0); // 只响应手指刚接触屏幕的瞬间 if (touch.phase ! TouchPhase.Began) return; // 执行射线检测 ListARRaycastHit hits new ListARRaycastHit(); if (raycastManager.Raycast(touch.position, hits, TrackableType.PlaneWithinPolygon)) { Pose hitPose hits[0].pose; // 获取第一个命中点的位置和旋转 // 如果之前没有放置物体则实例化一个 if (spawnedObject null) { spawnedObject Instantiate(placementPrefab, hitPose.position, hitPose.rotation); } else { // 如果已有物体则移动它到新的位置 spawnedObject.transform.position hitPose.position; spawnedObject.transform.rotation hitPose.rotation; } } } }在Inspector中将之前创建的Cube Prefab或其他你喜欢的模型Prefab拖拽到PlaceOnPlane脚本的placementPrefab字段。5.3 构建与真机测试Android 构建步骤File - Build Settings。确保Android是选中的目标平台点击Switch Platform如果需要切换。将当前场景添加到Scenes In Build列表中。点击Player Settings...快速跳转检查我们之前的所有设置。连接你的Android手机开启开发者选项和USB调试。点击Build And Run。选择一个路径保存APK文件Unity将开始构建并自动安装到你的手机。iOS 构建步骤 (需在macOS上进行)在Build Settings中切换平台到iOS。点击Build生成一个Xcode工程。用Xcode打开生成的工程。在Signing Capabilities中配置你的Apple开发者团队和Bundle Identifier。连接iOS设备在Xcode中选择该设备作为运行目标然后点击运行按钮。真机测试验证在手机上运行应用。首次运行会请求摄像头权限务必允许。缓慢移动手机让摄像头扫描周围环境地面、桌面。你应该能看到AR Plane Manager生成的可视化平面我们设置的小方块边界。点击屏幕上的平面区域一个物体Cube应该被放置在你点击的位置。如果以上步骤都成功恭喜你一个最基本的ARFoundation演示项目已经配置并运行成功6. 常见问题排查与深度优化指南即使按照步骤操作你也可能会遇到一些问题。这里我整理了一些最常见的坑和解决方案。6.1 安装与编译问题问题现象可能原因解决方案Package Manager中找不到AR Foundation包视图未切换到Unity Registry或未勾选Show preview packages检查窗口左上角Packages下拉菜单和右上角Advanced选项。安装包时出现版本冲突错误包之间的依赖关系不兼容1. 尝试使用Package Manager的“Fix”功能。2. 手动编辑Packages/manifest.json将所有AR相关包AR Foundation, ARCore, ARKit, XR Plugin Management等的版本号调整到同一个大版本如4.1.x。然后回到Unity它会自动解析。构建时报错“找不到命名空间UnityEngine.XR.ARFoundation”脚本编译引用失败可能是包未正确加载或脚本编译顺序问题1. 检查Package Manager中相关包是否确已安装且无错误图标。2. 关闭Unity编辑器删除项目根目录下的Library和obj文件夹然后重新打开Unity。这会强制重新导入所有资源和编译脚本。Android构建失败提示Gradle、SDK或JDK错误Unity安装时未包含Android模块或路径包含中文/特殊字符1. 通过Unity Hub为当前编辑器版本添加Android Build Support模块。2. 检查Edit - Preferences - External Tools中的Android SDK、JDK、NDK路径是否有效。无效则点击Download或Browse指定正确路径。6.2 运行时与真机问题问题现象可能原因解决方案应用启动后黑屏无图像摄像头权限未获取或AR会话启动失败1. 确认真机已授予应用摄像头权限。2. 检查XR Plug-in Management中是否勾选了对应平台插件并设置了Initialize on startup。3. 检查Player Settings中Minimum API Level是否满足ARCore/ARKit要求。能看到摄像头画面但无法检测平面环境光线不足、表面纹理单一、或设备不支持1. 改善环境光照让摄像头能看清丰富纹理。2. 尝试扫描有图案的地毯、木纹桌面等。3. 确认设备在 ARCore支持设备列表 或支持ARKitiPhone 6s及以上iOS 11。物体放置位置漂移或不稳定跟踪丢失或锚点不稳定1. 确保环境光线充足且稳定。2. 放置物体后避免剧烈移动手机给AR系统一些时间进行重定位。3. 考虑使用ARAnchorManager来创建持久锚点而不是直接放置物体。iOS构建后Xcode报签名或权限错误Bundle Identifier重复或权限描述未设置1. 使用唯一的Bundle Identifier。2. 确认Player Settings - iOS - Camera Usage Description已填写。3. 在Xcode中检查Signing Capabilities配置是否正确。6.3 性能优化与进阶配置当基础功能跑通后为了获得更好的体验和准备上线这些优化点值得关注平面检测优化AR Plane Manager组件下有Detection Mode选项。默认是Horizontal水平面。如果你的应用只需要垂直面如墙壁可以改为Vertical以节省计算资源。Plane Prefab尽量使用简单的几何体如我们用的缩放Cube避免使用复杂网格。管理跟踪状态监听ARSession的stateChanged事件。当状态变为None或Not Ready时可以提示用户移动设备以重新初始化跟踪。当状态为Unsupported时提示用户设备不支持AR并可能切换到非AR模式。处理设备朝向在AR Session Origin上Camera子物体的Tracked Pose Driver组件负责将设备摄像头姿态同步到场景相机。确保其Tracking Type设置为Rotation and Position。光照估计添加AR Environment Probe和AR Light Estimation组件可以让虚拟物体的光照与真实环境更融合。AR Light Estimation可以调整场景中环境光的强度和颜色。打包尺寸优化ARCore/ARKit插件会显著增加APK/IPA文件大小。使用Unity的AssetBundles或Addressables系统来管理模型资源可以实现资源远程加载和按需加载减少初始包体。构建时启用Player Settings - Publishing Settings中的代码剥离Code Stripping和压缩选项。整个配置过程最磨人的往往不是步骤本身而是版本兼容性和环境变量这类“隐形”问题。我的习惯是每开始一个全新的AR项目都先用这个最简流程跑通建立一个干净的“基线”。然后再根据项目需求逐步添加图像识别、人脸追踪、 occlusion遮挡等高级功能包。这样能确保问题被隔离在最小范围排查起来也更有方向。