排查视觉问题

使用结构化检查清单和决策树，在 Unity 中修复 Vision 发布失败、黑屏流、权限错误和平台特定问题。

请按从上到下的顺序阅读本页。大多数 Vision 故障都可归入四类之一：连接配置错误、帧源故障、平台特定限制，或 WebGL 来源策略。

快速检查清单

在深入处理具体问题之前，请按顺序确认以下五项：

1

确认 Connection Type 为 Video

选择 ConvaiRoomManager 在 Hierarchy 中。确认 连接类型 被设置为 视频. ConvaiVisionPublisher 当 Connection Type 为 音频 时会完全保持空闲——它会记录一条消息并无错误返回。

2

确认房间已连接

ConvaiVisionPublisher 在房间连接之前不会发布。请在 Console 中查看 [ConvaiRoomManager] 连接日志。确认 ConvaiManager.ActiveManager 在运行时不为 null。

3

确认存在帧源

在原生平台（非 WebGL）上， ConvaiVisionPublisher 需要一个帧源。确认 CameraVisionFrameSource, WebcamVisionFrameSource，或自定义的 IVisionFrameSource 位于同一个 GameObject 或其子对象上。请在 Console 中查看：

[ConvaiVisionPublisher] 未找到 IVisionFrameSource。

4

确认帧源处于 Ready 状态

在运行时在 Inspector 中打开帧源组件。确认 State 为 就绪。如果它是 失败之前，检查 ErrorKind 是位于 StatusMessage ，请在 Inspector 或 Console 中查看。

5

将 VisionDebugPreview 添加到任意场景 GameObject。

添加 VisionDebugPreview 按 Play。若覆盖层显示实时图像且 FPS > 0，说明视频流已到达发布器。如果覆盖层为空白或 FPS 始终为零，则帧源没有生成帧——继续查看 帧源问题 下文。

常见问题

症状	可能原因	修复
IsPublishing 保持 false	Connection Type 为 音频	设置 连接类型 到 视频 on ConvaiRoomManager.
IsPublishing 保持 false	房间未连接	等待连接或检查 API 密钥/网络。
IsPublishing 保持 false	未找到帧源	添加 CameraVisionFrameSource 到同一个或子 GameObject 上。
调试覆盖层空白，FPS = 0	帧源处于 失败 状态	检查 ErrorKind ——参见 帧源问题.
视频流为黑屏	错误的 CameraCaptureMode 用于渲染管线	请参见 黑屏视频流.
SrpNative 已选择	未实现的后端	CameraVisionFrameSource 进入 失败 会立即——请使用 ExplicitRenderCompatibility 在 SRP/URP 上。
摄像头未打开	权限被拒绝（Android / iOS）	声明 android.permission.CAMERA 在 manifest 中添加 NSCameraUsageDescription 到 Info.plist 中。
Quest 视频流未启动	缺少 manifest 权限	同时声明 horizonos.permission.HEADSET_CAMERA 是位于 android.permission.CAMERA.
Quest 视频流未启动	硬件不正确	QuestVisionFrameSource 需要 Quest 3 或 3S。Quest 2 和 Quest Pro 不受支持。
WebGL 视频流未发布	非 HTTPS 来源	部署到 HTTPS。 http://localhost 是唯一的例外。
WebGL 视频流未发布	已分配帧源	在 WebGL 上会忽略帧源——请移除它或保持为空；发布器使用 canvas.captureStream().
WebGL 上调试覆盖层为空白	预期如此——没有 RenderTexture	VisionDebugPreview 在 WebGL 上没有可显示的纹理。通过以下方式验证： IsPublishing 代替。

帧源问题

黑屏视频流

在 CameraVisionFrameSource 表明当前活动渲染管线使用了错误的捕获后端。

渲染管线	推荐模式	原因
内置渲染管线	Auto （使用 BuiltInHooks)	Camera.onPreRender / Camera.onPostRender 钩子可正常工作。
URP / SRP	Auto （使用 ExplicitRenderCompatibility)	显式 Camera.Render() 在 LateUpdate ——适用于所有 SRP 版本。
在 Auto 模式下出现黑屏视频流的 URP / SRP	ExplicitRenderCompatibility	会强制使用显式渲染路径；可解决自定义 SRP 配置下的黑屏视频流问题。

不要选择 SrpNative。它在此 SDK 构建中尚未实现。选择它会导致 CameraVisionFrameSource 进入 失败 状态，并立即出现 ErrorKind = UnsupportedPlatform.

未分配摄像机

如果 目标摄像机 为空，且场景中没有摄像机被标记为 MainCamera, CameraVisionFrameSource 进入 失败 状态：

ErrorKind = InvalidConfiguration
StatusMessage = "未分配摄像机，且 Camera.main 为 null。"

修复方法：为 目标摄像机 字段分配一个摄像机，或给其中一个摄像机添加标签 MainCamera.

摄像头权限被拒绝

在 Android 和 iOS 上， WebcamVisionFrameSource 会请求摄像头权限 StartCapture()。如果用户拒绝：

State = Failed
ErrorKind = PermissionDenied

Android： 验证 AndroidManifest.xml 声明 android.permission.CAMERA. iOS： 验证 Info.plist 包含 NSCameraUsageDescription ，且字符串非空。

如果用户之前已拒绝过权限，系统不会再次显示对话框。请引导用户前往设备的“设置”应用重新启用。

Quest 透视未启动

QuestVisionFrameSource 需要同时具备清单权限和正确的硬件。

所需的清单条目：

<uses-permission android:name="horizonos.permission.HEADSET_CAMERA" />
<uses-permission android:name="android.permission.CAMERA" />

如果缺少这两项声明，透视捕获会静默失败，帧源将进入 失败 状态。设备不会显示权限对话框——而是直接拒绝访问。

支持的硬件：仅限 Meta Quest 3 和 Quest 3S。Quest 2 和 Quest Pro 不会暴露 PassthroughCameraAccess.

决策树

启用帧健康探针

对于持续为空白或黑屏、且不会产生 失败 状态的帧，请在 CameraVisionFrameSource:

1. 选择 ConvaiVisionRoot GameObject。
2. 在 CameraVisionFrameSource，启用 启用诊断帧健康探针.
3. 按 Play 并观察 Console。

该探针会每帧执行一次同步的 GPU 到 CPU 像素回读并记录结果。这可以确认 RenderTexture 是否包含图像数据，或确实为空白。

禁用 启用诊断帧健康探针 在发布前。它会每帧执行一次同步 GPU 回读，这会导致 GPU 管线停顿并显著降低帧率。

日志记录

所有 Vision 日志消息都使用 LogCategory.Vision。将日志级别设为 详细 在 工具 → Convai → 配置 → 日志记录 ，以查看所有状态转换、帧源发现和发布事件。

前缀	组件
[ConvaiVisionPublisher]	发布器生命周期、帧源发现、策略更改
[VisionPublishCoordinator]	跟踪打开/关闭、帧路由
[CameraVisionFrameSource]	摄像头捕获后端选择、状态转换
[WebcamVisionFrameSource]	设备打开、权限请求、状态转换
[QuestVisionFrameSource]	透视 API 绑定、状态转换
[VisionDebugPreview]	帧源发现、备用切换

下一步

如果此处未涵盖该问题，请订阅 VisionCaptureStopped 是位于 VideoTrackUnpublished 并记录 原因 是位于 ErrorMessage 字段。参见 Vision 脚本 API 中的事件订阅模式。