JSAR 空间应用开发新人指南：从环境搭建到跨场景应用落地

前言

在空间计算飞速发展的当下，Web开发者想要切入AR应用开发往往面临“技术栈不匹配”“硬件依赖重”等难题。而JSAR作为可嵌入空间的Web运行时，以JavaScript/TypeScript为核心，让熟悉Web技术的开发者不需要学习全新引擎，就能快速开发出可交互的空间小程序。本文将从JSAR新人小白开发角度出发，记录JSAR应用开发的操作流程，从环境配置到项目部署，再到实战案例，帮助我们学习JSAR空间应用开发。

一、认识JSAR

1. 什么是 JSAR

JSAR 是可嵌入空间的 Web 运行时，核心能力是让开发者用 Web 技术（JavaScript/TypeScript、HTML 思想的 XSML）开发能嵌入到空间场景中的小程序。它就像空间版的前端框架，把 3D 场景开发、空间交互等复杂能力封装成 Web 开发者熟悉的 API，降低空间应用开发门槛。

2. 为什么选 JSAR

• 技术友好：支持 Web-standard APIs 和 TypeScript，Web 开发者可无缝迁移技能。
• 场景灵活：兼容 Babylon.js 做 3D 场景开发，支持在 VS Code 内完成全流程开发，还能嵌入 Unity 场景运行。
• 安全高效：保证空间组件隔离运行，互不干扰；优化离线体验和性能，打破“Web 技术做 3D 性能差”的刻板印象。

3. JSAR应用开发需求

二、环境搭建配置

JSAR 开发依赖 3 个核心工具：Visual Studio Code、Node.js、JSAR DevTools，全程“傻瓜式操作”，新手小白也能 10 分钟内搞定。

1. 安装 Visual Studio Code

• 要求：版本 ≥ 1.80.0（低版本可能不兼容插件）。
• 下载地址：Visual Studio Code - Code Editing. Redefined
• 推荐插件：除后续安装的 JSAR DevTools 外，可额外安装“TypeScript 扩展”“Babylon.js Debug Tools”，提升编码和调试效率。

2. 安装 Node.js

• 要求：版本 ≥ 18.0.0（推荐 LTS 版本，稳定性更高）。
• 下载地址：Node.js — Run JavaScript Everywhere
• 验证安装：打开终端输入以下命令，能正常显示版本号即成功：

node -v # 示例输出：v20.10.0 npm -v # 示例输出：10.2.3

3. 安装 JSAR DevTools（核心插件）

提供两种安装方式，任选其一即可：

VS Code安装

1. 打开 VS Code，点击左侧“扩展”图标（或按 Ctrl+Shift+X）。
2. 在搜索框输入“JSAR DevTools”，找到由“Rokid MCreativeLab”开发的插件。
3. 点击“安装”，等待插件自动下载并启用（右下角会提示“安装成功”）。

安装成功：

三、NPM 本地项目创建

JSAR 支持本地创建和 GitHub 模板创建，满足个人开发和团队协作不同需求。对于个人开发者来说我选择NPM命令本地创建。

NPM 命令本地创建（推荐个人开发）

通过一行命令即可拉取模板并初始化项目，步骤如下：

1. 打开 VS Code 终端（Ctrl+`，输入以下命令创建项目：

npm init @yodaos-jsar/widget my-first-jsar-app # my-first-jsar-app 是项目名，可自定义`

如果执行之后出现以下报错信息的，说明缺少Node.js 文件，需要下载配置node.js

环境变量。

PS C:\Users\28453> npm init @yodaos-jsar/widget my-first-jsar-app npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。 所在位置 行:1 字符: 1 + CategoryInfo : ObjectNotFound: (npm:String) , CommandNotFoundException + FullyQualifiedErrorId : CommandNotFoundException

1. 安装 Node.js

访问 Node.js 官网：[https://nodejs.org/](ttps://nodejs.org/) - 下载 **LTS 版本**（推荐，稳定性更高），根据你的系统（Windows）选择 64 位或 32 位安装包。

- 运行安装包，勾选 **"Add to PATH"** 选项（关键步骤，自动配置环境变量），然后按默认步骤完成安装。如果忘记了勾选，需要在系统环境变量中进行手动配置。

js安装完成之后，检查npm和node

1. 按终端提示输入项目描述、作者等信息（也可直接按回车使用默认值），工具会自动下载模板并生成 package.json。

1. 进入项目目录并安装依赖：

cd my-first-jsar-app # 进入项目文件夹 npm install # 安装类型定义等依赖，支持代码补全和类型检查

3. 项目核心结构解析

初始化后的项目结构清晰，核心文件如下（以 NPM 创建的项目为例）：

其中，main.xsml 是空间场景的“入口”，类似前端项目的 index.html，示例代码如下：

四、项目运行与调试：3 种方式覆盖不同场景

JSAR 支持在 VS Code、Web 浏览器、Rokid AR 设备中运行项目，我们可以根据开发阶段选择合适的方式。我这里选择的是vs Code内运行。

VS Code 内运行

适合编写代码时实时预览效果，步骤如下：

1. 在 VS Code 中打开项目的 main.xsml 文件。
2. 选中 main.xsml 的标签页，右上角会出现“打开场景视图”按钮（类似眼睛图标），点击该按钮。
3. 此时会弹出“Scene View”窗口，自动加载场景中的 3D 模型和交互逻辑。

- 如需重置模型位置，点击场景视图中的“重置”按钮（回到原点）。 - 修改代码后，场景视图会**自动刷新**，无需手动重启服务。

五、项目打包与发布：生成可部署的 .idp 文件

开发调试完成后，需将项目打包成 JSAR 专用的 .idp 格式，用于发布到应用市场或真机部署。

1. 打包步骤

1. 在 VS Code 中右键点击项目文件夹的空白处，选择“JSAR: Package”。
2. 工具会自动压缩项目资源（模型、脚本、图标等），生成

- 注意：当前 JSAR 要求打包后的文件**小于 10MB**，若超过会提示失败。 - 解决方案：用 [gltf-transform](https://gltf-transform.dev/) 工具压缩 3D 模型，或删除冗余资源。

.idp 是 JSAR 的专属打包格式，全称“Interactive Digital Product”（交互式数字产品），本质是一个压缩包，包含应用运行所需的所有资源（模型、脚本、配置文件等）。它的核心优势是“跨场景复用”——同一个 .idp 文件，可嵌入到不同的空间场景中运行，无需重复开发。

六、开发实践：开发一个可交互的 3D 时钟小程序

通过一个简单案例，来理解 JSAR 应用的开发逻辑，实现“点击时钟切换样式”的交互效果。

1. 准备工作

• 3D 模型：准备两个不同样式的时钟模型（glb 格式），放入项目的 model/ 文件夹，命名为 clock-style1.glb 和 clock-style2.glb。

• 核心需求：加载默认时钟模型，点击模型时切换为另一种样式。

2. 编写代码

步骤 1：修改 main.xsml（定义场景）

步骤 2：编写 main.ts（实现交互逻辑）

3. 运行与验证

1. 按前文“VS Code 内运行”的方式打开场景视图，能看到默认的时钟模型。
2. 点击模型，会立即切换为另一种样式，再次点击则切换回来，交互逻辑生效。

1. 打包项目：右键选择“JSAR: Package”，生成 .idp 文件后，可安装到 AR 设备上体验真实空间中的点击交互。由于刚学习，没有结合硬件设备使用，感兴趣的大家可以自行去体验

七、使用体验总结与建议

1. 新手友好的核心优势

• Web 开发者无需学习 Unity、Unreal 等引擎，用 JavaScript/TypeScript 就能开发 3D 空间应用。
• 代码补全、实时预览，JSAR DevTools 覆盖全开发流程，减少“配置折腾”时间。

2. 建议

• 3D 场景深化：学习 Babylon.js 与 JSAR 结合，实现更复杂的场景（如光照、动画、物理碰撞）。
• 多模态交互：集成手势、语音控制（需配合 YodaOS-Master 系统 API），提升用户体验。
• 跨设备适配：利用 JSAR 的多平台支持，开发的同时能兼容 AR 眼镜、PC 浏览器的应用。

总结

通过实践使用，JSAR 对开发者来说，它让我们的开发变得方便许多，也能很快速上手，能让我们体验到进行空间应用的开发，不需要重构技术栈，就能用熟悉的工具和语言，将可以开发出一个可交互的 3D 空间小程序。如果感兴趣的开发者们可以尝试开发使用，上手试一试，会发现不一样的惊喜。期待更多开发者用 JSAR 打造出丰富的空间应用，共同完善空间计算生态！也期待JSAR能不断更新优化，带来更多的惊喜！