Related Resources
增强现实/虚拟现实

使用 NVIDIA CloudXR.js 构建和流式传输基于浏览器的 XR 体验

2026年 3月 31日
作者：, 和

为企业用户提供高保真 VR 和 AR 体验通常需要本地应用开发、自定义设备管理和复杂的部署流程。现在，借助新的 JavaScript SDK NVIDIA CloudXR.js，开发者可以将 GPU 渲染的沉浸式内容直接流式传输到标准网络浏览器，无需应用商店、安装或特定设备构建。

NVIDIA CloudXR.js 将 NVIDIA RTX 远程渲染的全部功能引入 Web 平台。这从根本上改变了沉浸式应用的构建和交付方式。NVIDIA CloudXR.js 将企业 XR 的访问权限扩展到本地开发工作流程之外，并扩展到广泛的 Web 开发者社区。

在 NVIDIA Omniverse、机器人远程操作系统或交互式 3D 训练环境中构建数字孪生的开发者现在可以通过 URL 联系使用 XR 头盔的用户。本文将介绍 SDK 架构、其核心 API，以及如何将其连接到 Omniverse、NVIDIA Isaac Lab 和 LÖVR 等服务器应用程序。

如何运行和托管 NVIDIA CloudXR.js 客户端

本节将介绍如何运行和托管 NVIDIA CloudXR.js Web 客户端，包括预备知识和架构概述。

预备知识

要运行和托管基于 CloudXR.js 的 Web 客户端，您需要一台安装了 Node.js v20 或更高版本并安装了 npm 的计算机。查看 NVIDIA CloudXR.js 示例客户端，无需构建 Web 客户端即可试用。您仍需要运行 NVIDIA CloudXR 服务器以及 CloudXR 运行时 和兼容 OpenXR 的应用。预备知识包括：

  • 客户端
    • Node.js v20 npm
    • WebGL2+ WebXR ( Meta Quest Pico)
    • JavaScript/ TypeScript WebGL
    • Meta Quest 2/ 3/ 3s ( OS v79+) Pico 4 Ultra ( Pico OS 15.4.4 U+)
  • 服务器端
    • 运行 NVIDIA CloudXR 运行时的搭载 NVIDIA GPU 的服务器，符合最新要求
    • 兼容 OpenXR 的服务器应用程序，例如 Omniverse、Isaac Lab 或 LÖVR
  • 强烈建议使用延迟小于 20 ms、带宽超过 100 Mbps 的 WiFi 6 或 6E 网络

CloudXR.js 架构

CloudXR.js 使用两层连接模型，将 Web 应用程序托管与 XR 流式传输工作流分离 (图 1) 。

An image showing the architecture and core components for streaming high-fidelity contents from CloudXR Runtime on a server or from cloud to CloudXR.js based web application on an XR headset.
图 1. 用于流式传输高保真空间内容的高级 NVIDIA CloudXR.js 架构

客户端 Web 服务器: 标准的 Node.js 开发服务器 (或任何静态托管解决方案) 通过 HTTP 或 HTTPS 将 Web 应用程序提供给客户端设备。

CloudXR 运行时连接: SDK 建立从浏览器到服务器上运行的 CloudXR 运行时的 WebSocket 连接。此通道承载基于 WebRTC 的视频流、姿态跟踪数据和控制器/ 手动输入。

在服务器端，CloudXR 运行时可与任何兼容 OpenXR 的应用程序配对。它可以捕获渲染的立体帧，使用硬件加速的 AV1、H.265 或 H.264 对其进行编码，并将其流式传输到客户端。客户端对视频进行解码，将其合成到 WebXR 帧缓存中，然后将跟踪数据发送回服务器，从而以每秒高达 120 帧的速度关闭循环。

Web 应用程序本身与框架无关。CloudXR.js 与 Vanilla WebGL、React Three Fiber 或任何其他与 WebXR 兼容的库集成。

安装 SDK

要将 CloudXR.js 添加到项目中，请从 NVIDIA NGC 下载 SDK。然后将其导入到您的项目中。

npm install </path/to/sdk/nvidia-cloudxr-version.tar.gz>

该软件包包含 TypeScript 类型定义，因此 IDE 自动补全和类型检查工作开箱即用。在标准网页上执行此操作。

创建流式传输会话

整个 SDK 表面以单个入口点为中心：createSession。导入它，配置连接和渲染参数，并传递可选的代理回调来处理生命周期事件。以下代码段适用于使用createSessionAPI。

// Basic session creation
const session = createSession({
 serverAddress: '192.168.1.100',
 serverPort: 49100,
 useSecureConnection: false,
 perEyeWidth: 2048,
 perEyeHeight: 1792,
 // from WebGl API
 gl: webglContext,
// from WebXR API
 referenceSpace: xrReferenceSpace
});
// With event delegates
const session = createSession(sessionOptions, {
 onStreamStarted: () => {
   console.info('CloudXR streaming started');
 },
 onStreamStopped: (error) => {
   if (error) {
     console.error('Streaming error:', error);
   } else {
     console.info('Streaming stopped normally');
   }
 }
});
// Connect to CloudXR Runtime
if (session.connect()) {
 console.info('Connection initiated');
}

这个perEyeWidth以及perEyeHeight值 (必须是 16 的倍数) 定义了每只眼睛视图的分辨率。SDK 会自动从这些值中获得完整的流分辨率。

集成渲染循环

连接后，从 WebXR 渲染循环驱动流式传输管道。每帧需要进行两次调用：将当前跟踪状态发送给服务器，然后渲染接收到的帧。

function onXRFrame(time: number, frame: XRFrame) {
  // Send head pose, controllers, and hand tracking to the server
  session.sendTrackingStateToServer(time, frame);
  // Render the streamed frame into the WebXR layer
  session.render(time, frame, xrSession.renderState.baseLayer);
  // Continue the loop
  xrSession.requestAnimationFrame(onXRFrame);
}
xrSession.requestAnimationFrame(onXRFrame);

这个sendTrackingStateToServermethod 会自动捕捉和传输控制器按下按钮、触发值、控制器姿势、手部追踪数据 (在设备支持的情况下) 和查看器的头部姿势。服务器使用这些数据以正确的输入状态从正确的视角渲染下一帧。这个渲染然后将解码视频合成到 XR 显示器中。

探索示例客户端

CloudXR.js 提供了两个示例客户端，它们展示了不同的集成方法。

WebGL 示例

WebGL 示例 (简单/) 提供最小的单文件 TypeScript 实现，可直接与 WebXR 和 WebGL2 API 配合使用。它包括连接配置 UI、浏览器功能检查和简单的渲染循环。这是了解 CloudXR.js 底层工作原理的最快途径。

React 样本

React 示例 (反应/) 演示了使用 React Three Fiber、React Three XR 和 React Three UIKit 的生产式架构。它具有基于组件的会话管理、双 UI 系统 (用于配置的 2D HTML 和用于交互的 3D – VR 面板) 和 WebGL 状态跟踪功能，可防止 React Three Fiber 和 CloudXR 之间的渲染冲突。

这两个示例均支持 Docker 部署以进行快速测试：

# WebGL sample
docker build -t cloudxr-js-sample --build-arg EXAMPLE_NAME=simple .
docker run -d --name cloudxr-js-sample -p 8080:80 -p 8443:443 cloudxr-js-sample
# React sample
docker build -t cloudxr-react-sample --build-arg EXAMPLE_NAME=react .
docker run -d --name cloudxr-react-sample -p 8080:80 -p 8443:443 cloudxr-react-sample

对于使用热重新加载进行本地开发，请安装依赖项并启动开发服务器：

cd simple  # or react
npm install </path/to/sdk/tarball.tar.gz
npm run dev-server

在浏览器中导航至 http://localhost:8080。在台式机上，Immersive Web Emulator Runtime (IWER) 自动加载来模拟 Meta Quest 3，因此您无需使用物理头显设备即可进行开发和测试。

连接到服务器应用程序

CloudXR.js 适用于与 CloudXR 运行时一起运行的任何兼容 OpenXR 的应用。以下三个示例展示了串流内容的广度：NVIDIA Omniverse、NVIDIA Isaac Lab 和 LÖVR。

NVIDIA Omniverse

将高保真 USD 数字孪生场景串流到 XR 头显设备，用于架构演练、设计评审和工业训练。 Omniverse Kit SDK 109.0.2 及更高版本包含集成的 CloudXR WebRTC 运行时，因此串流工作流直接内置于平台中。操作员使用手部追踪与 3D 内容进行交互，以便在流式传输环境中进行直接操作。

NVIDIA Isaac Lab

为灵巧的机器人构建远程操作工作流。佩戴 Quest 2/ 3/ 3 或 Pico 4 Ultra 的操作员可以看到机器人仿真的实时立体渲染，并使用手部追踪来控制机器人。Isaac Lab 在 Linux 上运行，并配备 Docker 和 NVIDIA Container Toolkit，支持双 GPU 配置以更大限度地提高性能。有关详细信息，请参阅设置 CloudXR 远程操作。

LÖVR

LÖVR 是一种基于 Lua 的轻量级开源 VR 框架，提供了通往可运行服务器的简单路径。使用 --webrtc 标志启动 LÖVR，并连接 CloudXR.js 客户端。这是快速原型设计和测试客户端设置的理想选择。访问 NVIDIA/cloudxr-lovr-sample 上 GitHub 开始使用。

配置面向生产的网络

对于生产部署或 HTTPS 托管，设置具有 TLS 终止的 WebSocket 代理。CloudXR.js 包含一个基于 Docker 的 HAProxy 配置示例，可自动处理此问题：

cd proxy
docker build -t cloudxr-wss-proxy .
docker run -d --name wss-proxy --network host \
  -e BACKEND_HOST=localhost \
  -e BACKEND_PORT=49100 \
  -e PROXY_PORT=48322 \
  cloudxr-wss-proxy

代理生成自签名证书，在端口 49100 上连接到 CloudXR Runtime，并在端口 48322 上侦听安全 WebSocket 连接。对于企业 Kubernetes 部署，SDK 文档包括 NGINX Ingress 配置，该配置支持多个具有负载均衡功能的 CloudXR 服务器。

确保您的防火墙允许 TCP 端口 49100 (信令) 、UDP 端口 47998 (媒体流) 和 TCP 端口 48322 ( WSS 代理，如果使用 HTTPS) 。

开始使用 CloudXR.js

NVIDIA CloudXR.js 将企业 XR 串流引入 Web 平台，即通过 URL 提供 GPU 渲染的沉浸式内容，无需原生应用。该 SDK 提供简洁、精简的 API，可与任何兼容 WebXR 的框架集成，并支持从 Omniverse 数字孪生到 Isaac Lab 机器人远程操作的多个服务器应用程序。它包括生产部署所需的网络和性能工具。

通过为每个 Web 开发者提供构建和交付沉浸式体验的工具，而无需原生 XR 开发的开销，CloudXR.js 使全新类别的应用成为可能。我们很高兴看到开发者社区使用这款新 SDK 构建的内容。

下载 CloudXR.js 并试用 示例客户端。要获得有效演示的最快途径，请从 LÖVR 示例服务器 和 WebGL 客户端开始。如需完整的 API 参考、配置指南和部署文档，请访问 CloudXR.js SDK 文档。

标签

增强现实/虚拟现实 | 开发工具与技巧 | 机器人 | CloudXR | 工业数字化/ 数字孪生

关于作者

Yanzi Zhu 是 NVIDIA 的首席软件工程师兼经理，处于构建新一代空间计算基础设施的前沿。他的团队正在设计现代沉浸式技术的支柱，使机器人和 AI 能够流式传输、感知物理世界并与之交互，使人类能够沉浸在数字世界中。他的专业知识植根于流框架、传感器数据工作流和云系统，为工业应用的数据捕获和沉浸式体验提供支持。此前，他曾在 Google 领导基于 Kubernetes 的分布式基础架构团队。
William Cannady 是 NVIDIA enterprise XR 团队的技术产品经理。他专注于 XR 产品的技术方面，与合作伙伴和客户密切合作。
Gareth Morgan 拥有超过 25 年的图形、渲染和混合现实开发经验。自 2024 年以来，他一直在构建 NVIDIA 空间计算平台，并探索该技术的新前沿。在此之前，他曾在 Autodesk、Activision 和 SiliconGraphics 等公司工作。