故障排除与诊断

使用结构化清单和决策树，诊断并解决 Vision 问题——发布失败、空白画面、权限错误以及特定平台问题。

诊断并解决 Vision 问题

大多数 Vision 问题可归为三类之一：发布器未在发布，视频流为空白或不正确，或帧源卡在非就绪状态。本页涵盖这三种情况，先从最快的一线工具开始，再处理平台特定问题。可使用决策树快速进行可视化诊断。

使用 VisionDebugPreview 进行一线诊断

VisionDebugPreview 是可用的最快诊断工具。在按下 Play 之前将其添加到任意场景 GameObject 上——它会显示实时 RenderTexture 输出以及一个统计信息叠加层，其中包括当前 VisionSourceState、FPS 和帧计数。

添加组件： Convai/Vision/Vision 调试预览（仅编辑器）

你会看到的情况	其含义
有实时图像，FPS > 0	帧源 就绪 且正在生成帧
空白/黑色图像，FPS = 0	帧源未在生成帧——检查 State 是位于 ErrorKind 如下
叠加层完全未显示	未找到活动帧源——请显式分配一个或启用 回退到活动帧源
叠加层出现了但显示占位符	已分配帧源，但尚未启动——检查其 State 在 Inspector 中

VisionDebugPreview 不 不是 显示 WebGL 画布捕获路径。在 WebGL 中，叠加层按设计会是空白的——这是预期行为，不是故障。

请参见 调试预览 查看完整配置选项。

---

一线排查

在出现问题时按顺序执行此检查清单。大多数问题会在第 1 或第 2 步解决。

1

验证连接类型

选择 ConvaiRoomManager 在 Hierarchy 中。确认 连接类型 被设置为 视频.

ConvaiVisionPublisher 在仅音频连接上永远不会发布，无论其他任何组件如何配置。这是最常见的 IsPublishing 仍保持 false.

2

检查帧源状态

添加 VisionDebugPreview 将其添加到任意场景 GameObject 并按下 Play。统计信息叠加层会显示当前 VisionSourceState.

• 就绪 → 帧源正常工作。转到第 3 步。
• 降级 → 捕获正在运行，但帧健康检查失败——请参见空白或黑色视频流。
• 失败 → 检查 ErrorKind 是位于 StatusMessage 帧源组件上的——请参见帧源错误。
• 等待授权 → 在 Android / iOS 上，正在等待用户授予相机权限——请参见移动权限问题。
• 空闲或正在启动 → 帧源尚未完成启动。检查组件是否已启用，以及其 目标摄像机 是否已分配，并且 Console 中没有错误。

3

检查发布器上的 IsPublishing

添加一个临时脚本，或在 Play 模式下检查是否 ConvaiVisionPublisher.IsPublishing 为 true。如果帧源 就绪 但 IsPublishing 仍然 false:

• 确认房间已 完全连接 ——不只是按下了 Play。
• 请确认 ConvaiVisionPublisher 为 已启用.
• 如果 发布策略 被设置为 Manual，则调用 publisher.EnablePublishing(true) ——在此策略下，发布不会自动开始。

4

检查 Console 中的错误

查找带有以下标签的消息： [Vision], [ConvaiVisionPublisher]，或 [CameraVisionFrameSource] 在 Unity Console 中。Vision 会使用源组件名称记录错误，从而可以轻松识别失败的组件。

---

常见问题

症状	可能原因	修复
IsPublishing 保持 false	ConvaiRoomManager.Connection Type 不是 视频	设置 连接类型 到 视频
IsPublishing 保持 false	房间未连接（API 密钥、网络）	在以下位置验证 API 密钥 ConvaiSettings；检查网络；查看 Console
IsPublishing 保持 false	帧源从未到达 就绪	添加 VisionDebugPreview；检查 State 是位于 ErrorKind 帧源上的
IsPublishing 保持 false	发布策略为 Manual	调用 publisher.EnablePublishing(true) 从脚本中
IsPublishing 保持 false	ConvaiVisionPublisher 组件已禁用	在 Inspector 中启用该组件
调试预览中出现黑屏或空白画面	错误的 CameraCaptureMode 对于渲染管线	设置 Camera Capture Mode 到 Auto on CameraVisionFrameSource
调试预览中出现黑屏或空白画面	目标摄像机 为空（Camera.main 未找到）	在……中显式分配一个相机 目标摄像机 字段
调试预览中出现黑屏或空白画面	VisionSourceState 为 降级	启用 启用诊断帧健康探针 暂时，以识别原因
帧源卡在 等待授权	Android / iOS 相机权限对话框待处理	等待操作系统对话框；如果被拒绝， ErrorKind 变为 PermissionDenied
帧源处于 失败, ErrorKind = PermissionDenied	用户拒绝了相机权限	通知用户；在 Android 上，引导其进入应用设置重新授予权限
帧源处于 失败, ErrorKind = UnsupportedPlatform	QuestVisionFrameSource 运行在非 Quest 平台上	在 Editor 中属于预期——使用 CameraVisionFrameSource 供 Editor 测试
帧源处于 失败, ErrorKind = DeviceUnavailable	未找到请求的摄像头设备	留空 摄像头设备名称 留空以选择第一个可用设备，或验证设备名称
QuestVisionFrameSource 在 失败	PassthroughCameraAccess 不在场景中	添加 PassthroughCameraAccess 组件，或将 透视相机访问 留空以进行自动发现
发布了错误的帧源	自动发现选择了错误的源	在……中显式分配正确的源 ConvaiVisionPublisher的 帧源组件 字段
VisionDebugPreview 叠加层为空白	未找到活动帧源	分配一个帧源，或启用 回退到活动帧源
VisionDebugPreview WebGL 上的叠加层为空白	没有 RenderTexture WebGL 上的路径	预期如此——WebGL 使用画布捕获；预览不适用
视频正在发布时，WebGL 上没有播放音频	浏览器要求在播放音频前有用户手势	确保用户在房间连接前已点击或与页面交互
视频已发布，但角色在视觉上没有响应	后端模型 / 会话配置	确认角色已在 Convai 仪表板中配置为多模态输入

---

空白或黑色视频流

黑色视频流表示帧源正在运行，但生成的是空帧或无效帧。 VisionSourceState 通常会是 就绪 或 降级.

第 1 步——检查相机捕获模式

在 CameraVisionFrameSource，确认 Camera Capture Mode 为 Auto。选择 BuiltInHooks 在 URP/HDRP 项目中会产生黑色视频流，因为 SRP 相机不会触发内置渲染回调。

第 2 步——确认目标相机正在渲染

已分配的相机必须处于活动状态、已启用且实际正在渲染。具有 Enabled = false 或其 GameObject 处于非活动状态的相机不会产生输出。

第 3 步——启用诊断帧健康探针

在 CameraVisionFrameSource，启用 启用诊断帧健康探针。这会执行逐帧同步像素回读，在检测到连续无效帧时记录到 Console。

禁用 启用诊断帧健康探针 在发布前使用。它会每帧执行一次同步的 GPU 到 CPU 回读，并带来可测量的性能开销。

第 4 步——检查后处理问题

某些后处理效果会以可能让捕获后端混淆的方式写入相机纹理。如果仅在启用后处理时画面为黑色，请尝试切换 Camera Capture Mode 到 ExplicitRenderCompatibility.

---

帧源错误

VisionSourceState 参考

State	含义	处理方法
空闲	捕获尚未开始	检查组件是否已启用以及发布器是否已启动
等待授权	正在等待操作系统相机权限（Android / iOS）	等待系统对话框；通过以下方式处理拒绝： ErrorKind = PermissionDenied
启动中	设备正在打开， RenderTexture 分配中	稍等片刻；如果卡住，请检查 Console 中的错误
就绪	捕获正在运行；正在生成帧	正常运行状态
降级	正在运行，但帧健康检查检测到问题	请参见空白或黑色视频流
已停止	捕获已正常停止	如有需要，请再次启动捕获
失败	不可恢复错误	读取 ErrorKind 是位于 StatusMessage 查看具体原因

VisionSourceErrorKind 参考

错误类型	原因	解决方案
无	无错误	—
超时	在预期时间窗口内未产生可用帧	检查相机是否处于活动状态并正在渲染；查看 CameraCaptureMode
PermissionDenied	操作系统相机权限被拒绝	引导用户在设备设置中授予权限
UnsupportedPlatform	此平台不支持该源	使用 CameraVisionFrameSource 在 Editor 中用于 QuestVisionFrameSource 场景
DeviceUnavailable	无法打开摄像头设备	留空 摄像头设备名称 留空，或通过以下方式验证设备名称： WebcamVisionFrameSource.GetAvailableDeviceNames()
InvalidConfiguration	某个字段值不一致	读取 StatusMessage 针对具体字段；在 Inspector 中更正
未知	意外的内部错误	查看 Console 中的完整异常；如果问题持续存在，请向支持团队报告

---

移动权限问题

在 Android 和 iOS 上， WebcamVisionFrameSource 在捕获开始时会异步请求相机权限。权限对话框只会出现一次——即应用安装后的首次运行会话中。

如果授予了权限： State 会从 AwaitingPermission → Starting → Ready 自动。

如果拒绝了权限： State 会转到 失败 其带有 ErrorKind = PermissionDenied。该组件不会自动重试。若要在应用中优雅处理此情况：

using Convai.Runtime.Vision.Sources;

void Update()
{
    var statusProvider = _webcamSource as IVisionFrameSourceStatusProvider;
    if (statusProvider != null
        && statusProvider.State == VisionSourceState.Failed
        && statusProvider.ErrorKind == VisionSourceErrorKind.PermissionDenied)
    {
        // 显示应用内消息，引导用户进入设备设置
        ShowPermissionDeniedUI();
    }
}

确保你的 Android manifest 声明了 android.permission.CAMERA 以及你的 iOS Info.plist 包含 NSCameraUsageDescription。如果没有这些声明，系统可能会静默拒绝权限请求，或阻止提交到应用商店。

---

Meta Quest 问题

QuestVisionFrameSource 绑定到 PassthroughCameraAccess 在运行时通过反射。常见失败模式：

问题	原因	修复
ErrorKind = UnsupportedPlatform	在 Editor 中或在非 Quest 硬件上运行	使用 CameraVisionFrameSource 在 Editor 中； QuestVisionFrameSource 仅适用于 Quest 硬件
失败 在启动时	PassthroughCameraAccess 未在场景中找到	将该组件添加到任意场景 GameObject，或将 透视相机访问 留空以进行自动发现
失败 在 Meta XR SDK 更新后	PassthroughCameraAccess SDK 版本之间 API 已更改	查看 Meta XR SDK 变更日志；如有需要更新 QuestVisionFrameSource 绑定
画面方向不正确	翻转 Y 已禁用	确保 翻转 Y 为 true （默认）

---

决策树：IsPublishing 一直为 False

---

结论

从以下开始 VisionDebugPreview 用于瞬时视觉诊断——叠加层的 State 和 FPS 计数器会立即覆盖最常见的故障模式。对于其他所有问题，请按顺序执行一线排查检查清单，然后查阅常见问题表。如果在遵循本指南后问题仍然存在，带有 Vision 组件名称标签的 Console 错误消息将指出确切的故障点。