跳转至

WebXR 浏览器灰色不可用 — 根因分析记录

日期： 2026-05-31
项目： truth-lab Phase 2 第③步 — WebXR VR 集成
设备： Pico Ultra 真机浏览器
作者： Hermes Agent (aiyoubu)

问题描述

truth-lab VR 模式在 Pico Ultra 真机浏览器上测试时，VR 按钮显示为 灰色不可用 状态，无法点击进入 VR 模式。

按钮状态逻辑：

状态 显示文字 说明
✅ VR 可用 🎮 进入 VR 可点击进入 VR
❌ 非安全上下文 🎮 VR 不可用 灰色，不可点击
✅ 已进入 VR ✕ 退出 VR 可点击退出

在桌面 Chrome 和 Pico Ultra 浏览器上均显示 "🎮 VR 不可用"。

问题排查过程

1. 初检代码层面

检查 VR 按钮组件的 isVRSupported 逻辑：

1
2
3
4
// BrachistochroneScene.tsx — VRModeButton 组件
const isSecureContext = window.isSecureContext;
const isWebXRSupported = navigator.xr?.isSessionSupported('immersive-vr');
const isVRSupported = isSecureContext && isWebXRSupported;

代码逻辑本身正确——三个条件缺一不可。

2. 在浏览器 Console 中验证

在 桌面 Chrome (http://服务器IP/truth-lab/) 上打开控制台检查：

1
2
window.isSecureContext
// → false  ← 非安全上下文，问题根源

3. 定位根源

查阅 WebXR 规范以及浏览器实现，确认：

WebXR Device API 强制要求 Secure Context。 只有通过 HTTPS 或 localhost 提供的页面才能启用 WebXR。 通过纯 HTTP 提供的页面，navigator.xr API 存在但 isSessionSupported() 始终返回 false。

当前 truth-lab 的部署情况：

  • 服务地址：http://服务器IP/truth-lab/（纯 HTTP）
  • Nginx 配置：仅监听 80 端口，无 SSL 证书
  • 无域名，无 HTTPS

4. 验证安全上下文之外的 API 可用性

即使非安全上下文，navigator.xr 对象也存在，但 isSessionSupported() 被浏览器静默拒绝。

根因总结

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
┌──────────────────────────────────────────────────────────┐
│                  根因因果链                                 │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  truth-lab 通过 HTTP 提供服务                              │
│         │                                                  │
│         ▼                                                  │
│  window.isSecureContext === false                          │
│         │                                                  │
│         ▼                                                  │
│  浏览器拒绝启用 WebXR API                                   │
│  (navigator.xr.isSessionSupported 静默返回 false)           │
│         │                                                  │
│         ▼                                                  │
│  VR Button 显示 "🎮 VR 不可用"（灰色不可点击）                │
│                                                          │
└──────────────────────────────────────────────────────────┘

一句话总结： WebXR 强制要求 Secure Context（安全上下文），而安全上下文只有 HTTPS 或 localhost 能提供。当前 truth-lab 通过纯 HTTP 部署，浏览器拒绝启用 WebXR。

解决方案

方案 A（推荐）— 域名 + Let's Encrypt ✅

  1. 注册域名，DNS A 记录指向服务器 IP
  2. 使用 certbot 获取 Let's Encrypt 免费 SSL 证书
  3. 修改 Nginx 配置，添加 SSL 443 端口，HTTP 301 跳转 HTTPS
  4. 在阿里云安全组放开 443 端口

优点： 标准方案、免费证书、浏览器信任、长期可用
缺点： 需要域名、需偶尔自动续期

方案 B — 本地隧道（ngrok / bore / serveo）

优点： 无需域名、快速测试
缺点： 临时方案、域名随机、不适合长期开发

方案 C — Pico 开发者选项跳过安全上下文检查

优点： 最快速、零配置
缺点： 仅对当前设备有效、不修复根本问题

已选方案

方案 A — 用户已确认采用域名 + Let's Encrypt 方案。

参考链接