VR/XR开发调试工作流最佳实践报告¶

import { Canvas } from '@react-three/fiber'
import { OrbitControls, Stats } from '@react-three/drei'
import { XR, useXR } from '@react-three/xr'

function App() {
  // 通过URL参数 ?mode=desktop 或 localStorage 控制
  const isDesktop = new URLSearchParams(window.location.search).get('mode') === 'desktop'

  return (
    <Canvas camera={{ position: [0, 1.6, 3], fov: 70 }}>
      {isDesktop ? (
        <>
          {/* 桌面模式：自由相机控制 */}
          <OrbitControls 
            target={[0, 0.8, 0]}
            makeDefault
            enableDamping
            dampingFactor={0.1}
          />
          {/* 键盘模拟手柄交互 */}
          <DesktopController />
        </>
      ) : (
        <XR>
          <VRExperience />
        </XR>
      )}
      {/* 始终显示 Stats 和 Grid */}
      <Stats />
      <gridHelper args={[10, 10, '#444444', '#222222']} />
      <ambientLight intensity={0.5} />
    </Canvas>
  )
}

import { Stats, Debug, Grid, Environment } from '@react-three/drei'
import { useControls } from 'leva' // lil-gui 的 R3F 接口

function Scene() {
  // 运行时调节物理参数
  const { gravity, friction, restitution } = useControls({
    gravity: { value: -9.8, min: -20, max: 0, step: 0.1 },
    friction: { value: 0.3, min: 0, max: 1, step: 0.01 },
    restitution: { value: 0.5, min: 0, max: 1, step: 0.01 },
  })

  return (
    <>
      <Stats />           {/* 左上角FPS + 帧耗时 */}
      <Grid />             {/* 地面网格 */}
      {/* ... 场景内容 ... */}
    </>
  )
}

# 如果还没有使用 Vite
npm create vite@latest truth-lab -- --template react
# 或对现有项目
npm install vite @vitejs/plugin-react

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',        // 局域网内其他设备可访问
    port: 5173,
    https: false,            // 内网开发不用HTTPS
    hmr: {
      overlay: true          // 错误显示在浏览器上
    }
  }
})

import { useController } from '@react-three/xr'
import { Line } from '@react-three/drei'
import { useRef, useEffect } from 'react'

function DebugControllerRay({ handedness = 'right' }) {
  const controller = useController(handedness)
  const [hitInfo, setHitInfo] = useState(null)

  useEffect(() => {
    if (!controller) return

    const onSelect = (e) => {
      const target = e.target
      console.log(`[${handedness}] Select on:`, target.name || target.type)
      setHitInfo({
        object: target.name || target.type,
        time: Date.now()
      })
    }

    controller.controller.addEventListener('select', onSelect)
    return () => controller.controller.removeEventListener('select', onSelect)
  }, [controller])

  if (!controller) return null

  return (
    <>
      {/* 可视化的射线 */}
      <Line 
        points={[[0, 0, 0], [0, 0, -5]]} 
        color={handedness === 'right' ? '#00ff88' : '#ff8800'}
        lineWidth={2}
        dashed={false}
      />
      {/* 射线末端小球 */}
      <mesh position={[0, 0, -5]}>
        <sphereGeometry args={[0.03, 8, 8]} />
        <meshBasicMaterial color={hitInfo ? '#ff0000' : '#00ff00'} />
      </mesh>
    </>
  )
}

npm install leva

import { useControls } from 'leva'

function PhysicsParams() {
  const params = useControls('Physics', {
    gravity: { value: -9.8, min: -20, max: 0, step: 0.1 },
    initialVelocity: { value: 0, min: 0, max: 20, step: 0.1 },
    trackFriction: { value: 0.02, min: 0, max: 1, step: 0.001 },
    ballMass: { value: 1, min: 0.1, max: 10, step: 0.1 },
    showTrajectory: true,
    showVectors: false,
  })
  return params
}

桌面开发循环（占80%时间）:
  1. 在 localhost:5173 编码
  2. HMR 自动刷新预览
  3. 用 OrbitControls + 键盘模拟操作
  4. 用 leva 面板调参
  5. 用 Stats 监控 FPS
  → 确认：逻辑正确、参数合理、性能达标

桌面WebXR验证（占10%时间）:
  6. 打开 Chrome DevTools Sensors → WebXR Emulation
  7. 验证 XRSession 创建、手柄事件、空间交互
  → 确认：WebXR API 正常工作

真机集中测试（占10%时间）:
  8. 每天下午 3:00-4:00 集中真机测试
     a. 用 adb + chrome://inspect 连接 Pico
     b. 访问 https://ilmhub.top (或内网地址)
     c. 跑预定义的测试清单（见下）
     d. 用 Performance 面板记录性能数据
     e. 有问题截屏/录屏标记，随后统一修复

# 每日真机测试清单
日期: _____

## 功能验证
- [ ] 场景正常加载（无白屏/报错）
- [ ] 左右手柄均能操作
- [ ] 小球沿轨道正常下落
- [ ] 交互反馈（视觉/动画）符合预期

## 性能检查
- [ ] FPS ≥ 72（稳态）
- [ ] 无持续掉帧（无GC卡顿）
- [ ] 内存 < 2GB（Pico浏览器限制）
- [ ] 场景加载时间 < 5秒

## 兼容性
- [ ] 不同观察角度画面正常
- [ ] 手柄射线命中准确
- [ ] 无渲染闪烁/遮挡错误