跳转至

Pico Ultra WebXR 调试工作流（实用版）

目标：为 truth-lab (React Three Fiber WebXR) 建立高效的 Pico 调试流程 适用场景：代码在云服务器上，通过 ilmhub.top 访问，本机电脑负责调试

架构概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
┌──────────────────┐      git push       ┌──────────────────────┐
│  本机电脑 (Mac)   │  ──────────────→    │  阿里云 ECS 服务器    │
│  ├── 代码编辑器    │                     │  ├── git pull        │
│  ├── adb + Chrome │                     │  ├── npm run build   │
│  └── USB 连 Pico  │                     │  └── nginx 部署      │
└────────┬─────────┘                     └──────────┬───────────┘
         │ USB 调试                                 │ ilmhub.top
         ▼                                          ▼
┌──────────────────┐                     ┌──────────────────────┐
│  Pico Ultra      │                     │  Pico 浏览器          │
│  ├── USB 调试开启  │  ← 只需做一次       │  https://ilmhub.top  │
│  └── USB 线连电脑  │                     │  /truth-lab/         │
└──────────────────┘                     └──────────────────────┘

你需要做的

第 0 步：Pico 上开启 USB 调试（只需一次）

  1. Pico 设置 → 通用 → 开发者选项
  2. 没看到？去"关于本机"连续点击版本号 7 次解锁
  3. 开启 USB 调试
  4. ✅ 之后不用再碰 Pico 的任何设置

Pico 浏览器不需要任何配置，直接访问 https://ilmhub.top/truth-lab/ 即可

第 1 步：本机安装 adb

Mac: 

1
brew install android-platform-tools

Windows: 下载 Android SDK Platform Tools → 解压 → 把 adb.exe 所在目录加到 PATH

验证： 

1
2
adb --version
# 应看到: Android Debug Bridge version 1.0.xx

第 2 步：连接 Pico

  1. USB 线连 Pico 到本机电脑
  2. Pico 上弹出"允许 USB 调试？" → 点 允许（勾选"始终允许"）
  3. 本机验证： 
    1
2
    adb devices
# 应看到: xxxxxxxxxxxxxx    device

第 3 步：在 Pico 上打开 truth-lab

戴上 Pico，打开浏览器 → https://ilmhub.top/truth-lab/ → 点击 🎮 进入 VR

第 4 步：在本机开启远程调试

1
2
3
4
5
# 转发 Pico 浏览器调试端口
adb forward tcp:9222 localabstract:chrome_devtools_remote

# 打开 Chrome → 地址栏输入
chrome://inspect

你应该能看到 ilmhub.top 的页面列表。点击下方的 inspect → 完整的 Chrome DevTools 弹出来：

面板 能做什么
Console 看 JS 报错、console.log、手动执行命令
Sources 查看源码、断点调试
Network 看请求/响应
Performance 性能分析

第 5 步：调试 WebXR 常用命令

在 DevTools Console 中可以直接操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// 检查 WebXR 是否支持
navigator.xr.isSessionSupported('immersive-vr').then(console.log)

// 查看手柄输入
navigator.xr.requestSession('immersive-vr').then(session => {
  session.addEventListener('inputsourceschange', e => {
    console.log('手柄:', e.session.inputSources)
  })
})

// 查看渲染帧率（在 useFrame 中打 log）

无线调试（可选，不用 USB）

1
2
3
4
5
6
7
8
9
# 第 1 次：USB 连一次，开启无线
adb tcpip 5555

# 拔掉 USB
adb connect <PICO_IP地址>:5555

# 然后同样
adb forward tcp:9222 localabstract:chrome_devtools_remote
# Chrome → chrome://inspect

⚠️ Pico 重启后无线模式会失效，需要重新 USB→tcpip

完整开发工作流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
1. 本机改代码 → git push

2. SSH 到服务器：
   git pull
   npm run build
   rsync -avz --delete dist/ ~/truth-lab-dist/

3. 戴 Pico → 刷新 ilmhub.top

4. 需要调试：
   连 USB → adb forward tcp:9222 ...
        → Chrome → chrome://inspect

构建加速

当前 npm run build 包含 tsc -b（类型检查），最慢的是这一步。 可以在服务器上创建快速构建脚本：

1
2
3
4
5
# 快速构建（跳过 tsc，仅转译+打包）~5 秒
npm run build:fast

# 完整构建（含类型检查）提交前跑一次
npm run build:full

Pico Ultra 控制器关键信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// 按钮映射
// gamepad.buttons[0] = 扳机 Trigger (0~1 模拟值)
// gamepad.buttons[1] = 握持 Grip (0~1)
// gamepad.buttons[2] = 摇杆按下
// gamepad.buttons[3] = X/A
// gamepad.buttons[4] = Y/B
// gamepad.buttons[5] = 菜单

// 摇杆
// gamepad.axes[0] = X 轴 (-1~1)
// gamepad.axes[1] = Y 轴 (-1~1)

注意事项

场景 说明
自签名证书警告 WebXR 需要 HTTPS，ilmhub.top 已有合法证书 ✅ 无需处理
HMR Pico 上无 HMR，每次改代码需服务器构建后刷新页面
构建耗时 主要瓶颈在 tsc -b，可拆成快速版
ADB 失效 检查 USB 线、Pico 授权、adb devices 是否显示 device