1. 项目概述：从零构建你的第一个空间锚点应用

如果你刚拿到HoloLens 2，看着官方示例里那些能稳定停留在真实世界中的虚拟物体，心里一定痒痒的，想自己动手实现一个。这个教程就是为你准备的。我们将抛开复杂的框架和抽象概念，直接动手，在Unity里使用MRTK（Mixed Reality Toolkit）创建一个最简单的空间锚点应用。所谓空间锚点，你可以把它理解成一个虚拟的“图钉”，它能记住自己在真实三维空间中的精确位置和朝向。即使你关闭应用、重启设备，甚至房间里的家具被挪动过，当你再次打开应用时，那个虚拟的“图钉”以及它关联的物体，依然会出现在你当初放置它的地方。这对于需要持久化内容的混合现实体验至关重要，比如在会议室墙上固定一个虚拟白板，或者在机床旁边放置一个永久的操作指引。

整个项目我们会聚焦于最核心的流程：初始化MRTK环境、创建一个可交互的虚拟物体、编写代码实现锚点的保存与加载，最后在HoloLens 2上验证其持久性。过程中，我会穿插很多我实际开发中踩过的坑和总结的技巧，这些在官方文档里往往不会写得那么直白。我们使用的工具链是当前最主流和稳定的组合：Unity 2021.3 LTS + MRTK 3.0 + OpenXR插件。这个组合在兼容性和功能支持上达到了一个很好的平衡，能确保我们的教程步骤清晰、结果可复现。

2. 环境准备与项目初始化

2.1 Unity版本与MRTK导入

第一步是搭建一个干净、正确的开发环境。我强烈建议使用Unity 2021.3.x这个长期支持版本。它非常稳定，对URP（通用渲染管线）和OpenXR的支持成熟，是混合现实开发的“安全区”。不要盲目追求最新版本，新版本可能引入未知的插件兼容性问题，会浪费大量排查时间。

创建项目时，选择“通用渲染管线（URP）”模板。这是因为MRTK 3.0及以后的版本主要围绕URP进行优化和构建，使用URP能获得更好的性能和视觉效果。项目创建好后，我们通过Unity的Package Manager来导入MRTK。不要从Asset Store下载，那样版本管理会很混乱。在Package Manager窗口，点击左上角的“+”号，选择“Add package by name...”，然后输入com.microsoft.mixedreality.toolkit。等待其解析并安装核心包。安装完成后，Unity会弹出一个“MRTK Project Configurator”窗口。这里非常关键，你需要确保勾选“Initialize XR Plugin Management for OpenXR”。这个选项会自动帮你配置好项目的XR设置，并安装必要的OpenXR插件包，省去大量手动配置的麻烦。

注意：如果安装MRTK后没有自动弹出配置窗口，你可以手动在菜单栏找到Mixed Reality->Toolkit->Utilities->Configure Project for MRTK...来启动它。务必确保配置成功，否则后续步骤会报错。

2.2 场景基础配置

MRTK导入并配置成功后，你的项目里会多出很多预制体和资源。接下来，我们需要为场景搭建一个混合现实的基础运行环境。最简单的方法是使用MRTK提供的场景搭建工具。在Hierarchy窗口右键，选择Mixed Reality Toolkit->Add to Scene and Configure...。这个操作会向场景中添加一个名为“Mixed Reality Toolkit”的游戏对象，它承载了MRTK的核心系统。

随后，我们需要一个能让用户“置身其中”的环境。再次在Hierarchy窗口右键，选择Mixed Reality Toolkit->Scene->Add Basic Scene Setup。这会添加一系列关键对象：

• MixedRealityPlayspace：代表用户（相机）的父对象，处理头部移动。
• MRTK XR Rig：集成了手部追踪、眼动追踪等输入功能的XR设备控制器。
• DefaultMixedRealityToolkitConfigurationProfile：MRTK的默认配置档案，包含了输入、空间感知、诊断等系统的设置。

完成这些后，你的场景应该已经具备了在Unity编辑器中模拟混合现实交互的基础能力。你可以按下播放键，尝试用手柄或模拟手势来与场景交互，看看基本的射线点击是否生效。

2.3 配置空间感知与锚点子系统

空间锚点的功能依赖于Unity的XR插件管理系统和底层的锚点子系统。我们需要确保它们被正确启用。打开Edit->Project Settings， 然后选择XR Plug-in Management。

1. 在“Windows”标签页下，找到“OpenXR”。如果它没有被勾选，请勾选它。然后点击“OpenXR”字样进入详细设置。
2. 在“Interaction Profiles”下，确保添加了“Microsoft Motion Controller Profile”和“Microsoft Hand Interaction Profile”，以支持HoloLens 2的手部追踪和控制器。
3. 最关键的一步：在“OpenXR”设置页面的下方，找到“Features”列表。你需要确保Microsoft HoloLens这个特性组被展开，并且其下的Spatial Anchor功能是启用状态。如果没找到，可能需要点击“+”号添加这个特性。

这一步是告诉Unity和OpenXR运行时，我们的应用需要访问HoloLens的空间锚点API。如果这里配置错误，后续所有关于锚点的代码都将无法工作。

3. 核心原理：空间锚点是如何工作的

在动手写代码前，花几分钟理解其背后的原理，能让你在调试时事半功倍。Unity中的空间锚点（UnityEngine.XR.WSA.WorldAnchor在旧版，或UnityEngine.XR.ARSubsystems.XRAnchorSubsystem在新版/OpenXR流程下）并不是一个魔法黑盒。

它的本质是一个空间坐标系绑定。当你为一个GameObject创建锚点时，系统会采集当前时刻该物体周围环境的特征点信息（通过HoloLens的深度摄像头和环境理解摄像头）。这些特征点可能是墙角、桌沿、纹理丰富的海报等具有独特几何或视觉模式的位置。系统将这些特征点的空间关系加密后，在设备本地生成一个唯一的锚点ID和对应的空间数据包。

保存（持久化）：当你调用保存方法时，这个数据包会被存储到设备的一个特殊、受保护的持久化存储区中。你可以选择将其上传到Azure Spatial Anchors这样的云服务，实现跨设备共享。在本教程中，我们只涉及本地存储。

加载（还原）：当应用再次启动并请求加载锚点时，系统会重新扫描当前环境，寻找与存储的数据包匹配的特征点。一旦找到足够多的匹配点，它就能解算出当初那个坐标系相对于当前设备位置的方向和姿态，然后将虚拟物体准确地放置回去。这个过程被称为“重定位”。

因此，锚点的稳定性高度依赖于环境。在特征稀少、反光、或动态变化剧烈的环境（如一面纯白的光滑墙壁前），创建和重定位锚点可能会失败或精度下降。理解这一点，你就知道为什么测试时要选择纹理丰富的稳定环境了。

4. 创建可锚定的虚拟物体与交互逻辑

4.1 设计一个简单的锚定对象

我们不搞复杂的模型，就用一个Cube来演示。在Hierarchy中创建一个Cube，重置其Transform，然后稍微调整一下，比如把Scale改成(0.2, 0.2, 0.2)，让它变成一个方便抓取和观察的小方块。

为了让它在混合现实中看起来更自然，我们需要给它添加一些MRTK组件。首先，删除自带的Box Collider，然后通过Add Component添加以下MRTK组件：

• Object Manipulator：这个组件让物体可以通过手部追踪进行抓取、移动和旋转。在它的配置里，你可以勾选“Two Handed Manipulation”来启用双手缩放等高级操作。
• Near Interaction Grabbable：启用近距离手部抓取交互。没有它，你的手可能无法直接“握住”这个Cube。
• （可选）Constraint Manager：可以添加这个组件来配置移动、旋转、缩放的约束，比如限制它只在某个平面上移动。

接着，为这个Cube创建一个新的材质球，选一个醒目的颜色，比如亮蓝色。这样在HoloLens的透视视图里会更容易被看到。

4.2 编写锚点管理脚本

这是整个教程的核心代码部分。我们将创建一个名为SpatialAnchorManager的C#脚本，并把它挂载到我们的Cube上。

using UnityEngine; using UnityEngine.XR.ARSubsystems; // 新版锚点API所在的命名空间 using UnityEngine.XR.ARFoundation; // ARFoundation包含了锚点子系统的访问接口 using System.Collections.Generic; using System.Threading.Tasks; public class SpatialAnchorManager : MonoBehaviour { private ARAnchorManager _anchorManager; // 锚点管理器 private ARAnchor _localAnchor; // 当前关联的锚点组件 private string _anchorIdKey = “SavedAnchorId”; // 用于在PlayerPrefs中存储锚点ID的键名 void Start() { // 获取或创建ARAnchorManager _anchorManager = FindObjectOfType<ARAnchorManager>(); if (_anchorManager == null) { Debug.LogError(“ARAnchorManager not found in scene. Please ensure MRTK scene setup is complete.”); return; } // 尝试加载之前保存的锚点 LoadAnchor(); } // 为当前物体创建并附加一个新的空间锚点 public void CreateAnchor() { if (_anchorManager == null || _anchorManager.subsystem == null || !_anchorManager.subsystem.running) { Debug.LogWarning(“Anchor subsystem not ready.”); return; } // 如果已存在锚点，先销毁它 if (_localAnchor != null) { Destroy(_localAnchor.gameObject); } // 使用ARAnchorManager在物体当前位置创建锚点 // 注意：CreateAnchor是异步方法，返回一个Task<ARAnchor> var anchorGameObject = new GameObject(“Local Spatial Anchor”); anchorGameObject.transform.SetPositionAndRotation(transform.position, transform.rotation); _localAnchor = anchorGameObject.AddComponent<ARAnchor>(); // 将创建的锚点游戏对象作为当前物体的子物体，建立关联 anchorGameObject.transform.SetParent(transform, false); Debug.Log($“Anchor created at: {transform.position}”); } // 保存当前锚点的ID到本地（此处为简化演示，使用PlayerPrefs） public void SaveAnchor() { if (_localAnchor == null) { Debug.LogWarning(“No anchor to save. Create an anchor first.”); return; } // ARAnchor有一个trackableId，是系统赋予的唯一标识符 string anchorId = _localAnchor.trackableId.ToString(); PlayerPrefs.SetString(_anchorIdKey, anchorId); PlayerPrefs.Save(); // 立即保存 // 在实际项目中，你可能需要保存更多信息，比如锚点的位置、关联的物体数据等。 // 这里我们简单保存ID，并假设物体位置相对于锚点是固定的（因为锚点是父物体）。 Debug.Log($“Anchor saved with ID: {anchorId}”); } // 尝试加载并定位之前保存的锚点 public async void LoadAnchor() { string savedAnchorId = PlayerPrefs.GetString(_anchorIdKey, string.Empty); if (string.IsNullOrEmpty(savedAnchorId)) { Debug.Log(“No saved anchor found.”); return; } Debug.Log($“Attempting to load anchor with ID: {savedAnchorId}”); // 重要：在真实场景中，加载锚点是一个异步过程，需要等待子系统在环境中重新定位。 // 这里是一个简化的示意流程。实际ARFoundation的加载更复杂，可能涉及会话重载。 // 对于HoloLens + MRTK，更常见的做法是使用WorldAnchorStore（旧API）或直接依赖云服务如ASA。 // 以下代码块旨在说明原理，在MRTK 3 + OpenXR下可能需要适配。 // 原理性提示：在实际编码中，你需要： // 1. 通过ARAnchorManager的子系统监听锚点添加事件。 // 2. 当子系统报告发现一个锚点（其trackableId与你保存的ID匹配）时，获取该锚点的GameObject。 // 3. 将你的虚拟物体（这个Cube）移动到该锚点游戏对象的位置，或将其设为锚点的子物体。 // 由于这是一个快速变化的领域，具体实现请务必参考Unity和MRTK的最新官方文档和示例。 Debug.Log(“Anchor load process triggered. (Note: Full implementation requires handling ARFoundation anchor events.)”); } // 删除本地保存的锚点数据 public void DeleteAnchor() { PlayerPrefs.DeleteKey(_anchorIdKey); if (_localAnchor != null) { Destroy(_localAnchor.gameObject); _localAnchor = null; } Debug.Log(“Saved anchor data deleted and local anchor removed.”); } }

代码关键点解析：

1. ARAnchorManager：这是ARFoundation中管理锚点生命周期的中心组件。我们的场景中应该已经通过MRTK配置隐含地拥有了一个AR Session Origin，它上面通常附有ARAnchorManager。
2. CreateAnchor方法：它创建了一个新的GameObject，为其添加ARAnchor组件，然后将其设为当前Cube的子物体。这意味着Cube的位置和旋转将相对于这个锚点。当锚点在物理世界中被重定位时，Cube会跟着移动。
3. SaveAnchor方法：这里我们使用了PlayerPrefs来存储锚点的唯一ID。这是一个为了教程简化的做法。在真正的生产应用中，PlayerPrefs并不适合存储大量或关键数据。对于本地持久化，你应该使用文件系统（如Application.persistentDataPath）或更结构化的本地数据库。对于跨设备共享，则必须使用Azure Spatial Anchors等云服务。
4. LoadAnchor方法：这里的实现是示意性的。完整的加载流程涉及订阅ARAnchorManager的事件，等待锚点子系统在环境中重新发现并报告锚点。由于这部分代码与Unity的AR子系统版本和具体设置紧密相关，且篇幅较长，本教程以阐述核心流程和原理为主。强烈建议你在掌握基础后，查阅MRTK和ARFoundation关于“Anchor”的最新示例项目来获取可工作的完整代码。
5. 异步操作：很多空间计算操作（如创建、保存、查询锚点）都是耗时的，应该使用异步编程（async/await）来避免阻塞主线程，防止应用卡顿或无响应。

4.3 创建简易用户界面

为了让测试更方便，我们添加两个简单的3D UI按钮来控制锚点操作。使用MRTK的预制体可以快速完成。

1. 在Hierarchy中，右键选择Mixed Reality Toolkit->UI->PressableButton。这会创建一个带有完整视觉和交互反馈的3D按钮。
2. 将按钮放置在摄像机前方合适的位置（例如，Position (0, -0.3, 1)）。
3. 选中按钮，在Inspector中找到“Interactable”组件下的“OnClick()”事件列表。
4. 点击“+”号添加一个新事件。
5. 将场景中的Cube（带有SpatialAnchorManager脚本）拖拽到事件对象的框里。
6. 在下拉菜单中，选择SpatialAnchorManager->CreateAnchor方法。
7. 重复步骤1-6，创建第二个按钮，并将其事件绑定到SpatialAnchorManager->SaveAnchor方法。你可以修改按钮的文本（在子对象TextMeshPro上）来区分它们，比如“创建锚点”和“保存锚点”。

现在，在Unity编辑器的播放模式下，你可以用手部射线点击按钮，来触发创建和保存锚点的操作了。

5. 在HoloLens 2上部署与测试

5.1 项目构建设置

在将应用部署到真机前，需要对Unity项目进行正确的打包设置。

1. 打开File->Build Settings。
2. 确保当前场景已被添加到“Scenes In Build”列表中。
3. 在“Platform”列表中选择“Universal Windows Platform”，然后点击“Switch Platform”。
4. 点击“Player Settings”按钮，打开项目设置。
5. 在“Player Settings”中，找到“Other Settings”：
   • Scripting Backend：确保为IL2CPP。这是发布到UWP平台的强制要求，能带来更好的性能和安全性。
   • Target Device：选择HoloLens。
   • Architecture：选择ARM64。HoloLens 2使用ARM64架构的处理器。
   • 在“Configuration”部分，找到“Scripting Define Symbols”，添加UNITY_WSA和WINDOWS_UWP（如果不存在的话），以确保平台相关的代码被正确编译。
6. 在“Publishing Settings”部分：
   • Capabilities：这是权限声明，必须勾选SpatialPerception。没有这个权限，应用将无法访问摄像头进行空间映射，锚点功能也就无从谈起。根据你的应用需求，可能还需要勾选“InternetClient”（如果需要访问网络服务，如Azure Spatial Anchors）、“Microphone”等。
   • Supported orientations：取消所有勾选，仅保留Landscape Left。混合现实应用通常是全息沉浸式的，不需要屏幕旋转。

5.2 生成Visual Studio工程并部署

1. 回到Build Settings窗口，点击“Build”按钮。
2. 选择一个空文件夹来存放生成的Visual Studio解决方案（.sln文件）和工程文件。
3. Unity编译完成后，会打开你选择的文件夹。找到其中的.sln文件，用Visual Studio 2022（或更高版本）打开它。确保你安装了“使用C++的桌面开发”和“通用Windows平台开发”工作负载。
4. 在Visual Studio的顶部工具栏，将解决方案配置从“Debug”改为“Release”，将平台从“x86”改为“ARM64”。
5. 在右侧的解决方案资源管理器中，右键点击Unity生成的项目（通常是解决方案名称后带“.WSA”），选择“属性”。
6. 在属性页中，确保“目标设备”是“HoloLens 2”，并且“远程计算机”的IP地址是你的HoloLens 2的IP地址（可以在HoloLens的设置->网络->高级选项中查看）。或者，你也可以选择“设备”，通过USB连接线直接部署。
7. 点击顶部菜单的“调试”->“开始执行(不调试)”或按Ctrl+F5。Visual Studio会开始编译应用并将其部署到你的HoloLens 2上。

实操心得：第一次部署时，HoloLens可能会提示“正在安装证书”或“启用开发者模式”。请按照设备屏幕上的提示操作。确保在HoloLens的设置->更新与安全->开发者选项中，已经开启了“开发者模式”和“设备发现”。

5.3 真机测试流程与验证

应用成功部署并启动后，戴上你的HoloLens 2，开始测试：

1. 环境选择：找一个特征丰富、光照稳定的区域，比如有家具、装饰画、书架的房间一角。避免面对空旷的白墙或强光直射的窗户。
2. 创建锚点：用手部射线点击“创建锚点”按钮。你应该能看到Cube上或附近出现一个视觉提示（如果脚本添加了的话），或者至少在Unity的调试输出（如果部署了调试版本）中看到“Anchor created”的日志。
3. 移动并保存：用手直接抓取Cube，将它移动到一个新的位置（比如从桌子中间移到桌子边缘）。然后点击“保存锚点”按钮。
4. 验证持久性：这是最关键的一步。退出应用。你可以通过系统手势回到开始菜单。然后，在房间里走动一下，甚至可以把HoloLens 2放下休息几分钟。之后，重新启动你的应用。
5. 观察结果：应用启动后，LoadAnchor方法（或其完整实现）会被调用。如果一切顺利，你的Cube应该出现在你之前保存它的位置（桌子边缘），而不是初始位置或世界原点。这表明空间锚点成功地将虚拟物体的位置与真实世界的一个特定点绑定并持久化了。

6. 常见问题排查与进阶技巧

6.1 部署与运行问题排查表

6.2 进阶技巧与最佳实践

1. 视觉反馈至关重要：在创建、保存、加载锚点时，给用户明确的视觉或听觉反馈。例如，创建锚点时让物体闪烁一下，保存成功时播放一个音效。这能极大提升用户体验，让用户知道操作已生效。
2. 异步操作与状态管理：所有锚点操作（创建、保存、查询）都应设计为异步，并使用状态机管理UI。例如，在加载锚点时，显示一个“正在定位...”的提示；操作失败时，给出友好的错误提示，而不是让应用卡住。
3. 错误处理与重试：网络不稳定或环境识别失败是常态。你的代码必须能优雅地处理这些错误，并提供重试机制。例如，加载锚点失败后，可以提示用户“缓慢环顾四周”，然后自动或手动触发重试。
4. 超越本地存储：PlayerPrefs和本地文件只适用于单设备。要实现跨设备、跨会话的共享体验，Azure Spatial Anchors (ASA)是几乎唯一的企业级选择。它提供了强大的云锚点服务，支持iOS、Android、HoloLens等多平台。MRTK对ASA有良好的集成支持，后续可以很容易地将本教程的本地锚点升级为云锚点。
5. 性能考量：一个场景中不宜创建过多（如上百个）高精度的空间锚点，这会增加系统负载和重定位时间。对于大量需要持久化的物体，可以考虑使用相对坐标，将它们作为少数几个“父锚点”的子物体来管理。
6. 调试利器：在开发过程中，务必启用MRTK的诊断工具（通常在MixedRealityToolkit游戏对象的配置文件中启用）。它可以实时显示空间映射网格、手部关节、视线射线等信息，对于理解应用与环境的交互状态有巨大帮助。

这个教程为你打通了从零到一的第一公里。空间锚点是混合现实持久化内容的基石，理解并掌握了它，你就打开了构建真正实用、可共享的混合现实应用的大门。接下来，你可以尝试用Azure Spatial Anchors替换本地存储，实现多人协同查看同一虚拟物体；或者设计更复杂的锚点交互逻辑，比如让锚点成为游戏中的存档点或信息标记点。