> 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/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.md).

# 排查视觉问题

使用结构化检查清单和决策树，排查 Unity 中 Vision 发布失败、画面空白、权限错误及平台特定问题。

请从上到下逐项排查本页内容。大多数 Vision 故障都属于以下四类之一：连接配置错误、帧源故障、平台特定限制或 WebGL 源策略。

### 快速检查清单

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

{% stepper %}
{% step %}

#### 确认 Connection Type 为 Video

在 Hierarchy 中选择 `ConvaiRoomManager` 。确认 **Connection Type** 设置为 **Video**. `ConvaiVisionPublisher` 在 Connection Type 为 `Audio` 时会完全处于空闲状态——它会记录一条消息，然后直接返回，不会报错。
{% endstep %}

{% step %}

#### 确认房间已连接

`ConvaiVisionPublisher` 只有在房间连接后才会发布内容。检查 Console 中是否有 `[ConvaiRoomManager]` 连接日志。确认运行时 `ConvaiManager.ActiveManager` 不为 null。
{% endstep %}

{% step %}

#### 确认存在帧源

在原生平台（非 WebGL）上， `ConvaiVisionPublisher` 需要帧源。确认 `CameraVisionFrameSource`, `、WebcamVisionFrameSource`或自定义的 `IVisionFrameSource` 位于同一个 GameObject 或其子对象上。检查 Console 中是否有以下内容：

```
[ConvaiVisionPublisher] No IVisionFrameSource found.
```

{% endstep %}

{% step %}

#### 确认帧源处于 Ready 状态

在运行时于 Inspector 中打开帧源组件。确认 `State` 为 `Ready`。如果状态为 `Failed`，请在 Inspector 或 Console 中检查 `ErrorKind` 和 `StatusMessage` 。
{% endstep %}

{% step %}

#### 添加 VisionDebugPreview

将 `VisionDebugPreview` 添加到场景中的任意 GameObject。按下 Play。如果叠加层显示实时图像，且 `FPS > 0`，说明画面已传送到发布器。如果叠加层为空白或 FPS 始终为零，说明帧源未生成帧——请继续查看 [帧源问题](#frame-source-issues) 见下文。
{% endstep %}
{% endstepper %}

### 常见问题

| 症状                         | 可能原因                                                         | 解决方法                                                                                                                                             | 验证                                                                                                                                                                                                                                 |
| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IsPublishing` 保持为 `false` | 连接类型为 `Audio`                                                | 将 **连接类型** 设为 **视频** 在 `ConvaiRoomManager`.                                                                                                      | 确认 `IsPublishing` 在将连接类型切换为视频并重新连接后变为 `true` 。                                                                                                                                                                                     |
| `IsPublishing` 保持为 `false` | 房间未连接                                                        | 等待连接，或检查 API 密钥/网络。                                                                                                                              | 检查控制台中的 `[ConvaiRoomManager]` 连接日志，并确认 `ConvaiManager.ActiveManager` 不为 `null`.                                                                                                                                                    |
| `IsPublishing` 保持为 `false` | 未找到帧源                                                        | 将 `CameraVisionFrameSource` 添加到同一 GameObject 或其子 GameObject 上。                                                                                   | 确认控制台不再记录 `[ConvaiVisionPublisher] No IVisionFrameSource found.`                                                                                                                                                                   |
| 调试叠加层为空，FPS = 0            | 帧源处于 `Failed` 状态                                             | 检查 `ErrorKind` —请参阅 [帧源问题](#frame-source-issues).                                                                                                | 确认 `State` 在应用下方对应的修复后，帧源组件上的状态会退出 `Failed` 。                                                                                                                                                                                      |
| 画面为黑色                      | 错误的 `CameraCaptureMode` （与渲染管线不匹配）                           | 请参阅 [黑屏画面](#black-feed).                                                                                                                         | 确认 `VisionDebugPreview` 叠加层在切换模式后显示非黑色图像。                                                                                                                                                                                          |
| `SrpNative` 已选中            | 未实现的后端                                                       | `CameraVisionFrameSource` 进入 `Failed` 状态——在 SRP/URP 上请使用 `ExplicitRenderCompatibility` 。                                                         | 确认 `State` 不再报告 `Failed` 且 `ErrorKind = UnsupportedPlatform`.                                                                                                                                                                      |
| 摄像头无法打开                    | 权限被拒绝（Android / iOS）                                         | 在清单文件中声明 `android.permission.CAMERA` ；在 Info.plist 中添加 `NSCameraUsageDescription` 。                                                              | 确认 `State` 不再报告 `PermissionDenied` ，并且在权限对话框中授予权限后，摄像头预览会显示。                                                                                                                                                                       |
| Quest 视频流未启动               | 缺少清单权限                                                       | 声明以下两项： `horizonos.permission.HEADSET_CAMERA` 和 `android.permission.CAMERA`.                                                                     | 确认透视视频捕获已启动，并且 `State` 在重新部署并声明这两项后达到 `Ready` 状态。                                                                                                                                                                                  |
| Quest 视频流未启动               | 硬件不兼容                                                        | `QuestVisionFrameSource` 需要 Quest 3 或 3S。Quest 2 和 Quest Pro 均不受支持。                                                                              | 确认目标设备为 Quest 3 或 3S—— `State` 无法达到 `Ready` 无论权限如何，在不受支持的硬件上都无法进入该状态。                                                                                                                                                              |
| WebGL 视频流未发布               | 非 HTTPS 来源                                                   | 部署到 HTTPS。 `http://localhost` 是唯一例外。                                                                                                             | 确认部署的 URL 使用 `https://` （或者是 `http://localhost`).                                                                                                                                                                                  |
| WebGL 视频流未发布               | 已指定帧来源                                                       | 在 WebGL 上，帧来源会被忽略——请移除或留空；发布器使用 `canvas.captureStream()`.                                                                                        | 确认移除帧来源引用后， `IsPublishing` 会变为 `true` 。                                                                                                                                                                                            |
| WebGL 上的调试叠加层为空白           | 这是预期行为——没有 RenderTexture                                     | `VisionDebugPreview` 在 WebGL 上没有可显示的纹理。请改为通过 `IsPublishing` 进行验证。                                                                                | 确认 `IsPublishing` 为 `true` 即使叠加层仍为空白也是如此。                                                                                                                                                                                          |
| 采样窗口对帧选择没有影响               | 某个 **采样窗口** 条目设置了 **Count** ，但 **Interval Ms** 仍为 `0` （或反过来） | 请将 **Count** 和 **Interval Ms** 都设置为非零值，适用于 **采样窗口** 下的每个条目，位于 `ConvaiRoomManager` （或 `ConvaiRoomManagerProfile` 资源）中。请移除未使用的条目，而不是将其中一个字段留为 `0`. | 确认 Inspector 中两个字段均显示非零值。被丢弃的窗口不会在 Console 中发出警告——SDK 仅在窗口数量超过 **每轮帧数** 预算时才会发出警告——因此，没有警告并不能证明窗口已发送。                                                                                                                              |
| 更改响应模式没有明显效果               | `UpdateRespondMode` 返回 `false`，或者后端拒绝了请求                     | 检查 `bool` 返回值 `UpdateRespondMode` ，确认已生效后再继续；仅当 `IsConnected` 为 `true`时才调用它。订阅 `RespondModeUpdateResultReceived` 并检查 `Status` 和 `Message`.       | 确认 `RespondModeUpdateResultReceived.Status` 为 `"success"` ，且 `Modality` / `Mode` 与请求的通道和模式一致。有关事件订阅模式，请参阅 [视觉脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 。 |

### 帧源问题

#### 黑屏画面

在 `CameraVisionFrameSource` 上出现黑屏画面（叠加层可见，但所有像素均为黑色），表示当前渲染管线使用了错误的捕获后端。

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

{% hint style="danger" %}
请勿选择 `SrpNative`。此 SDK 版本未实现该功能。选择此项会导致 `CameraVisionFrameSource` 立即进入 `Failed` 状态，并显示 `ErrorKind = UnsupportedPlatform`.
{% endhint %}

#### 未指定摄像机

如果 **目标摄像机** 为空，且场景中没有摄像机带有 **MainCamera**, `CameraVisionFrameSource` 将在启动时进入 `Failed` 状态：

```
ErrorKind = InvalidConfiguration
StatusMessage = "No camera was assigned and Camera.main is null"
```

修复方法：在 **目标摄像机** 字段中指定摄像机，或为一台摄像机添加 **MainCamera**.

#### 摄像头权限被拒绝

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

```
State = Failed
ErrorKind = PermissionDenied
```

**Android：** 确认 `AndroidManifest.xml` 声明了 `android.permission.CAMERA`.\
**iOS：** 确认 `Info.plist` 包含 `NSCameraUsageDescription` ，且其字符串不为空。

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

#### Quest 透视画面无法启动

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

必需的清单条目：

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

如果缺少其中任一声明，透视捕获会静默失败，帧源会进入 `Failed` 状态。设备不会显示权限对话框，而是直接拒绝访问。

支持的硬件：仅 Meta Quest 3 和 Quest 3S。Quest 2 和 Quest Pro 不提供 `PassthroughCameraAccess`.

### 决策树

```mermaid
flowchart TD
    A[IsPublishing = false?] --> B{Connection Type = Video?}
    B -- No --> B1[将 ConvaiRoomManager 上的 Connection Type 设置为 Video]
    B -- Yes --> C{Room connected?}
    C -- No --> C1[检查 API 密钥、网络，以及 Console 中的连接错误]
    C -- Yes --> D{Frame source found?}
    D -- No --> D1[将 CameraVisionFrameSource 添加到同一 GameObject 或其子对象]
    D -- Yes --> E{Frame source State = Ready?}
    E -- No --> F{ErrorKind?}
    F -- InvalidConfiguration --> F1[指定 Target Camera，或为相机添加 MainCamera 标签]
    F -- PermissionDenied --> F2[添加清单权限；引导用户前往 Settings]
    F -- UnsupportedPlatform --> F3[确认未选择 SrpNative；Quest 源需要 Quest 3/3S]
    F -- DeviceUnavailable --> F4[检查网络摄像头设备名称；确认硬件已连接]
    E -- Yes --> G{Feed black?}
    G -- Yes --> G1[将 Camera Capture Mode 切换为 ExplicitRenderCompatibility]
    G -- No --> H[IsPublishing = true — 检查 VisionDebugPreview 叠加层]
```

### 启用帧健康状态探针

如果持续出现空白或黑色帧，但没有进入 `Failed` 状态，请在 `CameraVisionFrameSource`:

1. 中启用诊断探针。 **ConvaiVisionRoot** GameObject。
2. 在 `CameraVisionFrameSource`上，启用 **Enable Diagnostic Frame Health Probe**.
3. 按下 Play 并查看 Console。

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

{% hint style="warning" %}
发布前请禁用 **Enable Diagnostic Frame Health Probe** 。它每帧都会执行同步 GPU 回读，导致 GPU 管线停顿，并显著降低帧率。
{% endhint %}

### 日志记录

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

| 前缀                           | 组件                      |
| ---------------------------- | ----------------------- |
| `[ConvaiVisionPublisher]`    | 发布器生命周期、帧源发现、策略更改       |
| `[VisionPublishCoordinator]` | 跟踪开启/关闭、帧路由             |
| `[CameraVisionFrameSource]`  | 摄像头采集后端选择、状态转换          |
| `[WebcamVisionFrameSource]`  | 设备开启、权限请求、状态转换          |
| `[QuestVisionFrameSource]`   | Passthrough API 绑定、状态转换 |
| `[VisionDebugPreview]`       | 帧源发现、回退切换               |

### 后续步骤

如果此处未涵盖该问题，请订阅 `VisionCaptureStopped` 和 `VideoTrackUnpublished` 并记录 `Reason` 和 `ErrorMessage` 字段。请参阅 [视觉脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 了解事件订阅模式。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
