1. 项目概述

如果你正在用Unity做项目，想给产品加点“魔法”，让虚拟的3D模型能稳稳地站在现实世界的桌面上，或者让一张普通的图片在手机镜头里“活”过来，那么EasyAR绝对是你绕不开的一个名字。我最早接触AR开发，就是从EasyAR开始的，它算是国内AR引擎里对Unity开发者最友好、上手门槛最低的一个。很多朋友一听到AR，就觉得是那种需要高深算法和昂贵硬件的黑科技，其实不然。EasyAR把很多复杂的底层技术，比如图像识别、运动跟踪、环境感知，都打包成了Unity里几个简单的组件和脚本，你甚至不需要完全理解SLAM（即时定位与地图构建）的原理，就能做出一个像模像样的AR应用。这篇教程，我就以一个老Unity开发者的视角，带你从零开始，手把手把EasyAR集成到你的项目里，并实现一个最经典的“图片识别展示3D模型”的功能。整个过程，我会把那些官方文档里一笔带过、但实际开发中一定会踩的坑，以及我积累下来的调试技巧，毫无保留地分享给你。

2. 核心概念与准备工作

2.1 EasyAR是什么？它能做什么？

简单来说，EasyAR是一个增强现实（AR）引擎的SDK（软件开发工具包）。你可以把它理解为一个功能强大的“插件包”，专门为Unity、Android、iOS等平台提供AR能力。它的核心价值在于，让你不必从零开始研究计算机视觉算法，而是通过调用它封装好的API，快速实现AR效果。

目前，EasyAR Sense主要有两个版本：Basic和Pro。对于绝大多数入门和商业应用，Basic版完全够用。它支持平面图像识别（就是识别一张特定的图片）、多目标同时跟踪（同时识别好几张图）、云识别（把识别图库放在服务器上）、3D物体跟踪（识别一个真实的物体，比如一个玩具）、SLAM（让虚拟物体能稳定地“粘”在现实世界的平面上，比如地板上）以及录屏等核心功能。最关键的是，EasyAR SDK Basic可以免费商用，没有水印，也没有调用次数限制，这对于个人开发者和初创团队来说非常友好。

2.2 环境与工具准备

在开始写代码之前，我们需要把“厨房”收拾好，把“食材”备齐。

1. Unity版本选择：我强烈推荐使用Unity 2021 LTS（长期支持版）或2022 LTS。LTS版本经过长期测试，稳定性最高，与各种插件的兼容性也最好。EasyAR官方对较新的Unity版本支持通常都很快，但为了避免不必要的兼容性问题，选择LTS版本是最稳妥的。我个人目前的主力开发环境是Unity 2021.3.32f1。

2. 下载EasyAR SDK：前往EasyAR官网的 下载中心 。你需要注册一个账号并登录。在下载页面，找到“EasyAR Sense”的Unity版本SDK进行下载。你会得到一个后缀为.unitypackage的文件，这是我们后续要导入到Unity工程中的资源包。

注意：官网可能会同时提供多个版本（如2.x, 4.x）。对于新手，我建议从最新的稳定版（如Sense 4.x）开始，因为它包含了更完善的文档和样例。本教程将以Sense 4.x版本为例进行讲解，其核心逻辑与旧版相通。

3. 申请License Key（密钥）：这是使用EasyAR SDK的“通行证”，没有它，SDK无法初始化。登录EasyAR官网，进入“开发中心” -> “License管理”。

• 创建License：点击“添加License Key”。
• 选择类型：对于学习和测试，直接选择“EasyAR SDK Basic”。
• 填写应用信息：
  • 应用名称：可以随意填写，如“MyFirstARApp”。
  • Bundle ID (iOS) / Package Name (Android)：这是最关键的一步！它必须与你最终打包APP时设置的包名完全一致，包括大小写。我们可以在Unity里提前设置好。
    • 打开Unity，菜单栏File -> Build Settings，切换到Android或iOS平台。
    • 点击Player Settings，在Other Settings区域找到Identification。
    • 对于Android，修改Package Name，例如com.YourCompany.MyFirstARApp。
    • 对于iOS，修改Bundle Identifier，格式类似。
  • 将Unity中设置好的包名，准确地填写到EasyAR官网创建License的对应输入框中。
• 获取Key：创建成功后，在License列表里点击你创建的Key，就能看到一串长长的字符串，这就是你的App Key和Secret Key（有些版本合称为License Key）。请妥善保存，我们马上要用到。

4. 新建Unity项目：打开Unity Hub，创建一个新的3D项目（Core或URP模板均可）。建议项目名称和路径都不要包含中文和空格，这是一个避免各种奇怪问题的好习惯。

3. SDK集成与基础配置

3.1 导入EasyAR UnityPackage

这一步很简单，但有几个细节需要注意。

1. 在Unity中，确保你的新项目已经打开。
2. 将下载好的EasyAR Sense X.X.X.X.unitypackage文件直接拖入Unity的Project窗口，或者通过菜单Assets -> Import Package -> Custom Package...进行导入。
3. 这时会弹出一个导入对话框，通常默认全选所有文件即可，点击Import。

实操心得：导入完成后，建议立即在Project窗口搜索 “EasyAR”，观察一下目录结构。你会看到EasyAR、Samples、Documentation等文件夹。先别急着运行样例，我们从头开始构建，理解会更深刻。

3.2 配置EasyAR设置与密钥

导入SDK后，我们需要进行一些基础配置，让SDK知道你是谁（用哪个Key），以及如何工作。

1. 创建EasyAR配置资源：在Project窗口右键，选择Create -> EasyAR -> Sense -> AR Session。这会在当前目录下创建一个名为EasyAR_Session的游戏对象预制体（Prefab）。同时，Unity会自动在Assets根目录下生成一个Resources文件夹，里面包含一个easyar_settings的配置文件。

2. 填写License Key：

   • 找到并选中刚才创建的EasyAR_Session预制体，或者直接在Hierarchy窗口中右键 ->EasyAR -> Sense -> AR Session创建一个实例。
   • 在Inspector面板中，你会看到EasyAR Sense AR Session组件。
   • 关键字段是License Key。将你在官网获取的那一串密钥完整地粘贴进去。
   • 下方通常还有一个Package Name / Bundle Identifier的字段，检查一下是否自动填充了你当前项目的包名，确保一致。

3. 理解核心组件：

   • AR Session：这是整个AR功能的“大脑”和“调度中心”。它负责管理AR引擎的生命周期、协调摄像头、识别跟踪器等各个模块。一个场景中通常只需要一个AR Session。
   • Camera Device：负责调用和控制设备的物理摄像头。
   • Frame Source：帧源，决定AR画面的来源，通常是Camera Device Frame Source，表示从手机摄像头获取实时画面。
   • Frame Player：负责将获取到的摄像头画面渲染到屏幕上。

   当你通过菜单创建AR Session时，这些核心组件通常会作为子对象自动生成并连接好，这为我们省去了大量手动组装的时间。

3.3 构建第一个AR场景：图像识别

现在，我们来搭建一个最经典的AR场景：用手机摄像头识别一张特定的图片，然后在其上方显示一个3D模型。

1. 布置场景基础：

   • 在Hierarchy中，确保有一个Main Camera（Unity默认会有）和我们刚刚创建的EasyAR_Session。
   • 将Main Camera的Clear Flags设置为Solid Color，并将背景色改为纯黑或透明（Alpha=0）。这是因为AR的实时背景将由EasyAR渲染的摄像头画面提供，Unity相机只负责渲染叠加的虚拟物体。
   • 调整Main Camera的位置和旋转归零。它的作用更像是“观察虚拟世界的窗口”，世界空间的原点将对应AR识别到的目标位置。

2. 准备识别图（Target Image）：

   • EasyAR不能识别任意图片，它需要一张“特征鲜明”的图作为目标。特征鲜明意味着有丰富的角点和纹理，比如一张复杂的海报、一本书的封面。纯色、大面积重复纹理的图片识别效果会很差。
   • 选好图片后（例如一张example.jpg），将其放入Unity项目的Assets目录下。
   • 选中这张图片，在Inspector面板中，进行以下关键设置：
     • Texture Type选择Default。
     • 勾选Read/Write Enabled（非常重要！EasyAR需要读取图片数据来提取特征）。
     • 根据你的目标平台调整Max Size，例如移动端设为1024即可，太大影响加载速度和内存。
   • 点击Apply。

3. 创建图像跟踪器（Image Tracker）：

   • 在Hierarchy中，右键选择EasyAR -> Sense -> Image Tracker。这会创建一个ImageTracker对象。
   • 在Inspector中，ImageTracker组件需要关联一个AR Session。将EasyAR_Session对象拖拽到AR Session字段上。

4. 配置识别图到跟踪器：

   • 我们需要创建一个“图像目标”（Image Target），告诉跟踪器要识别哪张图。
   • 在Hierarchy中，右键选择EasyAR -> Sense -> Image Target。这会创建一个ImageTarget对象。
   • 选中ImageTarget，在Inspector的Image Target Controller组件中：
     • 将Path Type选为Absolute或StreamingAssets。对于本地图片，Absolute最简单，直接填图片在Assets目录下的完整路径，如Assets/example.jpg。更规范的做法是将图片放到StreamingAssets文件夹下，然后使用StreamingAssets路径类型。
     • 在Name字段，给这个目标起个名字，如MyTarget。
     • 将ImageTracker对象拖拽到Tracker字段上，建立关联。
   • 此时，ImageTarget对象下会自动生成一个Target子对象，它代表了识别图在虚拟世界中的“锚点”。

5. 添加虚拟内容：

   • 现在，任何放在ImageTarget对象下的3D模型，都会在识别到图片时出现。
   • 在Hierarchy中，将一个Cube（或任何你喜欢的模型）拖拽成为ImageTarget的子对象。
   • 调整这个Cube的位置、旋转和缩放。例如，将其向上（Y轴）移动1个单位，这样它就会悬浮在识别图上方。

6. 运行测试：

   • 点击Unity编辑器上的播放按钮。
   • 在Game视图中，你应该能看到一个由EasyAR渲染的摄像头选择界面（如果有多摄像头）。选择后，将你准备好的那张实体图片（example.jpg）对准电脑的摄像头。
   • 当识别成功后，你放置的Cube就会出现在图片上方！你可以移动图片，Cube会随之稳定地移动和旋转。

4. 核心功能深度解析与实现

4.1 图像识别的工作原理与优化

你以为把图片拖进去就能识别？背后的门道可不少。EasyAR的图像识别基于特征点检测与匹配。它会提取你提供的识别图中的关键特征点（如角点、边缘）形成一个“特征数据库”。运行时，它从摄像头每一帧画面中提取特征点，并与数据库进行快速匹配，找到最相似的位置和姿态。

优化技巧：

• 图片质量：使用高分辨率、高对比度、纹理丰富的图片。避免反光、过曝或模糊。
• 物理尺寸：在ImageTarget的Image Target Controller组件中，有一个Size字段（单位是米）。这里填写的是识别图在现实世界中的物理宽度。例如，你的图片打印出来是10厘米宽，这里就填0.1。填写准确的尺寸，能让虚拟物体拥有正确的比例感和空间感。
• 多目标管理：ImageTracker组件可以加载多个ImageTarget。你可以通过脚本动态加载和卸载目标，以节省内存。例如，在扫描图书时，翻到哪一页再加载对应页的识别图。

4.2 平面跟踪（Ground Tracking/SLAM）的实现

除了识别特定图片，更常见的需求是让一个虚拟物体“放在”地面上。这需要用到EasyAR的**稀疏空间地图（Sparse Spatial Map）或稠密空间地图（Dense Spatial Map）**功能，也就是SLAM的一种实现。

1. 启用SLAM功能：

   • 选中你的EasyAR_Session对象。
   • 在Inspector中找到AR Session组件，展开其子组件Spatial Map Worker Frame Filter。
   • 确保其Enabled是勾选的。这个组件负责在后台构建环境的空间地图。

2. 创建平面跟踪器：

   • 在Hierarchy中，右键选择EasyAR -> Sense -> Plane Tracker。
   • 同样，将其AR Session字段关联到EasyAR_Session。

3. 添加可放置对象：

   • 现在，我们需要一种方式来“点击地面放置物体”。EasyAR提供了Point Cloud Tracker和Point Cloud Frame Filter来获取摄像头画面中的特征点云，并估算点击位置。
   • 更简单的方法是使用EasyAR -> Sense -> Interaction -> Point Cloud Gesture预制体。将它拖入场景。
   • 这个预制体包含了一个PointCloudGesture脚本，它允许用户通过点击屏幕来与点云交互，并触发放置事件。

4. 编写放置逻辑脚本：

   • 创建一个新的C#脚本，命名为PlaceOnPlane，挂载到你想要放置的物体（例如一个Cube）上。

   using UnityEngine; using easyar; public class PlaceOnPlane : MonoBehaviour { // 关联PointCloudGesture对象 public PointCloudGesture pointCloudGesture; // 关联PlaneTracker对象 public PlaneTracker planeTracker; private void Start() { if (pointCloudGesture != null) { // 订阅手势点击事件 pointCloudGesture.Tap += OnTap; } } private void OnTap(Vector2 touchPosition) { // 将屏幕点击位置转换为射线 Ray ray = Camera.main.ScreenPointToRay(touchPosition); RaycastHit hit; // 进行射线检测，这里假设只检测PlaneTracker生成的平面 // 实际项目中，你可能需要更复杂的逻辑来筛选可放置平面 if (Physics.Raycast(ray, out hit)) { // 将物体移动到点击位置 this.transform.position = hit.point; // 让物体“站”在平面上（法线朝上） this.transform.up = hit.normal; Debug.Log("物体已放置在: " + hit.point); } } private void OnDestroy() { if (pointCloudGesture != null) { pointCloudGesture.Tap -= OnTap; } } }

   • 在Unity编辑器中，将PointCloudGesture和PlaneTracker对象拖拽到脚本的对应字段。

5. 运行测试：

   • 运行场景，用摄像头缓慢扫描你所在的桌面或地面，让EasyAR有时间构建空间地图（你可能会在屏幕上看到稀疏的点云）。
   • 构建完成后，点击屏幕，你的Cube就会被“放置”在点击位置对应的真实平面上了。

4.3 视频与3D模型叠加

让AR体验更炫酷的，莫过于在识别图上播放视频，或者让复杂的3D模型动起来。

叠加视频：

1. 在ImageTarget下创建一个新的子对象，比如一个Quad（面片），调整其大小和位置，使其覆盖识别图区域。
2. 为这个Quad创建一个新的材质球（Material），Shader选择EasyAR/Background Video或Unlit/Texture。如果是前者，EasyAR会自动处理视频纹理；后者则需要手动赋值。
3. 编写脚本，使用EasyAR的VideoPlayer组件来加载和播放视频文件（需放置在StreamingAssets目录下），并将视频纹理赋给Quad的材质。

驱动3D模型动画：

1. 将带有Animator组件的FBX模型拖拽为ImageTarget的子对象。
2. 确保模型的缩放、位置合适。
3. 你可以通过脚本控制动画的播放。例如，在识别状态变化时触发动画：

   using UnityEngine; using easyar; public class TargetAnimationController : MonoBehaviour { public Animator modelAnimator; // 拖拽你的模型Animator组件到这里 private ImageTargetController imageTargetCtrl; void Start() { imageTargetCtrl = GetComponentInParent<ImageTargetController>(); if (imageTargetCtrl != null) { imageTargetCtrl.TargetFound += () => OnTargetFound(); imageTargetCtrl.TargetLost += () => OnTargetLost(); } } void OnTargetFound() { Debug.Log("目标找到，播放动画！"); if (modelAnimator != null) modelAnimator.Play("YourAnimationStateName"); } void OnTargetLost() { Debug.Log("目标丢失，停止动画。"); if (modelAnimator != null) modelAnimator.StopPlayback(); } }

   将这个脚本挂载到ImageTarget上，并将模型的Animator组件拖拽赋值。

5. 打包部署与平台适配

5.1 Android平台打包

移动端是AR的主战场，Android的打包流程相对标准，但有几个专属坑点。

1. Player Settings设置：

   • File -> Build Settings，切换平台到Android。
   • 点击Player Settings。
   • Other Settings区域：
     • Package Name:必须与EasyAR License中填写的完全一致。
     • Minimum API Level:建议设置为Android 7.0 ‘Nougat’ (API level 24)或更高。EasyAR某些高级功能需要较新的API。
     • Target API Level:设置为你测试设备的API级别或最新的稳定版。
     • Scripting Backend:推荐使用IL2CPP，以获得更好的性能和兼容性。
     • Target Architectures:勾选ARM64。现代Android设备基本都是64位，勾选此项能获得最佳性能。

2. 权限配置：AR应用必须获取摄像头权限。在Player Settings -> Other Settings中找到Write Permission，确保External (SDCard)权限被添加（如果需要保存截图或数据）。更关键的摄像头权限通常在Android清单文件中配置。EasyAR的SDK包中通常会包含一个预设的AndroidManifest.xml文件，它已经声明了必要的权限（CAMERA,INTERNET等）。检查你的Assets/Plugins/Android目录下是否有相关文件。

3. 构建与运行：

   • 用USB线连接你的Android手机，并开启开发者模式和USB调试。
   • 在UnityBuild Settings中点击Build And Run，选择输出APK的路径。
   • 首次构建可能会较慢，因为要编译IL2CPP。构建成功后，APK会自动安装到手机并运行。

5.2 iOS平台打包

iOS的打包流程因为需要Xcode的参与，步骤更多。

1. Player Settings设置：

   • 切换平台到iOS。
   • Player Settings：
     • Bundle Identifier:必须与EasyAR License中填写的完全一致。
     • Target minimum iOS Version:建议设置为11.0或更高。
     • Architecture:选择ARM64。
     • Camera Usage Description (隐私描述):这是必须填写的！用中文或英文描述你为什么需要访问摄像头，例如“用于增强现实功能展示”。这个描述会显示在系统向用户请求权限的弹窗上。

2. 生成Xcode工程：

   • 在Build Settings中点击Build，选择一个文件夹来存放生成的Xcode项目。

3. 在Xcode中配置：

   • 打开生成的.xcodeproj文件。
   • 确保Signing & Capabilities中选择了正确的开发者账号和团队，并自动管理签名。
   • 在Info.plist中，确认NSCameraUsageDescription键已存在，并且值是你刚才填写的描述。
   • 关键步骤：在Build Settings中，找到Enable Bitcode选项，将其设置为NO。Unity项目通常不支持Bitcode，保持开启会导致编译失败。

4. 连接真机运行：

   • 用数据线连接你的iPhone。
   • 在Xcode顶部的设备选择栏中，选择你的iPhone。
   • 点击运行按钮（三角形）。Xcode会编译项目并安装到你的手机上。首次运行需要在手机上信任开发者证书（设置->通用->设备管理）。

6. 常见问题排查与性能优化

6.1 问题排查速查表

6.2 性能优化实战心得

AR应用是资源消耗大户，优化做得好，体验差不了。

• 模型与纹理优化：

  • 面数：移动端AR展示的模型，面数最好控制在5万三角面以内，单个模型1万面左右为佳。使用LOD（多细节层次）技术，根据距离切换不同精度的模型。
  • 纹理：使用压缩格式（如ASTC），尺寸尽可能为2的幂次方（256x256, 512x512）。一张1024x1024的纹理足以应对大多数近距离观察的需求。
  • Draw Call：合并材质相同的静态物体，使用合批（Batching）技术。

• EasyAR特定优化：

  • 按需加载目标：不要一次性加载所有识别图。使用ImageTracker.LoadTarget和UnloadTarget方法动态管理。
  • 控制跟踪数量：在ImageTracker组件上设置Simultaneous Targets Number。如果场景中只需要识别一个目标，就设为1，可以节省计算资源。
  • 合理使用SLAM：平面跟踪（SLAM）非常耗电和算力。如果应用只需要图像识别，可以在AR Session中禁用Spatial Map Worker Frame Filter。

• 脚本优化：

  • 在Update函数中避免进行昂贵的计算或Find查找。
  • 对于AR跟踪到的位置更新，EasyAR通常会在底层线程处理，然后在主线程回调。在回调函数中更新物体变换是安全的，但要避免在回调中做复杂逻辑。

• 功耗与发热：

  • 在应用进入后台时，务必暂停AR会话（ARSession.Pause），回到前台时再恢复（ARSession.Resume）。这能显著减少电量消耗。
  • 如果应用有非AR界面，在切换到那些界面时，可以考虑关闭摄像头或降低帧率。

走到这里，你已经完成了从零到一的EasyAR入门之旅。从我个人的经验来看，AR开发最迷人的地方在于它连接了数字与现实的边界，而EasyAR则是一把非常称手的“开山刀”。初期按照教程一步步走通流程很重要，它能帮你建立信心。但真正做出有创意的应用，需要你跳出教程，多思考“如果我想实现XX效果，该怎么做？”。这时候，回头去仔细阅读EasyAR官方文档的API部分，查阅社区论坛的案例，甚至去研究Samples示例工程里的高级用法，会比任何教程都管用。遇到问题别怕，记住排查问题的核心思路：从License和配置检查起，再到权限和平台设置，最后才怀疑是代码逻辑问题。大多数坑，前辈们都踩过，善用搜索，你也能快速成长。最后一个小建议，多做真机测试，编辑器里的表现和手机上的真实体验，有时候是天壤之别。