Machine-readable: manifest · index · 简体中文 Markdown

使用 Unity 模板开发并发布第一个 AR 应用

01Spatial Unity 模板是一套面向二次开发的 AR Foundation 开发包。它以 .unitypackage 形式交付，可以直接导入你新建的 Unity 工程：iOS 使用 ARKit，Android 使用 ARCore；01Spatial 负责通过视觉定位，把设备当前的 AR Session 对齐到持久地图坐标。

模板已经包含单帧 Snap、通过四帧 Scan 完成的多帧定位、Auto 自动定位的演示，以及地图坐标对齐、服务端 Content、遮挡网格、定位成功后以脉冲形式显示 Mesh 的动画效果和响应式界面。默认交互在 iOS 上参考 App Clip，在 Android 上参考 WebXR。你可以替换界面、业务逻辑和三维内容，也可以扩展定位工作流，开发完整的自定义 AR 应用。

完成本教程后，你将得到一个可以在真机上运行的应用：用户对准已经建图的空间并完成定位后，由你放置的内容会出现在地图中的固定位置。之后无论哪台设备进入该空间，内容都使用同一地图坐标出现。

1. 准备开发环境和地图

开始前只需要准备四项：

Unity Hub 与 Unity 6000.3.19f1。
01Spatial 提供的 01SpatialAR-<版本号>.unitypackage 文件。
一张状态为 Ready（已就绪） 的 01Spatial 地图。还没有地图时，请先按建图流程完成采集和构建。
一台支持 ARCore 的 Android 真机，或一台支持 ARKit 的 iPhone/iPad。

API Key 和 Map Key 会在后续步骤中取得。Android、iOS 各自需要的 Unity 模块也放到对应的构建章节再安装，不必在开始时一次准备完。

Unity Editor 的 Game 视图没有真实的 ARKit/ARCore 相机 CPU Image，不能完成端到端定位。场景摆放可以在 Editor 中进行，定位结果必须在真机上验收。

2. 创建账号并取得 API Key

API Key 表示“由哪个账号调用 01Spatial”，Map Key 表示“使用哪一张地图”。Unity 模板需要两者，它们都从 01Spatial 开发者 Portal 获取。

2.1 选择正确的 Portal

账号、API Key 和 Map Key 必须来自同一个服务区域：

地区	Portal	Unity 中的 Server Region
中国	portal.01spatial.cn	`CN (China)`
EU 服务	portal.01spatial.ai	`EU (Europe)`

中国 Portal 创建的 Map Key 不能拿到 EU 服务解析，反之亦然。请根据地图所在区域选择，而不是根据开发电脑所在位置选择。

2.2 注册并登录

打开对应地区的 Portal，选择注册。
使用支持的第三方账号注册，或填写姓名、邮箱和密码。
阅读并勾选当前版本的用户协议和隐私文件，然后完成注册。
按页面提示完成邮箱验证或再次登录。

2.3 生成并复制 API Key

登录后打开右上角用户菜单，选择 个人资料。
找到 API Key 区域。
如果账号还没有 Key，选择 生成 API Key；已有 Key 时直接复制。
把 Key 暂时保存在安全的密码管理器中，后面要粘贴到 Unity。

选择 重新生成 会让旧 API Key 立即失效，所有仍使用旧 Key 的 Unity、WebXR、App Clip 或服务端应用都会停止工作。只有在已经列出并准备更新全部客户端时才轮换 Key。更多范围和安全说明见凭证与 Key。

3. 新建 URP 工程并导入 Unity Package

我们推荐从一个空白的 Universal Render Pipeline（URP） 工程开始：

打开 Unity Hub，选择 New project。
选择 Unity 6000.3.19f1 和 Universal 3D 模板，填写项目名称与保存位置，然后选择 Create project。
等待新工程首次导入完成。在 Unity 中选择 Assets > Import Package > Custom Package…。
选择 01Spatial 提供的 01SpatialAR-<版本号>.unitypackage。
在 Import Unity Package 窗口中保留全部文件选中，然后选择 Import。
如果 Unity 提示缺少依赖，选择 Install；也可以从顶部菜单选择 01Spatial > Install Missing Packages。等待 Package Manager 安装完成并让 Unity 完成脚本编译。
在 Project 窗口中打开 Assets/Scenes/01SpatialAR.unity。
正式开发时，建议立即用 File > Save As… 把场景另存到自己的产品目录，例如 Assets/MyProduct/Scenes/01SpatialAR.unity。这样以后升级 01Spatial 包时，不会覆盖你的场景改动。

导入包后看到依赖警告是 .unitypackage 格式本身不能声明 UPM 依赖所致；执行第 6 步即可。依赖安装和脚本编译都完成后，Console 不应再有 01Spatial 相关编译错误。

本教程后续以随包提供的 01SpatialAR 场景为起点。如果你要把 01Spatial 接入一个已经拥有 AR Foundation Rig 的产品场景，请改用 01Spatial > Add To Scene… 并选择 Use my existing AR rig；不要在同一场景中创建第二套 ARSession、XR Origin 或 AR Camera。

4. 认识场景和坐标层级

01SpatialAR 场景的实际 Hierarchy 如下：

AR Session & Camera
├── AR Session
└── XR Origin
    └── Camera Offset
        └── AR Camera

01Spatial (Localization Services)
├── Map Features
│   ├── Environment Lighting
│   │   └── Environment Main Light
│   ├── Spatial Content
│   └── Occlusion Mesh
├── Localization UI
└── Event System

XRSpace
├── SDK Content (Generated)
│   └── Map Origin Axes
└── Map - Sample
    ├── Logic (Always Active)
    └── Content (Visible When Localized)

Authoring Light (Editor Only)

第一次使用时，你只需要关注 XRSpace > Map - Sample > Content (Visible When Localized)：把需要固定在真实空间中的模型、文字、粒子、动画或交互对象放在这里。定位成功后，这个节点下的内容会按地图坐标显示。

其余节点保持模板默认状态即可：

不要修改 AR Camera 的 Transform，也不要移动、旋转或缩放 XRSpace、Map - Sample 或 SDK Content (Generated)。
不要把自己的内容放进 SDK Content (Generated)；它由 01Spatial 管理。
Content (Visible When Localized) 和 AR Session & Camera 在编辑状态下显示为未激活是模板的正常状态，不需要手工“修复”。
Authoring Light (Editor Only) 只帮助你在 Scene 视图中看清模型，构建应用时会被 Unity 自动移除。
下载地图后，Map - Sample 下还会出现 Reference Geometry (Editor Only)，供你在编辑器中对照真实空间摆放内容；它同样不会进入应用构建。

4.1 实现中的关键链路

普通接入不需要直接调用内部实现。产品脚本优先面向稳定接口 ISpatialClient：模板中的 SpatialClientRuntime 实现了这个接口，可发起 Snap、Scan、Auto，切换地图，并接收定位成功、失败和状态变化事件。

如果你要继续阅读源码、替换界面或扩展工作流，可以从这条真实链路开始：

SpatialClientRuntime 是场景中的客户端入口，连接账号配置、地图、相机帧源、定位后端、工作流与功能模块。
CameraFrameCaptureService 挂在 AR Camera 上，从同一帧取得图片、相机内参和 AR 位姿。
Spatial01LocalizationBackend 使用 Map Key 解析地图，并创建与 01Spatial 定位 API 通信的 Transport。
DefaultSpatialLocalizationWorkflowFactory 创建一个同时支持 Snap、Scan 和 Auto 的默认工作流。实际状态机类 DefaultSpatialLocalizationWorkflow 是 SDK 内部实现，不需要由产品代码直接实例化。
SlamVpsFusion 根据定位结果及其对应采样帧，计算地图坐标到当前 AR Session 的对齐变换；最终变换由 SpatialClientRuntime 应用到 XRSpace。
SpatialFeatureHost 管理服务端 Content、Mesh 和环境光等功能模块。本地 Content (Visible When Localized) 的显隐则由 SpatialMapSpace 与 SpatialAlignedVisibility 控制，只在对齐可靠后显示。

这些名称均来自当前 Unity SDK 的公开类型或实际内部实现。常用入口是 TryRequestSnap()、TryStartOrCancelScan()、SetAutoLocalization(bool)，以及 StateChanged、LocalizationSucceeded、LocalizationFailed 事件；不要直接改写 AR Camera 的位姿。

5. 在 Unity 中连接账号

在 Unity 顶部菜单选择 01Spatial > Account。
在 Server Region 中选择地图所在服务：
- 中国地图选择 CN (China)，对应 https://api.01spatial.cn；
- EU 地图选择 EU (Europe)，对应 https://api.01spatial.ai；
- 只有自托管或测试环境才使用 Custom。
把个人资料中复制的 API Key 粘贴到 API Key。
选择 Save。
选择 Verify API Key。

如果场景还没有有效 Map Key，验证按钮只能确认 URL 和 Key 的本地格式；配置好下一节的 Map Key 后再次验证，Unity 才会通过真实的地图解析请求同时验证账号权限、服务区域和地图。

账号窗口只管理账号和工程级设置。定位模式、Content、Mesh、定位成功后的 Mesh 脉冲动画和诊断参数已经移到 01Spatial > Localization；可使用窗口中的 Open Localization… 进入。第一次使用时保持这些运行时参数的默认值，除非已经有真机测量结果支持修改。

账号配置默认保存在 Assets/01Spatial/TemplateAssets/01SpatialClientConfig.asset，其中的 Key 以明文写在资产里。不要把真实凭证提交到公开仓库、打印到日志或包含在公开的 .unitypackage 中；提交或交付前执行 01Spatial > Development > Scrub Credentials For Commit，它会扫描 Assets/ 下的场景、预制体和配置资产并把真实 Key 换回占位符。移动端安装包中的长期 Key 也无法做到绝对保密；面向公众发布时，应通过受控后端、短期授权或正式发布入口限制滥用，并配合服务端授权策略。

6. 复制 Map Key 并连接地图

6.1 从 Portal 复制 Map Key

回到与 Unity Server Region 相同地区的 Portal。
打开 Spatial Maps，找到要用于应用的地图。
等待地图状态变为 Ready（已就绪）。仍在 Building、Processing 或 Failed 状态的地图不能用于定位。
在 Ready 地图卡片中找到 Map Key（地图密钥），选择 Copy（复制）。不要手工抄写。

Map Key 的完整说明和地图操作见管理地图。当前 Unity 模板按场景中的每个 Map 节点配置 Map Key；不要把 Project Key 粘贴到这个输入框。

6.2 在场景中配置 Map

回到 Unity，选择 01Spatial > Maps。
默认场景已有 Map - Sample。在这一行的 Map Key 输入框粘贴刚复制的 Key。
如果场景中没有 Map，选择 Add Map 创建一个；可以在 Hierarchy 中给它改一个容易识别的名字。
一个场景可以配置多个 Map，但必须有且只有一个起始地图。目标行显示 Active 即为起始地图；否则选择 Set Active。
选择该 Map 行中的 Verify。
确认结果显示地图名称、ready，并留意 metric 或 non-metric 提示。
保存场景。

Verify 失败时，优先检查 API Key 与 Map Key 是否属于同一 Portal 地区、API Key 所属账号是否有权访问该地图，以及地图是否为 Ready。

7. 下载地图

01Spatial > Maps 可以把地图的点云或 Mesh 下载到 Unity，让你在 Scene 视图中看见真实空间，并据此摆放 AR 内容。这些下载数据只用于编辑，不会被打包进 App；真机运行时仍通过 API Key + Map Key 定位，并按需加载服务端内容和网格。

7.1 下载点云

在 01Spatial > Maps 中找到已经 Verify 的 Map。
如果地图来自 LiDAR，并且希望优先使用高密度 LiDAR 点云，勾选 Prefer LiDAR point cloud (source=lidar)。没有 LiDAR 点云时服务会自动回退到 SfM 稀疏点云。
在界面的 Reference Geometry > Point Cloud 行选择 Download；已经下载过时，按钮文字会变为 Update。Reference Geometry 是 Unity 当前界面中的功能分组名称。
等待下载、解析和资产导入完成。
使用 Point Cloud 行的眼睛按钮在 Scene 视图中显示或隐藏点云。上方的 Point Size 和颜色设置只影响编辑器中的预览效果。

7.2 下载 Mesh

在同一 Map 的 Reference Geometry > Mesh 行选择 Download；已经下载过时选择 Update。
等待纹理网格或可用的场景网格下载并导入。
使用 Mesh 行的眼睛按钮切换显示。

点云和 Mesh 可以只下载一种，也可以同时下载。Mesh 更容易看清墙面和物体表面，点云通常更轻，并能显示建图实际覆盖范围。

下载内容缓存在：

Assets/01Spatial/MapReferenceCache/map_<地图 ID>/

该目录是当前开发者的本地缓存，已经被 Git 忽略。下载后的对象位于 Map 下的 Reference Geometry (Editor Only)，带有 EditorOnly 标记，不会进入 Android APK 或 iOS Player。不要把正式产品内容放在这个节点下。

如果 Portal 中重新设置了地图 Origin，Unity 会提示本地下载的地图已过期。重新 Verify 并下载地图后，再检查所有产品内容的位置。non-metric 地图的下载数据和定位坐标仍一致，但 Unity 中 1 个单位不一定严格等于真实 1 米；需要按真实尺寸摆放内容时，应优先使用具有公制尺度和正确重力方向的地图。

8. 在地图中摆放内容

你可以摆放普通模型、带动画的复杂模型、Prefab、文字、粒子和交互对象。下面先用一个边长 20 厘米的立方体演示通用流程；把 Cube 换成自己的内容时，父子层级和摆放方法完全相同。示例假设地图为 metric；如果地图是 non-metric，请以下载地图的视觉比例为准。

在 01Spatial > Maps 的目标 Map 行选择 Select Content Root。Unity 会在 Hierarchy 中选中该地图的 Content (Visible When Localized)。
Content 在编辑状态下显示为灰色或未激活是正常的。需要在 Scene 视图中查看和摆放内容时，可以临时勾选 Inspector 顶部、对象名左侧的激活复选框；编辑完成后再取消勾选，让场景继续保持“定位成功后显示”的默认状态。
保持 Content 被选中，选择 Unity 菜单 GameObject > 3D Object > Cube。
把新对象重命名为 My First AR Cube。

在 Inspector 中把 Transform 设置为：

Local Scale:    X 0.2, Y 0.2, Z 0.2
Local Rotation: X 0,   Y 0,   Z 0

使用 Move Tool，在下载的点云或 Mesh 上把立方体移动到目标位置。一个常见做法是让立方体中心位于桌面上方 0.1 米，这样它的底面刚好落在桌面上。换成自己的模型时，也要依据模型的 Pivot 和真实尺寸调整位置与缩放。

再次确认 Hierarchy 中的父子关系是：

XRSpace
└── <你的 Map>
    └── Content (Visible When Localized)
        └── My First AR Cube

保存场景。下载的点云或 Mesh 可继续显示，也可以用眼睛按钮隐藏；它们不会进入最终安装包。

截图用于说明父子层级和如何对着下载的地图摆放内容；截图中示例 Cube 的 Transform 不是本教程的 20 厘米参数，请以第 5 步的 0.2, 0.2, 0.2 为准。

不要把产品内容放在 AR Camera、XRSpace、SDK Content (Generated) 或 Reference Geometry (Editor Only) 下。只有放在目标 Map 的 Content 下，它才会同时获得正确地图坐标和“定位成功后显示”的生命周期。

如果只想快速验证流程，模板还提供 Assets/01Spatial/Samples/SampleMarkerSpawner.cs。把 01Spatial/Samples/Sample Marker Spawner 添加到一个持续激活的对象并绑定 SpatialClientRuntime 后，它会在应用启动时把示例立方体生成到内容根节点下，并在首次可靠定位后随该根节点显示；正式内容仍建议按上面的层级直接摆放或使用自己的 Prefab/业务系统。

9. 理解真机上的定位流程

应用启动后会依次发生以下事情：

系统请求相机权限并启动 ARKit 或 ARCore。
模板等待 AR Session 与 XR Provider 进入完整 Tracking 状态。
用户选择 Snap 时发送当前同步相机帧；选择 Scan 时按引导采集四帧；开启 Auto 后按配置间隔自动重定位。
01Spatial 返回相机在地图中的位姿，模板将相应变换写入 XRSpace，而不是 AR Camera。
定位可靠后，当前 Map 的 Content (Visible When Localized) 整体显示；服务端 Content 和遮挡网格也按配置工作。如果启用了对应效果，系统会在定位成功后以脉冲形式显示 Mesh，作为一次清晰的成功动画反馈。
AR Foundation 继续负责帧间平滑跟踪，后续定位用于校正地图对齐。

第一次真机测试时，请站在建图覆盖范围内，让相机看到有纹理、结构稳定且与建图时相符的区域。先缓慢移动设备，让 AR Tracking 稳定，再使用 Snap；单视角定位不稳定时使用 Scan。

你也可以先在 Space Studio 中测试定位，确认地图本身可以定位，再排查 Unity 工程和设备问题。

10. 应用推荐设置并执行预检

在首次构建前完成一次通用配置：

在 Unity 顶部菜单选择 01Spatial > Apply Recommended Project Settings...。新建的空白 URP 工程可以直接采用这些基线；如果把 SDK 嵌入已有产品，先审阅它对项目级 Player/XR Settings 的修改。
在确认窗口中选择 Apply Settings，等待 Unity 完成项目设置与 XR 配置更新。
在 Unity 的 Player Settings 中把模板占位信息替换为自己的产品信息，包括 Company Name、Product Name、应用图标、Android Package Name 和 iOS Bundle Identifier。推荐设置还会把启动画面替换成 01Spatial 品牌画面，正式发布前请在 Player Settings 的 Splash Image 中换成你自己的，或关闭它。
打开并保存当前开发场景。如果你在第 3 节另存了场景，请保持另存后的场景处于打开状态。
选择 01Spatial > Fix Build Blockers... 并确认修复。.unitypackage 无法替宿主工程修改 Build Profiles；这个操作会把当前打开且包含 SpatialClientRuntime 的场景设为第一个启用的 Scene，并为 URP 补齐必需的 AR Background Renderer Feature。
打开 01Spatial > Account，展开 Advanced，选择 Verify Configs in Build Scenes，检查所有构建场景都绑定了正确 Config 和 Map。
选择 01Spatial > Build > Check Android Settings (No Build) 或 Check iOS Settings (No Build)。这两个入口只执行预检、不生成安装包；预检本身只读，Error 必须修复，Warning 是需要确认的产品或发布建议。

推荐设置会建立 Linear Color Space、AR Foundation 自动启动、IL2CPP、Android API 26+/ARM64/ARCore/OpenGLES3，以及 iOS 16+/ARKit 等基线，但不会强制把现有工程切换到某条渲染管线。SDK 的内置材质同时支持 Built-in 与 URP，因此 Built-in 和 URP 都可直接使用。

URP 还要求 Graphics Settings 默认管线及每个质量档所引用管线中的所有 Universal Renderer 都包含 AR Background Renderer Feature；预检会逐个检查，只补移动端质量档不足以通过。缺少它时安装包可以构建成功，但真机只显示黑色背景。预检会以 SPATIAL-E071 阻止这种配置。开始构建时，如果错误属于 Player/XR 设置、Build Profiles 场景顺序或该 URP Feature，Unity 会询问是否选择 Fix and continue 执行一次性修复；也可以随时运行 01Spatial > Fix Build Blockers...。这两个修复入口都会明确修改工程资产，批处理和 CI 不会自动修复。平台签名仍必须使用你自己的身份。

11. 构建 Android 应用

11.1 安装 Android 模块

在 Unity Hub 中找到 Unity 6000.3.19f1，选择 Add modules，确认安装：

Android Build Support
Android SDK & NDK Tools
OpenJDK

11.2 设置 Android 产品信息

在 Unity 中打开 File > Build Profiles。如果列表中没有 Android，先选择 Add Build Profile > Android > Add Build Profile；然后选择该 Profile 并执行 Switch Profile。
在 Player Settings 中设置自己的 Package Name，例如 com.yourcompany.yourarapp。不要发布模板占位值 ai.spatial01.arunity。
设置 Version 和 Bundle Version Code。
确认 Scripting Backend 为 IL2CPP、Target Architectures 包含 ARM64、Minimum API Level 不低于 26。API 26 是 01Spatial 当前验证过的最低 Android 基线。
将 Target API Level 保持为 Automatic (highest installed)，让 Unity 使用本机已安装的最高 Android SDK；发布到 Google Play 前，还要确认本机 SDK 满足商店当时的 Target API 要求。
确认 ARCore 为 Required、Internet Access 为 Require、Graphics APIs 的第一项是 OpenGLES3。推荐设置会把 Graphics APIs 设为只有 OpenGLES3；保留 Vulkan 等其他 API 不会阻断构建，但模板基线只覆盖 GLES3 渲染路径，预检会给出警告。
用于商店发布时，在 Publishing Settings 中配置自己的 Keystore 和 Key Alias。
运行 01Spatial > Build > Check Android Settings (No Build)，修复全部 Error。

11.3 生成测试 APK

选择：

01Spatial > Build > Android APK

成功后输出：

Builds/Android/01SpatialAR.apk

如果当前活动平台不是 Android，这次不会构建，而是分两步走，中间会出现两个弹窗：

先弹出 Switch to Android first，选择 Switch to Android (no build yet) 才会切换平台；选择 Cancel 则既不切换也不构建，只在 Console 留一行日志。
Unity 重新编译完成后再弹出 Android platform is ready，选择 Build now 开始构建；选择 Later 可以稍后自己重新触发构建菜单。

所以切平台后的第一次构建需要点两次，这是正常的。不要在切平台尚未完成时强行构建。

连接启用了 USB 调试的 Android 设备后，可以使用 Android SDK 的 adb 安装测试包：

adb install -r Builds/Android/01SpatialAR.apk

内置菜单生成的是用于本地真机测试的 APK。发布到 Google Play 时，在标准 Android Build Profile 中启用 Build App Bundle (Google Play)，生成 AAB，并使用自己的发布 Keystore 签名。真机还必须是受支持的 ARCore 设备并安装可用的 Google Play Services for AR。

构建脚本采用事务式输出：新构建完整成功后才替换旧 APK；失败时上一次成功产物会保留。因此排查问题时要同时查看 Unity Console 和文件时间，不要把仍存在的旧 APK 当作本次构建成功。

12. 构建 iOS 应用

12.1 准备 macOS 和 Xcode

最终 iOS 应用必须在 macOS 上完成：

在 Unity Hub 给 Unity 6000.3.19f1 安装 iOS Build Support。
安装 Xcode 26.0 或更高版本，并至少启动一次以接受许可和安装组件。当前模板使用 ARKit XR Plugin 6.5；其静态库由 Xcode 26 构建，Unity 官方要求使用 Xcode 26.0 或更高版本。
准备可用于设备签名的 Apple Developer Team。

12.2 设置 iOS 产品信息

打开 File > Build Profiles。如果列表中没有 iOS，先选择 Add Build Profile > iOS > Add Build Profile；然后选择该 Profile 并执行 Switch Profile，等待脚本重新编译完成。
在 Player Settings 中设置唯一的 Bundle Identifier，例如 com.yourcompany.yourarapp。
设置 Version 和非零 Build Number。
确认 Target minimum iOS Version 为 16.0 或更高。这是 01Spatial 已验证的设备基线。
确认 Requires ARKit 已启用、Scripting Backend 为 IL2CPP、Architecture 为 ARM64，并且 Graphics APIs 的第一项是 Metal。
检查 Camera Usage Description，确保文案准确说明应用为什么使用相机。
运行 01Spatial > Build > Check iOS Settings (No Build)，修复全部 Error。01Spatial 预检通过后，Unity 的 ARKit 构建处理器仍会继续核对 Xcode、ARM64 和 Metal，因此不要跳过第 5 步。

12.3 导出 Xcode 工程

选择：

01Spatial > Build > Export iOS Xcode Project

成功后输出目录：

Builds/iOS

如果当前活动平台不是 iOS，第一次选择菜单不会导出，流程与上面的 Android 一致：先在 Switch to iOS first 中选择 Switch to iOS (no build yet) 切换平台，等重新编译完成后再在 iOS platform is ready 中选择 Build now；选择 Cancel 则什么都不会发生。这个两阶段过程保证 Unity ARKit 和模板的 iOS/Swift 后处理器都在正确的脚本域中执行。

12.4 在 Xcode 中签名并安装

用 Xcode 打开 Builds/iOS/Unity-iPhone.xcodeproj。
选择 Unity-iPhone target，在 Signing & Capabilities 中选择你自己的 Team。
确认 Bundle Identifier 与 Unity Player Settings 中一致且全局唯一。
开发测试时可启用 Automatically manage signing；团队有固定 Provisioning Profile 时按内部发布流程选择。
连接支持 ARKit 的 iPhone 或 iPad，解锁并信任开发电脑。首次安装本地开发应用时，如果设备提示需要开发者模式，请在 Settings > Privacy & Security > Developer Mode 中开启并按系统提示重启设备。
在 Xcode 顶部选择 Unity-iPhone scheme 和该真机，然后执行 Build and Run。
用于 TestFlight 或 App Store 时，选择 Any iOS Device (arm64) 或 Xcode 当前版本提供的等效通用设备目标，执行 Product > Archive，再通过 Organizer 完成验证和分发。

模板包含 Assets/Plugins/iOS/PrivacyInfo.xcprivacy 作为基础 Privacy Manifest。添加统计、广告、登录、文件访问或其他第三方 SDK 后，必须根据产品的实际数据使用重新审查并补充，不能把模板基线当作最终隐私声明。

iOS 导出同样采用事务式目录切换：完整成功后才替换 Builds/iOS；失败时可能看到的是上一次成功导出的目录，请以 Unity Console 和导出时间为准。

13. 在模板上继续开发

立方体只是最小示例。继续开发时遵守以下边界，复杂应用仍能保持正确坐标和生命周期：

把自己的 Prefab、脚本和资源放在独立产品目录，例如 Assets/MyProduct/，减少升级 SDK 时的冲突。
固定在真实空间中的内容放在对应 Map 的 Content (Visible When Localized) 下，由模板管理它们在定位成功后的显示。
用自己的 Prefab Variant、View 或 Feature Module 扩展表现，不要直接修改 AR Camera 或把另一个 ARSession/XROrigin 叠进场景。
已有一套 AR Foundation Rig 的产品应使用模板的 Embedded Client 接入方式，让 01Spatial 绑定现有 ARSession、XROrigin 和 AR Camera；不要再创建第二套 Provider。
服务端 Content 与本地 Unity 内容使用同一地图坐标源，可以混合构建导览、导航、多人共享锚点、游戏逻辑或数字孪生界面。
真正发布前，在 iOS 和 Android 各自验证权限、Tracking 恢复、Snap、Scan、Auto、前后台切换、屏幕旋转、弱网、遮挡、温升和长时间漂移校正。

14. 常见问题排查

Account 或 Map 验证失败

检查 Unity 中选的是 CN (China) 还是 EU (Europe)，并与 Portal 和 Map Key 的来源一致。
确认没有把 Project Key 粘贴到 Map Key 输入框。
确认 API Key 所属账号仍有地图权限，且 API Key 没有被重新生成而失效。
确认地图状态为 Ready，而不是离线、构建中或失败。

下载地图后看不到点云或 Mesh

使用 Point Cloud/Mesh 行的眼睛按钮打开显示。
在 Scene 视图按 F 聚焦下载的地图对象。
点云过细时增大 Point Size。
地图没有纹理 Mesh 时先下载 Point Cloud；LiDAR 选项不可用时让服务回退到稀疏点云。

定位成功但看不到内容

确认内容是当前 Active Map 的 Content (Visible When Localized) 的后代。
确认没有把对象放进 Reference Geometry (Editor Only) 或 SDK Content (Generated)。
确认对象的局部位置没有远离下载的地图，Scale 也不是 0。
检查当前 App 使用的 Map Key 是否就是摆放内容时的地图。
如果地图 Origin 改过，重新下载地图并重新检查对象位置。

Snap 和 Scan 按钮不可用

先允许相机权限。
缓慢移动设备，等待 ARKit/ARCore 进入完整 Tracking。
确认只有一套活动的 ARSession、XROrigin 和相机 Provider。
Editor Game 视图不能提供真机 CPU Image，请在设备上测试。

Android 或 iOS 构建没有开始

平台切换会触发 Unity 脚本域重载，因此构建菜单在检测到平台不一致时有意终止当次构建。先确认第一个弹窗里点的是 Switch to <平台> (no build yet) 而不是 Cancel —— 点 Cancel 时平台不会切换，菜单看起来「没反应」，Console 里会有一行说明。切换并重新编译完成后，在第二个弹窗中选择 Build now，或自己再次触发构建菜单。

URP 真机只有黑色背景

确认 Graphics Settings 默认管线及每个质量档所引用管线中的所有 Universal Renderer 都已添加 AR Background Renderer Feature。先运行 01Spatial > Fix Build Blockers...；若自动修复报告无法写入某个 Renderer，再在对应 Universal Renderer 资产中手工选择 Add Renderer Feature > AR Background Renderer Feature，然后重新执行目标平台检查。

导入 `.unitypackage` 后看不到 01Spatial 的完整菜单

这通常表示必需的 Unity 包尚未装齐，所以 01Spatial 程序集暂时没有参与编译。选择 01Spatial > Install Missing Packages，等待 Package Manager 和脚本编译全部结束；若安装失败，再根据 Console 中逐项列出的包名，在 Window > Package Manager 中安装。

仍然无法定位

先用 Space Studio 在同一地点、同一地图上测试。如果 Space Studio 也失败，应检查地图覆盖、环境变化、光照和画面纹理；如果 Space Studio 成功而 Unity 失败，再检查区域、Key、权限、AR Tracking、网络和 Console 日志。更多服务端错误说明见故障排查。