hz-vr-debug

VR 调试技能

使用 metavr 命令行接口调试 Meta VR、MR 和 Android 应用。本技能涵盖查看应用日志、捕获设备状态、诊断崩溃，以及解决 Meta VR 开发过程中遇到的常见问题。

何时使用本技能

在以下情况中使用本技能：

• 调试在已连接的 Meta VR 设备上运行的应用
• 查看实时或历史应用日志（logcat）
• 捕获 VR/MR 视图的屏幕截图
• 诊断应用崩溃、渲染异常或性能问题
• 调查追踪、控制器、音频或权限问题
• 从设备提取诊断文件以供离线分析

本技能适用于运行 Horizon OS 的 Meta VR Glasses 和 Meta Quest 头显（Quest 2、Quest 3、Quest 3S、Quest Pro）。

前置条件

使用本技能前，请确保满足以下条件：

1. 已安装 metavr CLI -- 在 PATH 上安装独立的 metavr CLI 二进制文件（请参阅 metavr-cli 技能），或使用 npx 按需调用，无需安装：

   metavr --version
   

   metavr 封装了 ADB，并添加了 Meta VR 专用的设备管理、日志查看、屏幕截图捕获和文件管理功能。以下示例使用简写命令 metavr。如果 metavr 不在 PATH 上，可通过 npx -y metavr <args> 调用相同的 CLI（作为 npm 包 metavr 发布）。
2. 通过 USB 连接 Meta VR 设备 -- 使用支持数据传输的 USB-C 线缆（不能仅支持充电）。
3. 已启用开发者模式 -- 必须在手机上的 Meta Horizon 应用中，进入头显设置并开启开发者模式。
4. 已接受 ADB 授权 -- 首次连接时，必须戴上头显并接受“允许 USB 调试”提示。

快速入门工作流

开始调试 Meta VR 应用最快的方法：

# 1. Verify the device is connected and recognized
metavr device list

# 2. List applications currently installed
metavr app list

# 3. View live logs (most recent 100 lines)
metavr log

# 4. Capture a screenshot of the current VR view
metavr capture screenshot

如果 metavr device list 未返回任何设备，请检查 USB 线缆、开发者模式和 ADB 授权。

关键调试命令

设备命令

命令	描述
metavr device list	列出所有已连接的 Meta VR 设备
metavr device info <id>	显示设备型号、OS 版本等信息
metavr device battery	显示电池电量和充电状态
metavr device wake	将设备从睡眠状态唤醒
metavr device reboot	重启设备
metavr device connect <ip>	通过 WiFi 连接设备

日志命令

命令	描述
metavr log	查看最近 100 行日志
metavr log -n 500	查看最近 500 行日志
metavr log --tag Unity	按标签筛选日志
metavr log --level E	按严重级别筛选（V、D、I、W、E、F）
metavr adb logcat	查看完整 logcat，并使用高级筛选选项
metavr adb logcat --follow	持续流式输出日志

应用命令

命令	描述
metavr app list	列出已安装的应用
metavr app info <package>	显示应用的详细信息
metavr app launch <package>	按软件包名称启动应用
metavr app stop <package>	强制停止正在运行的应用
metavr app clear <package>	清除应用数据和缓存
metavr app install <apk>	将 APK 安装到设备上
metavr app uninstall <package>	卸载应用

截图命令

命令	描述
metavr capture screenshot	截取当前 VR/MR 视图的屏幕截图
metavr capture screenshot -o file.png	将屏幕截图保存到指定文件

文件命令

命令	描述
metavr files ls /sdcard/	列出设备上的文件
metavr files pull /sdcard/path/file ./local/	从设备拉取文件
metavr files push ./local/file /sdcard/path/	将文件推送到设备
metavr files rm /sdcard/path/file	删除设备上的文件
metavr files mkdir /sdcard/path/dir	在设备上创建目录

常见调试工作流

典型的调试过程如下：

1. 连接并验证

metavr device list
metavr device info <device_id>

确认设备已被识别，检查操作系统版本，并记录电池电量。电量不足可能导致热降频，进而影响性能测试。

2. 确认应用

metavr app list

找到要调试的应用的软件包名称。软件包名称通常采用 com.company.appname 这种格式。

3. 重现问题并捕获日志

# Start logging before reproducing the issue
metavr adb logcat --follow

戴上头显并重现问题。日志会实时输出到终端。按 Ctrl+C 停止。

4. 捕获视觉状态

# Take a screenshot at the moment of the issue
metavr capture screenshot

5. 分析并诊断

检查捕获的日志，查找错误、警告和崩溃特征。重点关注：

• FATAL EXCEPTION -- 未处理的 Java/Kotlin 异常
• native crash 或 SIGABRT / SIGSEGV -- 原生代码崩溃
• ANR -- 应用无响应（UI 线程冻结）
• OOM 或 OutOfMemoryError -- 内存耗尽

6. 迭代

修改代码、重新构建、部署并再次测试：

metavr app stop com.example.myapp
metavr app launch com.example.myapp
metavr log --tag Unity --level W

症状到诊断决策树

开发者报告问题时，请使用这些决策树系统地诊断根本原因。从报告的症状开始，沿分支逐步排查。

通用的 Android 崩溃、ANR、内存和 logcat 分支适用于所有构建路径。只有在沉浸式 VR 或 MR 应用中，才使用涉及 VrApi、OpenXR 会话、沉浸式帧率、追踪、控制器或空间音频的分支。对于标准 Android 面板应用，请沿用 Android 应用、渲染、布局和输入分支。

应用启动时崩溃

App crashes on launch
├── Does `metavr app launch <pkg>` show "Error: Activity not found"?
│   └── YES → Package name is wrong or app is not installed.
│       Run `metavr app list` to verify the correct package name.
├── Does logcat show `FATAL EXCEPTION` in the first 5 seconds?
│   ├── YES, with `ClassNotFoundException` or `NoClassDefFoundError`
│   │   └── Missing native library or wrong ABI. Check the APK is built for ARM64.
│   │       Run: `metavr adb shell getprop ro.product.cpu.abi` → must show "arm64-v8a"
│   ├── YES, with `SecurityException` or `Permission denied`
│   │   └── Missing manifest permission. Check the logcat message for which permission.
│   │       Common: hand tracking, scene, camera permissions not declared.
│   └── YES, with `NullPointerException` or other Java exception
│       └── Application code bug. Read the stack trace for the failing class and method.
├── Does logcat show `native crash` / `SIGSEGV` / `SIGABRT`?
│   ├── Check if the crash is in a Unity/Unreal library (libunity.so, libUE4.so)
│   │   └── Engine bug or incompatible SDK version. Check Meta XR SDK release notes
│   │       for known issues with your engine version.
│   └── Check if the crash is in your own native code
│       └── Debug with `metavr adb logcat --buffer crash` for the tombstone, then use
│           `addr2line` or `ndk-stack` on the crash address.
└── No crash visible in logs?
    └── Check if the app is being killed by the system.
        Run: `metavr adb logcat --tag ActivityManager --level W`
        Look for "Force stopping" or "Process died" messages. Common cause: OOM killer
        triggered by excessive memory usage on launch.

应用冻结 / ANR（应用无响应）

App freezes or ANR dialog appears
├── Does logcat show "ANR in <package>"?
│   ├── YES, with "Reason: Input dispatching timed out"
│   │   └── The main/UI thread is blocked. Check for:
│   │       - Synchronous network calls on the main thread
│   │       - Large file I/O on the main thread
│   │       - Deadlocks between threads
│   │       Run: `metavr adb shell kill -3 <pid>` to dump thread stacks, then
│   │       `metavr files pull /data/anr/traces.txt ./` to retrieve the ANR trace.
│   └── YES, with "Reason: executing service"
│       └── A background service is taking too long. Check the service implementation.
└── No ANR, but app appears frozen?
    ├── Is the render loop still running? (Check VrApi logs for frame submission)
    │   ├── YES → The app is rendering but not processing input. Check input system.
    │   └── NO → The render thread is blocked or crashed silently.
    │       Check: `metavr adb logcat --tag VrApi` for "FPS" lines stopping.
    └── Is the device overheating?
        Run: `metavr device battery` — if battery temperature > 40°C, thermal
        throttling may have halted the app. Let device cool down and retry.

头显中出现黑屏

Black screen after app launch
├── Is the app actually running?
│   Run: `metavr adb shell pidof <package>` — if empty, app crashed silently.
│   └── Check crash logs: `metavr adb logcat --buffer crash`
├── Is VrApi initialized?
│   Check: `metavr adb logcat --tag VrApi | grep "VrApi" | head -20`
│   ├── No VrApi output → XR session never started. Check OpenXR/OVR initialization code.
│   └── VrApi output exists → Frames are being submitted but may be empty.
│       └── Check: rendering pipeline, camera setup, shader compilation errors.
├── Unity-specific: "Shader compiler" or "Compiling shaders" in logs?
│   └── Shader warmup can cause a black screen for several seconds on first launch.
│       Use shader prewarming/variant preloading to avoid this.
└── Is the correct rendering API being used?
    Check: `metavr adb logcat --tag Unity --level E` for Vulkan/GLES errors.
    Quest requires OpenGL ES 3.0 minimum. Vulkan is preferred on Quest 3.

帧丢失 / 卡顿

App stutters or drops frames
├── Check current FPS:
│   `metavr adb logcat --tag VrApi | grep FPS`
│   ├── FPS consistently below 72 → GPU or CPU bottleneck.
│   │   ├── Check GPU: use Perfetto or OVR Metrics Tool. Look for GPU completion
│   │   │   time > 13.8ms (72Hz) or > 11.1ms (90Hz).
│   │   └── Check CPU: look for game thread or render thread exceeding frame budget.
│   └── FPS mostly stable but periodic drops
│       ├── Check for GC pauses: `metavr adb logcat --tag dalvikvm --level D`
│       │   or `metavr adb logcat --regex "GC_|clamp"` → reduce allocations per frame.
│       ├── Check for thermal throttling: `metavr adb logcat --tag ThermalService --level W`
│       │   → sustained heavy load causes CPU/GPU frequency reduction.
│       └── Check for asset loading on main thread: large textures or models loaded
│           synchronously will cause frame spikes. Use async loading.
└── Only stutters in specific scenes?
    └── Profile that scene. Common causes: too many draw calls (>100), unculled
        off-screen geometry, expensive shaders, excessive overdraw, uncompressed textures.

追踪问题

Controllers or hands not tracking correctly
├── Are controllers paired and connected?
│   `metavr device info <id>` — check controller connection status.
├── Is hand tracking enabled in device settings?
│   Check: Settings > Movement Tracking > Hand and Body Tracking.
├── Does the app request the correct tracking mode?
│   ├── For hand tracking: manifest must include
│   │   `com.oculus.permission.HAND_TRACKING` and
│   │   `com.oculus.handtracking.frequency` set to "HIGH" if needed.
│   └── For controller tracking: ensure the app is not forcing hand-tracking-only mode.
└── Tracking works but is jittery or delayed?
    ├── Check lighting: tracking cameras need adequate, even lighting. Very bright
    │   or very dim environments degrade tracking quality.
    └── Check for occlusion: hands or controllers held outside the tracking camera
        FOV will lose tracking. The camera FOV is approximately 110 degrees.

音频问题

No audio or wrong audio output
├── Is audio playing through the headset speakers?
│   └── Check: Settings > Sound — ensure headset speakers are selected, not Bluetooth.
├── Does the app use spatial audio?
│   ├── Check for FMOD/Wwise initialization errors in logcat.
│   └── Check that audio sources have correct 3D settings and are not muted.
├── Audio is distorted or crackling?
│   └── Audio buffer underruns. Check for CPU overload causing audio thread starvation.
│       Reduce audio complexity or increase buffer size.
└── Audio plays from wrong position?
    └── Check spatial audio source positions match visual object positions.
        Common issue: audio listener not attached to the camera/head transform.

常见注意事项

以下是 Meta VR 开发中特有的常见调试问题。

• Logcat 缓冲区溢出 —— 在 Meta VR 设备上，由于操作系统和其他应用会持续产生输出，logcat 环形缓冲区很快就会填满。如果未在重现问题前开始记录日志，崩溃日志可能已经被清除。请在重现问题前启动 metavr adb logcat --follow。
• USB 线缆质量很重要 —— 许多 USB-C 线缆只能充电，无法传输数据。如果 metavr device list 没有显示任何设备，请先尝试更换线缆，再排查软件问题。Quest 随附的线缆支持数据传输。
• WiFi 调试会断开连接 —— WiFi ADB 连接（metavr device connect <ip>）会在设备进入睡眠后断开。唤醒设备后，必须重新连接。长时间调试时，USB 更可靠。
• 发布版本会移除日志 —— 如果应用使用 android:debuggable="false"（发布版本），部分日志输出会被抑制。排查问题时，请使用调试版本。请勿将可调试版本发布到商店。
• 同一组件存在多个 logcat 标签 —— Unity 会根据脚本后端使用 Unity、il2cpp 和 mono 标签。Unreal 会使用 UE、LogVR 和 LogOnline 标签。请先使用宽泛的筛选条件，再逐步缩小范围。
• OVR Metrics Tool 叠加层冲突 —— OVR Metrics Tool 叠加层可能会干扰应用的渲染或输入。如果应用表现异常，请先停用指标叠加层并重新测试，再提交错误报告。

提示和最佳实践

有效筛选日志

使用严重性筛选器来减少干扰：

# Show only errors
metavr log --level E

# Show warnings and above
metavr log --level W

按标签筛选，以专注于特定子系统：

metavr adb logcat --tag VrApi
metavr adb logcat --tag Unity

使用 metavr adb logcat 的高级筛选器：

# Complex filter expressions
metavr adb logcat --filter "Unity:W ActivityManager:I"

# Regex pattern matching
metavr adb logcat --regex "error|exception"

# Specific log buffer
metavr adb logcat --buffer crash

请参阅 logcat-filtering.md，了解日志筛选技巧的完整指南。

搜索崩溃特征

排查崩溃时，请在日志输出中搜索已知模式：

metavr log | grep -i "fatal\|crash\|exception\|anr"

常见的崩溃相关标签包括 AndroidRuntime、DEBUG 和 libc。

检查权限

许多 Horizon OS 功能需要特定的清单权限。如果某项功能无响应地失效，请检查应用清单是否包含所需权限。常见权限如下：

• com.oculus.permission.HAND_TRACKING —— 手部追踪访问权限
• com.oculus.permission.USE_SCENE —— Scene API 空间数据访问权限
• android.permission.RECORD_AUDIO —— 麦克风访问权限
• android.permission.CAMERA —— 摄像头访问权限（用于混合现实）

性能调试

如果应用出现卡顿或丢帧：

# Check device battery and thermal state
metavr device battery

# Watch for thermal throttling messages in logs
metavr adb logcat --tag ThermalService --level W

# Check VrApi frame timing
metavr adb logcat --tag VrApi | grep FPS

请参阅 common-issues.md，查看已知问题及其解决方案的汇总。

参考资料

技能参考资料

• Logcat 筛选指南 —— 设备日志筛选和解读的详细指南
• 屏幕截图和视频录制 —— 从设备捕获视觉状态
• 常见问题和诊断 —— Meta VR 开发常见问题及解决方案汇总