1. 项目概述：为什么是Unity 2021.3 + AR Foundation 4.1.5？

如果你正在用Unity做AR开发，尤其是面向安卓设备，那么ARCore图像识别绝对是一个绕不开的核心功能。它能让你把手机摄像头对准一张特定的图片，比如一张海报、一个产品包装盒，然后立刻在屏幕上“召唤”出一个3D模型、一段视频或者一个交互界面，这种虚实结合的体验非常酷。但说实话，从零开始配置一个能稳定运行的ARCore图像识别环境，尤其是确保Unity、AR Foundation、ARCore SDK以及安卓构建环境之间不“打架”，这个过程对新手甚至是有一定经验的开发者来说，都挺劝退的。

我之所以选择“Unity 2021.3 LTS”和“AR Foundation 4.1.5”这个组合，是经过实际项目验证的。Unity 2021.3是一个长期支持版本，意味着它的稳定性和向后兼容性有保障，不会像一些Tech Stream版本那样频繁引入未知的Breaking Changes。而AR Foundation 4.1.5是这个大版本下的一个稳定补丁版，它修复了早期4.1.x版本的一些关键Bug，同时又完整支持了ARCore图像识别所需的所有API。这个组合就像一个经过磨合的“黄金搭档”，能最大程度减少你在环境配置阶段遇到的诡异问题，让你把精力集中在创意和逻辑实现上。

这个教程的目标很明确：我会手把手带你走通从零配置到最终在真机上跑通图像识别的全流程。过程中你会遇到哪些坑，哪些设置必须勾选，哪些参数需要调整，我都会结合自己的踩坑经验给你讲清楚。最终，你将拥有一个干净、可复用的ARCore图像识别项目模板，以后任何新项目都可以直接套用。

2. 环境准备与核心工具链解析

在动手写一行代码之前，把环境搭对是成功的一半。这里的环境是一个“工具链”，环环相扣，任何一个环节版本不匹配都可能导致构建失败或运行时崩溃。

2.1 Unity编辑器的安装与关键设置

首先，你需要通过Unity Hub安装Unity 2021.3.x LTS版本。我建议安装2021.3.34f1或之后的版本，这些版本修复了更多的问题。在安装时，务必勾选以下模块：

• Android Build Support：这是必须的，包含SDK、NDK和OpenJDK。如果你之前没有安装过Android开发环境，让Unity帮你下载是最省事的方法。
• iOS Build Support：如果你后续有开发iOS AR的需求（使用ARKit），可以一并勾选。本教程主要针对ARCore。

安装完成后，打开Unity Hub，创建一个新的3D项目（Core模板即可）。创建后，第一件事是去Edit -> Project Settings -> Player进行关键设置。

在Player Settings面板中，找到Other Settings区域：

1. Scripting Backend：必须选择IL2CPP。ARCore依赖的原生库（.so文件）需要IL2CPP后端来正确交互。Mono后端在构建时可能会报错或导致运行时功能异常。
2. Target Architectures：勾选ARM64。这是现代安卓设备的标配，只勾选ARMv7可能会在某些新设备上无法运行或性能不佳。确保ARM64被选中。
3. Minimum API Level：设置为Android 7.0 ‘Nougat’ (API Level 24)或更高。ARCore本身对系统版本有要求，设得太低会导致应用无法安装或初始化失败。通常建议设为API Level 24或26。
4. Target API Level：可以设置为自动，或者指定一个较高的版本（如API Level 33）。这关系到你能使用哪些最新的系统特性。

注意：很多教程会忽略IL2CPP和ARM64的设置，导致开发者卡在构建或真机调试阶段，错误信息又非常模糊。这一步是基础中的基础，务必检查。

2.2 包管理器的正确操作：导入AR Foundation与ARCore XR Plugin

Unity 2021.3默认使用Package Manager来管理功能包。我们需要的核心包有两个：

1. AR Foundation (4.1.5)：这是Unity官方提供的跨平台AR开发框架。它定义了一套通用的API，无论底层是ARCore还是ARKit，你上层的C#代码写法都基本一致。
2. ARCore XR Plugin (4.1.5)：这是AR Foundation在安卓平台上的具体实现插件。它包含了与谷歌ARCore SDK通信的所有原生代码。

打开Window -> Package Manager。点击左上角“+”号，选择“Add package by name...”。 首先，输入com.unity.xr.arfoundation@4.1.5并点击Add。等待其下载并导入。 接着，再次点击“Add package by name...”，输入com.unity.xr.arcore@4.1.5并添加。

为什么必须指定版本号？因为Package Manager默认会安装最新版本，而最新版（如5.x或6.x）可能与Unity 2021.3不完全兼容，或者API发生了较大变动。锁定4.1.5这个经过验证的版本，能确保本教程的所有步骤和代码都有效。

导入完成后，你可以在Package Manager的“My Assets”列表中看到它们。确保它们的版本号都是4.1.5。

2.3 安卓开发环境（JDK, SDK, NDK）的配置要点

虽然Unity安装时可能已经下载了这些，但手动检查一下路径是否正确很有必要。进入Edit -> Preferences -> External Tools。

• Android JDK：Unity通常会使用其内置的OpenJDK，路径类似[Unity安装路径]/Editor/Data/PlaybackEngines/AndroidPlayer/OpenJDK。使用这个通常没问题。
• Android SDK：Unity也会自动安装在一个路径下。确保这里指向一个有效的路径。如果空白，你可以点击“Download”让Unity重新下载，或者指向你自己Android Studio中的SDK路径。
• Android NDK：这是最关键的，也是容易出问题的地方。ARCore的本地代码编译需要NDK。Unity 2021.3通常要求NDK版本在r19 - r23之间。我强烈建议使用Unity Hub为这个版本Unity安装的NDK。你可以在Unity Hub中，找到已安装的2021.3版本，点击右侧的三个点，选择“Add modules”，确保“Android NDK”被勾选并安装。安装后，在External Tools中，它应该被自动配置好。

实操心得：大约80%的“构建失败”问题都出在NDK版本不兼容上。如果你遇到编译原生库的错误，首先检查NDK路径和版本。不要使用太新（如r25）或太旧（r16）的NDK。使用Unity Hub管理的NDK是最稳妥的方案。

3. 项目核心配置与场景搭建

环境就绪后，我们开始在Unity项目内进行配置，并搭建一个最简单的AR图像识别场景。

3.1 配置XR Plug-in Management与ARCore项目设置

AR Foundation需要知道在哪个平台上启用哪个XR插件。我们需要配置XR Plug-in Management。

1. 在Project Settings窗口中，找到XR Plug-in Management。
2. 勾选上方的Android标签页。
3. 在列表中，找到ARCore并勾选它。这会自动启用ARCore插件，并确保构建时包含必要的库和清单(Manifest)配置。

接下来，我们需要为ARCore启用特定的功能。在Project Settings中，找到XR Plug-in Management -> ARCore。 在这里，确保Require ARCore是勾选的（这表示你的应用必须运行在支持ARCore的设备上）。 最重要的是，找到Image Tracking选项，并勾选它。这个操作会在最终生成的Android应用清单(AndroidManifest.xml)中，自动添加<uses-feature android:name="android.hardware.camera.ar" android:required="true" />等必要权限和特性声明，告诉系统和应用商店这个应用需要ARCore的图像追踪功能。

3.2 构建最小化AR场景：ARSession与图像识别管理器

现在我们来搭建场景。在Hierarchy窗口右键，选择XR -> AR Session。这会创建一个ARSession对象，它是整个AR体验的管理者，负责控制AR子系统（ARCore）的生命周期、会话状态（开始、暂停、重置）等。

接着，我们需要一个对象来管理图像识别数据库。再次右键，选择XR -> AR Tracked Image Manager。

• AR Tracked Image Manager组件负责加载一个图像数据库，并监听摄像头画面，当识别到数据库中的图像时，它会创建或更新ARTrackedImage对象。
• 在它的Inspector面板中，你会看到一个“Serialized Library”字段。我们需要创建一个XR Reference Image Library（参考图像库）资源来赋值给它。

在Project窗口右键，选择Create -> XR -> Reference Image Library，给它起个名字，比如“MyImageLibrary”。然后选中这个Library资源，在Inspector中点击“Add Image”按钮来添加你想要识别的图片。

• Texture：拖入你的识别图。建议使用.png或.jpg格式。
• Name：给这张图起个唯一的名字，代码里会用到。
• Size：这是关键！你需要指定这张图片在现实世界中的物理尺寸（单位：米）。例如，如果你的识别图是一张标准的A4纸（210mm x 297mm）上的图案，那么宽度就设0.21，高度设0.297。这个尺寸决定了后续生成的虚拟物体相对于识别图的比例。估测得越准，虚拟物体“站”得就越稳。
• Specify Size：一定要勾选，然后手动输入宽高。

创建好Library后，将它拖拽赋值给AR Tracked Image Manager组件的“Serialized Library”字段。

最后，为了在识别到图像时能“放点东西上去”，我们创建一个简单的3D Cube作为预制体。在Hierarchy中创建一个Cube，然后将其拖入Project窗口做成预制体，最后把这个预制体拖到AR Tracked Image Manager组件的“Tracked Image Prefab”字段上。这样，当图像被识别时，管理器会自动实例化这个Cube预制体，并将其位置和旋转与识别图对齐。

4. 图像识别逻辑的深度实现与优化

基础场景搭好了，但默认的Prefab实例化可能无法满足复杂需求。我们需要编写脚本来更精细地控制识别后的行为。

4.1 编写Tracked Image事件处理器脚本

创建一个C#脚本，命名为ImageTrackingHandler，将其挂载到场景中任何一个活跃的GameObject上（比如AR Session Origin）。

using System.Collections.Generic; using UnityEngine; using UnityEngine.XR.ARFoundation; using UnityEngine.XR.ARSubsystems; public class ImageTrackingHandler : MonoBehaviour { // 持有管理器引用，可以通过拖拽赋值，也可以在Start中查找 private ARTrackedImageManager _trackedImageManager; // 一个字典，用于根据识别出的图像名称，关联不同的预制体（例如：识别图A对应模型A，图B对应模型B） public Dictionary<string, GameObject> spawnedPrefabs = new Dictionary<string, GameObject>(); void Start() { // 获取场景中的ARTrackedImageManager组件 _trackedImageManager = FindObjectOfType<ARTrackedImageManager>(); if (_trackedImageManager == null) { Debug.LogError("ARTrackedImageManager not found in scene."); return; } } void OnEnable() { // 订阅图像追踪事件 _trackedImageManager.trackedImagesChanged += OnTrackedImagesChanged; } void OnDisable() { // 取消订阅，防止内存泄漏 _trackedImageManager.trackedImagesChanged -= OnTrackedImagesChanged; } private void OnTrackedImagesChanged(ARTrackedImagesChangedEventArgs eventArgs) { // 处理新识别到的图像 foreach (var trackedImage in eventArgs.added) { UpdateTrackedImage(trackedImage); } // 处理已更新（位置/状态变化）的图像 foreach (var trackedImage in eventArgs.updated) { UpdateTrackedImage(trackedImage); } // 处理已丢失（摄像头中消失）的图像 foreach (var trackedImage in eventArgs.removed) { // 当图像丢失时，你可以选择销毁对应的物体，或者将其隐藏 if (spawnedPrefabs.TryGetValue(trackedImage.referenceImage.name, out GameObject prefab)) { Destroy(prefab); spawnedPrefabs.Remove(trackedImage.referenceImage.name); } } } private void UpdateTrackedImage(ARTrackedImage trackedImage) { string imageName = trackedImage.referenceImage.name; // 获取图像在现实世界中的物理尺寸（我们在Reference Image Library中设置的） Vector2 imageSize = trackedImage.size; // 根据追踪状态决定如何处理 switch (trackedImage.trackingState) { case TrackingState.Tracking: // 图像被稳定追踪 if (!spawnedPrefabs.ContainsKey(imageName)) { // 第一次识别到这张图，实例化对应的物体 // 这里简化处理，实例化一个默认Cube。实际项目中，你可以根据imageName从资源库加载不同的预制体。 GameObject spawnedObject = Instantiate(yourPrefabForThisImage, trackedImage.transform.position, trackedImage.transform.rotation); spawnedPrefabs.Add(imageName, spawnedObject); // 你可以根据imageSize来调整生成物体的大小比例，使其与真实图片尺寸匹配 // spawnedObject.transform.localScale = new Vector3(imageSize.x, 1.0f, imageSize.y); } else { // 图像已被追踪，且物体已存在，更新物体的位置和旋转 GameObject existingObject = spawnedPrefabs[imageName]; existingObject.transform.position = trackedImage.transform.position; existingObject.transform.rotation = trackedImage.transform.rotation; existingObject.SetActive(true); // 确保物体是激活的 } break; case TrackingState.Limited: // 图像追踪受限（例如，图像在边缘、模糊、部分遮挡） // 通常选择隐藏物体，或者显示一个低精度的替代物 if (spawnedPrefabs.TryGetValue(imageName, out GameObject limitedObject)) { limitedObject.SetActive(false); } break; case TrackingState.None: // 图像完全丢失，处理方式同eventArgs.removed if (spawnedPrefabs.TryGetValue(imageName, out GameObject lostObject)) { Destroy(lostObject); spawnedPrefabs.Remove(imageName); } break; } } }

这个脚本是图像识别交互的核心。它通过订阅trackedImagesChanged事件，精准地响应图像的“出现”、“更新”和“消失”。根据trackingState来管理虚拟物体的显示、隐藏或销毁，能极大地提升用户体验，避免物体在图像不稳定时乱跳。

4.2 图像数据库的优化与识别图设计准则

不是任何图片都适合做识别图。ARCore的图像识别算法（也称为“特征点检测”）对图像有一定要求。

• 高对比度与丰富细节：识别图需要有足够多的、独特的视觉特征（如角点、边缘）。一张纯色或渐变平滑的图片很难被稳定识别。
• 避免对称与重复图案：像棋盘格、重复的条纹，这些图案特征点很多但缺乏独特性，容易导致识别位置漂移。
• 非动态内容：识别图内容应该是静态的。避免使用视频帧或动态变化的图像。
• 合适的尺寸与分辨率：在XR Reference Image Library中导入的图片纹理，建议分辨率在300x300 到 2000x2000像素之间。太小特征不足，太大会增加库的体积和加载时间。
• 物理尺寸准确：再次强调，Size字段必须尽可能准确地反映图片在现实世界中的打印或显示尺寸。这是虚拟物体能“脚踏实地”的关键。

你可以在Unity Editor中，选中AR Tracked Image Manager，在Inspector底部点击“Runtime Reference Image Library”下的“Open Library Editor”按钮，预览库中图像的特征点分布。特征点密集且分布均匀的图像，识别效果会更好。

5. 构建、部署与真机调试全流程

配置和代码都写好了，接下来就是打包到手机上测试。

5.1 构建Android APK前的最终检查清单

在菜单栏选择File -> Build Settings，确保Platform是Android，然后点击“Switch Platform”。等待转换完成。 点击“Player Settings...”按钮，再次快速核对：

1. Other Settings下，Scripting Backend= IL2CPP，Target Architectures= ARM64。
2. XR Plug-in Management下，Android平台的ARCore已勾选，且Image Tracking已启用。
3. Package Name(Bundle Identifier)：格式必须是com.YourCompanyName.YourProductName，且全网唯一。
4. Minimum API Level至少为24。

回到Build Settings窗口，选择好输出路径，点击Build。如果一切配置正确，Unity会开始编译。第一次构建可能会花费较长时间，因为它需要编译IL2CPP代码和打包资源。

5.2 在ARCore支持的设备上安装与测试

将生成的APK文件传输到你的安卓手机上并安装。确保你的手机在 谷歌的ARCore支持设备列表 中，并且已经通过Google Play商店安装了最新版的Google Play Services for AR（即ARCore运行时）。如果没安装，首次运行你的应用时，系统可能会提示你跳转到Play商店安装。

打开应用，授予相机权限。将摄像头对准你制作了识别图的实物（比如打印出来的图片）。你应该能看到，当图像被识别后，你设置的3D Cube（或你的自定义预制体）稳稳地出现在图像上方。移动手机，物体会随着图像的移动和旋转而同步变化，仿佛它真的“贴”在图片上一样。

5.3 使用Android Logcat进行运行时问题排查

如果应用安装后黑屏、闪退，或者无法识别图像，光靠肉眼很难定位问题。这时需要使用日志工具。Unity连接安卓设备调试，最强大的是Android Logcat窗口。

在Unity Editor中，打开Window -> Analysis -> Android Logcat。

1. 用USB数据线连接手机，并开启手机的USB调试模式（在“开发者选项”中）。
2. 在Android Logcat窗口的顶部，选择你的设备。
3. 点击“Play”按钮开始捕获日志。
4. 在手机上运行你的AR应用，观察Logcat中输出的信息。

重点关注带有“ARCore”、“ARFoundation”、“Error”、“Exception”等关键词的日志。常见的错误包括：

• ARCore未安装或版本过低：日志会明确提示。
• 相机权限被拒绝：应用启动即崩溃或黑屏。
• 图像数据库加载失败：检查图片格式和大小，以及Library是否正确赋值。
• 原生库加载失败：通常与NDK版本或构建设置（IL2CPP, ARM64）有关。

通过Logcat，你可以精准定位到崩溃的代码行或失败的系统调用，这是解决复杂运行时问题的必备技能。

6. 进阶技巧与性能优化指南

一个能跑起来的基础Demo只是开始。要让体验更流畅、更稳定，还需要一些进阶技巧。

6.1 多图像识别与动态图像库加载

AR Tracked Image Manager支持同时追踪多张图像。你只需在XR Reference Image Library中添加多张图片即可。在事件处理脚本中，通过trackedImage.referenceImage.name来区分不同的图像，并实例化不同的虚拟内容。

对于内容丰富的应用，图像库可能很大。你可以在运行时动态加载不同的图像库。ARTrackedImageManager有一个referenceLibrary属性，你可以在代码中创建RuntimeReferenceImageLibrary并通过Add方法添加图片，或者直接替换整个库。这适用于需要从网络下载识别图的应用场景。

6.2 识别稳定性的提升策略

有时图像识别会抖动或偶尔丢失。除了优化识别图本身，还可以：

• 使用跟踪状态过滤：正如我们在脚本中做的，只在TrackingState.Tracking时才显示完整精度的模型，在Limited时显示简化版或隐藏，能有效提升视觉稳定性。
• 位置平滑插值：对于ARTrackedImage.transform提供的位置和旋转，不要直接赋值给物体。可以使用Vector3.Lerp和Quaternion.Slerp进行平滑插值，过滤掉高频抖动。但要注意插值系数不能太大，否则会导致虚拟物体响应迟滞。
• 环境光线适应：ARCore的识别在光线充足、均匀的环境下效果最好。在应用启动时，可以提示用户确保环境光合适。

6.3 性能考量与内存管理

AR应用是性能敏感的，同时运行着相机预览、计算机视觉算法和3D渲染。

• 预制体优化：识别后实例化的3D模型面数不宜过高，贴图尺寸要合理。对于复杂的模型，考虑使用LOD（多细节层次）。
• 及时销毁：在OnTrackedImagesChanged的removed事件中，务必销毁或回收不再需要的GameObject，防止内存泄漏。我们的示例脚本中已经做了这件事。
• 帧率管理：可以在Quality Settings中适当降低默认的图形质量，或者使用Application.targetFrameRate将帧率锁定在30或60，以平衡发热和体验。
• 图像库大小：一个XR Reference Image Library中图片越多、分辨率越高，加载到内存和初始化识别引擎的时间就越长。按需加载，并考虑对图片进行压缩（在保证特征点不丢失的前提下）。

7. 常见问题排查与解决方案实录

这里汇总了我自己和社区里经常遇到的一些典型问题及其解决方法。

最后，我想分享一个在真机测试时的小技巧：由于ARCore需要从Google服务器下载设备特定的校准数据（第一次在某个设备上运行AR应用时），请确保你的测试手机连接了稳定的互联网。否则，AR会话可能会初始化失败或延迟非常久。这个细节在开发文档里不太起眼，但却能省去你很多“为什么我的手机不行”的困惑时间。