mcpField
Q
quest-webxr

quest-webxr

github.com/ssheleg开发194 次安装6 天前更新
代码仓库

关于 quest-webxr

面向 Horizon OS 的 WebXR 体验与 PWA 构建指导，帮助 Web 开发者评估网页路线、在头显 Browser 中测试，并处理打包、分发和性能约束。

主要功能

  1. 01WebXR 与 PWA 交付指导
  2. 02Web 3D 框架选择
  3. 03头显 Browser 测试流程
  4. 04通过 Android 工具远程调试
  5. 05使用 Bubblewrap 打包 PWA
  6. 06性能与分发检查

适用场景

  1. 01制作沉浸式 Web 演示
  2. 02在头显中验证网站
  3. 03将 WebXR 网站打包为 PWA
  4. 04评估 Web 性能与交付方式

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ssheleg/xr-dev --skill quest-webxr

安装后在 Claude Code 中输入/quest-webxr确认已加载。

附带文件references/pwa-packaging.mdreferences/runtime-delivery.md

详细介绍

Horizon OS 上的 WebXR 和 PWA

Web 路径以原生性能换取只需执行 git push 即可部署。它适合演示、目录、工具，以及任何还必须在头显之外运行的内容；如果帧预算已经吃紧，则不适合。

请阅读 references/runtime-delivery.md，了解会话／能力协商、普通屏幕回退、资源、托管以及浏览器／PWA 交付检查。

如果要制定完整的产品路线图或进行阶段审计，请使用 quest-lifecycle；单项技术任务仍由此负责人处理。如果该工具不存在，请直接说明当前阶段、相关证据和下一项前置要求。

避免返工的顺序

  1. 先构建网站，并在头显的浏览器中测试。 打包后的 PWA 使用相同的渲染引擎，因此所有兼容性和性能问题都能在打包前发现。
  2. 远程调试——通过 Android 平台工具，从计算机使用 Chrome DevTools 连接设备。浏览器规格页面包含用户代理字符串和支持的内容尺寸。
  3. 页面运行正常后再打包。

像真正的应用一样进入沉浸模式

从头显的应用库启动的 PWA 不应显示 2D 着陆页。页面加载后应立即请求会话：

const supported = await navigator.xr?.isSessionSupported('immersive-vr');
if (supported) {
  const session = await navigator.xr.requestSession('immersive-vr');
  await renderer.xr.setSession(session);          // three.js
}

A-Frame 也会在 renderstart 时通过 scene.enterVR() 执行相同操作。Meta 自己的代码片段会通过 window.getDigitalGoodsService !== undefined 进行判断——已打包的 PWA 中存在此属性，普通浏览器中则不存在——因此用户在笔记本电脑上打开 URL 时，页面仍可正常运行。

选择框架

选择适用场景
IWSDK（npm create @iwsdk@latest）Meta 为屏幕 3D 和沉浸式 WebXR 推荐的路径；提供测试方案（桌面端的 IWER）以及构建／部署指南
three.js已有 three.js 代码库，需要完全控制渲染器
A-Frame声明式场景，最快实现原型

Meta 还为 IWSDK 路径提供了 hz-iwsdk-webxr 技能——IWSDK 专项工作请使用它；此技能负责判断 Web 路径是否合适，并处理打包和分发的衔接。

打包为 PWA

分步说明（包括决定沉浸式 PWA 能否启动的 Digital Asset Links 步骤）：references/pwa-packaging.md。

npm install --global @meta-quest/bubblewrap-cli    # verified at 1.24.1, Node 18+
bubblewrap --version

Bubblewrap 所需的前置条件如下，顺序也请遵循：

  • 网站通过HTTPS提供服务，并具有有效的 Web App Manifest；
  • 在 Developer Dashboard 中创建应用——如果 PWA 使用应用内购买，则需要 Meta Horizon Application ID；
  • 签名密钥，或在 init 期间创建密钥所需的信息；
  • 用于侧载测试且已开启开发者模式的头显。

首次运行时，Bubblewrap 会提示下载匹配的 JDK 和 Android 命令行工具；除非环境已自行管理这些工具，否则请允许下载。初始化 Quest 项目时，它会询问是否包含 Horizon Billing——如果计划使用 IAP，请准备好 Application ID 后再确认，因为之后添加就意味着重新生成项目。

变现和平台功能

WebXR PWA 中的应用内购买通过 Horizon Billing 和 Digital Goods API 实现；成就、排行榜和附加内容的服务器到服务器 API 可在 Web 文档索引中找到。请在打包之前设置好 IAP。

分发

打包后的 PWA 是 Android 软件包，其发布流程与原生构建相同：发布渠道、审核、VRC——请参阅 quest-store；PWA 专属的商店步骤请参考 Meta 的 hz-store-pwa 技能。2D（非沉浸式）PWA 按照一部分 VRC 进行审核，另有一份会触发自动拒绝的权限列表。

性能，实话实说

  • 浏览器有自己的计数器——Web 文档中的绘制调用指标——而 quest-perf 中的原生性能分析器无法查看页面内部。
  • 帧预算与原生应用相同（72 Hz 下为 13.9 ms）；开销却不同。请务必在头显中测量，切勿在桌面浏览器窗口中测量。
  • XRSession 上的 requestAnimationFrame 是帧时钟；如果页面同时运行 DOM 动画，就要付出双倍开销。

阅读位置

index:  https://developers.meta.com/horizon/llmstxt/documentation/web/llms.txt/
page:   https://developers.meta.com/horizon/llmstxt/documentation/web/<slug>.md

有用的 slug：pwa-webxr、pwa-packaging、pwa-overview-gs、browser-specs、 browser-remote-debugging、3d-web、ps-iap、ts-webxr-perf-drawcall。 IWSDK 自己的指南位于 documentation/iwsdk/guides/ 下。

注意事项

  • PWA 内的 2D 落地页会让人觉得应用坏了——请在加载时请求会话。
  • bubblewrap 是 Meta 的分支（@meta-quest/bubblewrap-cli），并非 Google 的软件包；仅此分支包含 Quest 专用提示。
  • 计费是打包时的决定，不是运行时的决定。
  • 在桌面浏览器中测试能验证逻辑，却会误导性能判断。

内容摘自 Meta Web 文档（pwa-webxr、pwa-packaging、3d-web），日期为 2026-09-20；文档中的版本会变动——引用前请重新核对 bubblewrap 和 IWSDK 的版本。

触发词

更多会将请求路由至此处的短语：“Quest 的 PWA” / “Quest 的 PWA”、“A-Frame”、“bubblewrap”、 “头显的 Web 应用清单”、“Quest 上的浏览器” / “头显中的浏览器”、“远程调试头显浏览器” / “调试头显浏览器”、“Web IAP” / “网页购买”。

从 0.4.4 的描述中移至此处：“沉浸式 VR 会话”、“沉浸式会话”、“Quest 上的 three.js”。

评论

支持 Markdown