当前位置：首页 > news >正文

基于 MacOS 的Rokid 开发本地环境搭建指南

news 2025/10/8 5:23:34

Rokid 官网东西很多，系统、设备、SDK 一应俱全，但入口分散、名词偏多，新手很容易迷路。我们这篇文章把路径画清，告诉你整个系统的结构，以及你作为开发者应该如何选择。

一、系统、SDK、设备到底怎么配合

很多开发者一打开文档就会迷糊，因为同一个页面里会同时出现 CXR-M、CXR-S、YodaOS-Sprite、YodaOS-Master、UXR2.0、Station 2、Max 2、AR Spatial 这些名字。

为了不在一开始就掉进“名词泥潭”，我们先把这张地图摊开，然后一句一句把“谁负责什么、谁和谁配合、你该先装什么”讲清楚。等你把这张地图装进脑子里，后面的环境搭建、示例工程和真机验证都会顺得多。首先你可以把 Rokid 的世界简单分成“三层”，这三层分别是“系统层”、“开发包层”和“设备与宿主层”。

系统层决定应用形态和底层能力，开发包层提供编程接口和工具链，设备与宿主层决定算力在哪里、显示在哪里、交互在哪里。

1. 系统层

在系统层，Rokid 主要有两条线索。

第一条线索是 YodaOS-Sprite，它更偏向“全天候佩戴”的眼镜系统，这条线强调的是把手机和眼镜之间的连接打稳、把数据通道打通、把音视频链路接顺。

围绕这条线，官方明确把手机侧的 CXR-M 定义为“伴随与控制”的开发包，也就是说你在手机里做 UI、做转写、做控制，然后通过稳定的连接把能力喂给眼镜端使用。与此同时，Sprite 侧还提供了眼镜端的 CXR-S，让你可以直接访问眼镜上的数据通道，并且把自定义命令通过这条通道回传给手机侧的 CXR-M。你可以把它理解成“眼镜端的小搭档”，它和手机侧的 CXR-M 是一对互相握手的伙伴。

第二条线索是 YodaOS-Master，它是偏“空间计算”的系统底座，它把应用形态明确地分成三类，也就是“桌面应用、空间应用、空间小程序”。

这个分类不是为了好看，这个分类直接影响到你应该怎么设计窗口、怎么放置 3D 内容、怎么处理交互事件。

比如你要做真正的 3D 场景和空间交互，你就会走“空间应用”这条路径；如果你的能力更像一个传统窗口里的工具，你就会走“桌面应用”的路线；如果你要做轻量的场景化能力，你就会看“小程序”的约束和分发。把这个分类先记住，后面你在选 SDK 和示例工程时就不会跑偏。

2.开发包层

接下来我们说“开发包层”，也就是你真正在项目里要引的那些 SDK。

第一位是 CXR-M，它是跑在手机端的开发包，职责非常清楚，就是帮你把“手机↔眼镜”的连接、控制和数据通道做稳定。只要你打算让手机当“大脑”，你基本都会先装它。这里面最关键的点是“稳定连接”和“数据通信”，因为你要在手机里做的 UI、翻译、字幕、看板、控制都需要走这条链路。

第二位是 CXR-S，它是跑在 Sprite 设备上的开发包，作用是让眼镜端可以直接访问数据通道，并且把“自定义命令”从眼镜侧发回到手机侧的 CXR-M。这个能力意味着你可以在眼镜端做一小段定制逻辑，然后通过通道和手机侧配合，从而把整体体验拆成“眼镜端轻逻辑 + 手机端重逻辑”的结构，这样一来你既不把眼镜端做得太重，也不把手机端做得太盲。

第三位是 UXR3.0，它是给 Unity 开发者准备的空间开发工具包，它把位姿跟踪、手势等空间能力打了一个完整的工程化“壳”，让你可以像写普通 Unity 工程那样去搭场景、挂脚本、连交互。只要你在做真正的 3D 场景和空间交互，这个包就是你的主战场。

你可以先在编辑器里用虚拟相机和输入桩把交互跑通，随后再把 UXR3.0 的相机与输入预制体接进来，最后再跑到目标设备去做真机验证。

目前官方也同时支持 UXR2.0，它们的区别在于支持的 Unity 的版本不同，大家可以根据自己的情况选择对应的版本。

3.设备与宿主层

然后我们看“设备与宿主层”。在这层里面，眼镜本体比如 Max 2 或 AR Spatial 负责把画面显示在你眼前，同时承担一部分传感和交互；而“算力宿主”可以是手机，也可以是 Station 2。

假如你选择手机当宿主，你会把 CXR-M 放在手机里运行，然后通过稳定的通道把音视频、字幕、控制这类能力交给眼镜；这个结构很适合做“伴随型”的应用，比如同传字幕、提词器、仪表盘之类。

如果你选择 Station 2 当宿主，你更像是在用一台“掌上计算单元”去驱动眼镜，官方已经把阅读、剧院、运动等模式做成了现成的系统能力，同时提供了“射线交互”和多窗口布局这些现成的交互策略。这个选择的好处是你可以直接对齐这些模式去做 UI 适配，而且你在多屏和稳定视角上的工程量会小很多；与此同时，官方也会对 3D 内容、流媒体和 DRM 的组合做一些系统级的处理，这些处理让消费级体验更可控，你在写文档和做演示的时候更容易复现。

4.开发路径

当你把“三层”和“三个 SDK”摆在一起看，你会发现有两条非常自然的开发路径。

第一条路径是“手机为主”的伴随控制型路径：你在 macOS 上装好 Android Studio 和工具链，你先把 CXR-M 的最小示例工程跑起来，再用一个本地的 mock 当“眼镜端”去打通握手、心跳和指令往返；等你接上真实设备，你把传输层指向硬件，整条链路就能顺着跑，这条路径从第一天起就能产出可运行的 Demo。

第二条路径是“空间应用为主”的 Unity 路径：你在 macOS 上装好 Unity LTS 和 Android 打包组件，你在编辑器里先用虚拟位姿源和输入桩把交互打通，再把 UXR3.0 的相机与输入接进来，最后你打一个 Android 包去真机冒烟。因为 UXR3.0 就是为 Unity 开发者准备的空间工具包，所以这条路径从工程结构到调试手感都会更贴近 3D 应用开发的日常。

如果你现在在想“我到底先装哪一套”，你可以先用一个很务实的判断方式。你如果要把手机侧的字幕、翻译、笔记、远程控制这些能力变成“戴上就能用的小助手”，你就先走 CXR-M 的伴随路径；你如果要把 3D 物体、射线点击、空间锚定这些交互变成“真空间里的应用”，你就先走 UXR2.0 的 Unity 路径；你如果希望“开箱就是一台随身工作站”，而且你要演示多屏、阅读、剧院或运动场景，那么你可以优先把 Station 2 作为宿主，这样在系统模式、窗口管理和射线交互上你会省掉很多工程工作。

在“手机↔眼镜”的这条线上，CXR-M 和 CXR-S 通过数据通道做握手、做命令、做传输，然后把稳定性和时延放在第一优先级；在“空间应用”的这条线上，UXR2.0 把位姿和手势这些底层能力包成了 Unity 开发者“拿来就用”的组件，你把它接进工程就能开始写交互；在“宿主与设备”的这个选择题里，手机更灵活，Station 2 更整合，你根据场景去取舍，整个架构就确定了。

二、环境安装指南——手机为主的伴随控制型

1.明确目标与工具清单

我们这条路径的目标，就是让“手机 ↔ 眼镜”的伴随与控制链路先稳定可用，然后再接入真设备顺畅切换。

官方把这条链路对应的开发包叫做 CXR-M，它负责在手机侧建立稳定连接、做数据通信，并为后续的音视频与场景协同打底；而眼镜这边走的是 YodaOS-Sprite 路线，Sprite 明确要求通过手机侧的 CXR-M 建立稳定连接，这就决定了我们必须先把 Android 开发生态装全，再谈联调与验证。

2.安装 macOS 基座：Xcode 命令行工具（CLT）

你先装好 Xcode 命令行工具，因为很多编译与调试环节依赖它。

最稳的方式就是在“终端”执行系统自带的安装流程（xcode-select --install 会弹出官方安装对话框），装完后你用 xcode-select -p 或 clang --version 之类的命令确认工具已就位；如果你偏好手动下载，你也可以去 Apple Developer 的 Xcode 资源页获取“Command Line Tools”并安装。

xiaoyu@192 ~ % xcode-select --install xcode-select: note: Command line tools are already installed. Use "Software Update" in System Settings or the softwareupdate command line interface to install updates

3.安装 Android Studio 与 Android 15 SDK（API 35）

我们从 Google 官方页面下载安装最新稳定版 Android Studio。https://developer.android.com/studio?hl=zh-cn

首次启动后打开 Preferences → Android SDK。你在 SDK Platforms 勾选 Android 15（API 35）→ Android SDK Platform 35，在 SDK Tools 勾选 Android SDK Build-Tools 35.x.x，并确保 Android SDK Platform-Tools 为最新（这包里包含 adb 等关键工具）。

如果你在公司或校园网络，需要在 HTTP Proxy 里配置代理再执行安装。这样做的目的，是把“平台 + 构建工具 + 调试桥”一次装全，后面构建与设备联机才不掉链子。

4.连接与调试：让 adb 稳定识别你的设备（含 USB 与 Wi-Fi）

你在手机里打开“开发者选项”，开启“USB 调试”，用数据线连接到 Mac，手机上首次会弹出 RSA 指纹确认；你在“终端”执行 adb devices，看到设备状态为 device 就表示链路畅通。若你想减少插线，你也可以按官方流程配对 无线调试，确保电脑与手机在同一网络环境，再用 adb 的 Wi-Fi 连接步骤完成配对与连接。后续如果需要做本机服务联调，adb 还支持端口转发与反向转发，你可以在需要时用到 forward 或 reverse 的能力。

5.获取与安装 CXR-M

CXR-M SDK 采用 Maven 在线分发，官方仓库地址是：

https://maven.rokid.com/repository/maven-public/

你需要在项目根目录下找到 settings.gradle.kts 文件，然后在 dependencyResolutionManagement 里的 repositories 中添加上面这条地址。

官方文档用的是 Kotlin DSL（也就是 .kts 写法），所以建议保持一致，避免后面版本号或路径出现兼容问题。

简单来说，你的配置里要多这一段：

maven { url = uri("https://maven.rokid.com/repository/maven-public/") }

为什么要这么做？因为 Rokid SDK 没放在常规的 Maven Central，而是自己维护的仓库。如果不加这一行，Android Studio 在构建时根本找不到依赖。

仓库地址加好后，就可以在模块的 build.gradle.kts 里导入 SDK。

官方当前版本号是：

implementation("com.rokid.cxr:client-m:1.0.1-20250812.080117-2")

同时要注意，CXR-M SDK 需要 minSdk ≥ 28。你在 defaultConfig 里加一句：

minSdk = 28

这样可以避免编译时报错（因为 SDK 用到了一些 Android 9.0 之后的 API）。

除了主包以外，官方还推荐配套的依赖版本，比如 Retrofit、OkHttp、Gson、Kotlin 标准库等。如果你的项目里已经有这些依赖，但版本不同，建议优先使用 SDK 推荐的版本，否则可能出现方法签名冲突。

三、环境安装指南——空间应用为主的 Unity 路径

这条路子更像你熟悉的 3D 应用开发节奏。

你先把 Unity 的环境装稳，你在编辑器里用“虚拟位姿源＋输入桩”把交互逻辑跑顺，然后你把 UXR3.0 的相机与输入接进来，最后你打一个 Android 包做一次真机冒烟测试。官方把 UXR3.0 定义成面向 Unity 开发者、运行在 YodaOS-Master 上的空间工具包，所以这条链路从结构到调试手感都会很自然。

1.安装 Unity Hub＋LTS 版本

你先装 Unity Hub，然后在 Hub 里装一版 LTS 的编辑器版本；现在 Unity 的长期支持节奏是“Unity 6 LTS”家族和 2023/2022 LTS 存档，你按你的团队规范和 UXR3.0 的兼容建议来选。安装时一定勾上 Android Build Support，同时把 Android SDK & NDK 和 OpenJDK 一起装上，这样你后面不用再手动折腾环境变量。访问地址：

https://unity.com/download（Unity Hub 下载
https://unity.com/releases/editor/archive（历代 LTS 存档与版本对照）
https://docs.unity3d.com/2023.2/Documentation/Manual/android-sdksetup.html（官方说明“Android Build Support＋SDK/NDK/OpenJDK”应随 Hub 一起安装）
https://unity.com/releases/unity-6/support（Unity 6 LTS 支持节奏与更新策略）

2.切到 Android 目标，再配置 Package Manager 的私有源

你把平台切到 Android，这是因为 UXR3.0 的 App 跑在 Android / YodaOS-Master 上。你在 File → Build Settings 里选择 Android，然后点击 Switch Platform。这一步只是一句带过，它不是本节重点，但不切会影响后续校验项。官方接入指南就是这么要求的。

接着你在 Edit → Project Settings → Package Manager 里新增一个 Scoped Registry，用来从 Rokid 的私有 npm 仓库拉包：

Name 随便填一个英文名就行；
URL 填 https://npm.rokid.com/；
Scope(s) 填 com.rokid；保存之后，My Registries 里会出现 Rokid 的条目。Unity 官方文档对 Scoped Registry 的用法与字段解释很清楚，你完全可以对照它来检查。

小提示私有源与 UPM 完全兼容，这是 Unity 官方支持的工作方式；需要鉴权时，按 Unity 的“Scoped registry authentication”说明去配。

3.通过包名安装 Rokid Unity OpenXR Plugin（3.0.3）

你打开 Window → Package Manager，点击左上角 +，选择 Add package by name。你输入：

Package Name 填 com.rokid.xr.unity；
Version 填 3.0.3（不填版本就装最新）。点 Add 之后，UPM 会开始安装 Rokid Unity OpenXR Plugin。这是官方接入指南的推荐路径。

4.首次安装后的两件事：Input System 与 Environment Fix

安装完成后，Unity 会弹出启用 New Input System 的提示框，你直接点 Yes，编辑器会自动重启。Unity 官方文档说明了启用新输入系统时需要重启编辑器，这个提示是正常流程。

编辑器重启后，通常会自动弹出 Rokid OpenXR | Environment Fix 窗口。你直接点 Accept All，让插件一次性把工程里的必备项改好。如果没有自动弹出，你在菜单里找到 Rokid → Env → Project Environment Fix 手动打开即可。这个步骤来自 Rokid 的接入指南，你按它做就行。

5.打开 XR Plug-in Management，启用 OpenXR 与必需特性

你进入 Edit → Project Settings → XR Plug-in Management，在 Android 页签勾选：

Initialize XR on Startup；
OpenXR。这一步是 Unity 的标准 XR 管线开关，官方文档里写得很明确。

你点进左侧的 OpenXR 子项，再完成两组配置：

Enabled Interaction Profiles 里添加 Rokid Controller Profile 与 Rokid HandTracking Profile；
OpenXR Feature Groups 勾选 Hand Tracking Subsystem、Rokid ARFoundation Support、Rokid Hand Tracking Aim、Rokid OpenXR Support。这些勾选项来自 Rokid 接入指南，用来保证手势、控制器与底层能力齐活。

最后你打开 XR Plug-in Management → Project Validation，如果看到提示可以一键 Fix All。有时候 Unity 在内部刷新配置，你点了 Fix 还没完全生效，等几秒再点一次即可。这个“项目校验”是 Unity 官方提供的内置检查面板。

6.版本与命名的小提醒

你在创建或保存项目时，路径、项目名与任意文件夹名都不要用中文、空格或特殊字符，这是 Rokid 接入指南强调的注意点。你在 Player Settings 里按需确认 ARM64、渲染管线与图形 API 等基础项与插件要求一致，避免后期构建才遇到兼容问题。这些习惯做法与 Unity 官方 XR 文档是对齐的。