> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/troubleshooting-and-diagnostics.md).

# 故障排查与诊断

## 诊断并解决 Vision 问题

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

## 使用 VisionDebugPreview 进行一线诊断

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

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

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

{% hint style="warning" %}
`VisionDebugPreview` 不 **不是** 显示 WebGL 画布捕获路径。在 WebGL 中，叠加层按设计会是空白的——这是预期行为，不是故障。
{% endhint %}

请参见 [调试预览](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/debug-preview.md) 查看完整配置选项。

***

## 一线排查

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

{% stepper %}
{% step %}
**验证连接类型**

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

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

{% step %}
**检查帧源状态**

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

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

{% step %}
**检查发布器上的 IsPublishing**

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

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

{% step %}
**检查 Console 中的错误**

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

***

## 常见问题

| 症状                                           | 可能原因                                        | 修复                                                               |
| -------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| `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。

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

**第 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`。该组件不会自动重试。若要在应用中优雅处理此情况：

```csharp
using Convai.Runtime.Vision.Sources;

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

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

***

## 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

```mermaid
flowchart TD
    A[IsPublishing = false] --> B{ConvaiRoomManager\n连接类型 = Video?}
    B -- No --> C[将连接类型\n设置为 Video 并重新测试]
    B -- Yes --> D{房间已连接？}
    D -- No --> E[检查 ConvaiSettings 中的 API 密钥\n和网络连接]
    D -- Yes --> F{帧源的\nVisionSourceState？}
    F -- Ready --> G{ConvaiVisionPublisher\n已启用？}
    G -- No --> H[在 Inspector 中\n启用该组件]
    G -- Yes --> I{发布策略\n= Manual？}
    I -- Yes --> J[从脚本调用 EnablePublishing true\n
    I -- No --> K[检查 Console 中的错误\n标签：ConvaiVisionPublisher]
    F -- Failed --> L[读取帧源上的 ErrorKind 和 StatusMessage\n请参见帧源错误表]
    F -- AwaitingPermission --> M[正在等待操作系统权限\n对话框——等待或处理拒绝]
    F -- Degraded --> N[捕获正在运行但帧无效\n请参见空白或黑色视频流]
    F -- Idle or Starting --> O[组件可能已禁用\n或未分配相机\n检查 Inspector]
```

***

## 结论

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/troubleshooting-and-diagnostics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.