> 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 故障都属于四类之一：连接配置错误、帧源故障、平台特定限制或 WebGL 源策略。

### 快速检查清单

在深入具体问题之前，请按顺序验证这五项：

{% stepper %}
{% step %}

#### 确认 Connection Type 为 Video

选择 `ConvaiRoomManager` 在 Hierarchy 中。确认 **连接类型** 设置为 **视频**. `ConvaiVisionPublisher` 当 Connection Type 为时会完全保持空闲 `音频` ——它会记录一条消息并正常返回，不报错。
{% endstep %}

{% step %}

#### 确认房间已连接

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

{% step %}

#### 确认存在帧源

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

```
[ConvaiVisionPublisher] 未找到 IVisionFrameSource。
```

{% endstep %}

{% step %}

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

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

{% step %}

#### 添加 VisionDebugPreview

添加 `VisionDebugPreview` 到场景中的任意 GameObject 上。点击 Play。如果叠加层显示实时图像并且 `FPS > 0`，说明视频流已到达发布器。如果叠加层为空白或 FPS 一直为零，则帧源没有产出帧——继续查看 [帧源问题](#frame-source-issues) 下文。
{% endstep %}
{% endstepper %}

### 常见问题

| 症状                        | 可能原因                                                     | 修复方法                                                                                                                                      | 验证                                                                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IsPublishing` 保持 `false` | Connection Type 为 `音频`                                   | 设置 **连接类型** 为 **视频** 在 `ConvaiRoomManager`.                                                                                               | 确认 `IsPublishing` 变为 `true` 在将 Connection Type 切换为 Video 并重新连接后。                                                                                                                                              |
| `IsPublishing` 保持 `false` | 房间未连接                                                    | 等待连接，或检查 API 密钥/网络。                                                                                                                       | 检查控制台中的 `[ConvaiRoomManager]` 连接日志并确认 `ConvaiManager.ActiveManager` 不是 `null`.                                                                                                                                |
| `IsPublishing` 保持 `false` | 未找到帧源                                                    | 添加 `CameraVisionFrameSource` 到同一个或子 GameObject 上。                                                                                         | 确认 Console 不再记录 `[ConvaiVisionPublisher] 未找到 IVisionFrameSource。`                                                                                                                                             |
| 调试叠加层空白，FPS = 0           | 帧源处于 `Failed` 状态                                         | 检查 `ErrorKind` ——见 [帧源问题](#frame-source-issues).                                                                                          | 确认 `State` 帧源组件上的该状态会消失 `Failed` 在应用下面相应的修复后。                                                                                                                                                                 |
| 画面是黑的                     | 错误的 `CameraCaptureMode` 用于渲染管线                           | 参见 [黑屏画面](#black-feed).                                                                                                                   | 确认 `VisionDebugPreview` 切换模式后叠加层显示非黑色图像。                                                                                                                                                                      |
| `SrpNative` 被选中           | 未实现的后端                                                   | `CameraVisionFrameSource` 进入 `Failed` 会立即——请使用 `ExplicitRenderCompatibility` 在 SRP/URP 上。                                                 | 确认 `State` 不再报告 `Failed` 使用 `ErrorKind = UnsupportedPlatform`.                                                                                                                                                |
| 摄像头未打开                    | 权限被拒绝（Android / iOS）                                     | 声明 `android.permission.CAMERA` 在 manifest 中；在 `NSCameraUsageDescription` 在 Info.plist 中添加。                                                | 确认 `State` 不再报告 `PermissionDenied` 并且在授予权限对话框后，摄像头预览会出现。                                                                                                                                                      |
| Quest 画面未开始               | 缺少 manifest 权限                                           | 同时声明两者 `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` 尽管叠加层仍然为空白。                                                                                                                                                                        |
| 采样窗口对帧选择没有影响              | 一个 **采样窗口** 条目已设置 **计数** 但 **Interval Ms** 保持为 `0` （或相反） | 将两者都设置为 **计数** 和 **Interval Ms** 为以下所有条目设置非零值： **采样窗口** 在 `ConvaiRoomManager` （或者 `ConvaiRoomManagerProfile` 资源）。删除未使用的条目，不要让某个字段保持为 `0`. | 确认两个字段在 Inspector 中都显示非零值。被丢弃的窗口不会记录 Console 警告——SDK 只有在窗口数量超过时才会警告 **每轮帧数** 预算——因此没有日志并不能证明该窗口已发送。                                                                                                           |
| Respond 模式更改没有可见效果        | `UpdateRespondMode` 返回了 `false`，或者后端拒绝了该请求               | 检查 `bool` 的返回值 `UpdateRespondMode` 再假设它已生效；仅在以下情况下调用它 `IsConnected` 是 `true`。订阅 `RespondModeUpdateResultReceived` 并检查 `状态` 和 `Message`.   | 确认 `RespondModeUpdateResultReceived.Status` 是 `"success"` 和 `Modality` / `模式` 与请求的通道和模式匹配。请参阅 [Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 以了解事件订阅模式。 |

### 帧源问题

#### 黑屏画面

在以下情况下出现黑屏画面（叠加层可见但所有像素均为黑色）： `CameraVisionFrameSource` 表示当前渲染管线使用了错误的采集后端。

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

{% hint style="danger" %}
不要选择 `SrpNative`。此 SDK 构建版本未实现它。选择它会导致 `CameraVisionFrameSource` 进入 `Failed` 状态，并立即显示 `ErrorKind = UnsupportedPlatform`.
{% endhint %}

#### 未分配摄像头

如果 **目标摄像头** 为空白，并且场景中没有摄像头被标记为 **MainCamera**, `CameraVisionFrameSource` 进入 `Failed` 启动时状态：

```
ErrorKind = InvalidConfiguration
StatusMessage = "未分配摄像头，并且 Camera.main 为 null"
```

修复方法：为以下对象分配一个摄像头： **目标摄像头** 字段，或者将一台摄像头标记为 **MainCamera**.

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

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

```
状态 = Failed
ErrorKind = PermissionDenied
```

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

如果用户之前已拒绝该权限，系统将不会再次显示对话框。请引导用户到设备的设置应用中重新启用它。

#### Quest 透视未启动

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

所需的 manifest 条目：

```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[Set Connection Type to Video on ConvaiRoomManager]
    B -- Yes --> C{Room connected?}
    C -- No --> C1[Check API key, network, Console for connection errors]
    C -- Yes --> D{Frame source found?}
    D -- No --> D1[Add CameraVisionFrameSource to same or child GameObject]
    D -- Yes --> E{Frame source State = Ready?}
    E -- No --> F{ErrorKind?}
    F -- InvalidConfiguration --> F1[Assign Target Camera or tag MainCamera]
    F -- PermissionDenied --> F2[Add manifest permissions; guide user to Settings]
    F -- UnsupportedPlatform --> F3[Check SrpNative not selected; Quest 3/3S required for Quest source]
    F -- DeviceUnavailable --> F4[Check webcam device name; verify hardware connected]
    E -- Yes --> G{Feed black?}
    G -- Yes --> G1[Switch Camera Capture Mode to ExplicitRenderCompatibility]
    G -- No --> H[IsPublishing = true — check VisionDebugPreview overlay]
```

### 启用帧健康探针

对于持续为空白或黑色、且不会产生 `Failed` 状态的帧，请在以下对象上启用诊断探针： `CameraVisionFrameSource`:

1. 选中 **ConvaiVisionRoot** GameObject。
2. 开 `CameraVisionFrameSource`，启用 **启用诊断帧健康探针**.
3. 点击 Play 并观察 Console。

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

{% hint style="warning" %}
禁用 **启用诊断帧健康探针** 在发布前关闭它。它会在每帧执行同步 GPU 回读，这会导致 GPU 管线停顿并显著降低帧率。
{% endhint %}

### 日志记录

所有 Vision 日志消息使用 `LogCategory.Vision`。将日志级别设为 `Verbose` 在 **Tools → Convai → Configuration → Logging** 以查看所有状态转换、帧源发现和发布事件。

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

### 下一步

如果这里没有涵盖该问题，请订阅 `VisionCaptureStopped` 和 `VideoTrackUnpublished` 并记录 `原因` 和 `ErrorMessage` 字段。请参阅 [Vision 脚本 API](/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.