> 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).

# 排查 Vision 问题

请按从上到下的顺序阅读本页。大多数 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` 为 `就绪`。如果它是 `失败`之前，检查 `ErrorKind` 是位于 `StatusMessage` ，请在 Inspector 或 Console 中查看。
{% endstep %}

{% step %}

#### 将 VisionDebugPreview 添加到任意场景 GameObject。

添加 `VisionDebugPreview` 按 Play。若覆盖层显示实时图像且 `FPS > 0`，说明视频流已到达发布器。如果覆盖层为空白或 FPS 始终为零，则帧源没有生成帧——继续查看 [帧源问题](#frame-source-issues) 下文。
{% endstep %}
{% endstepper %}

### 常见问题

| 症状                        | 可能原因                           | 修复                                                                                       |
| ------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------- |
| `IsPublishing` 保持 `false` | Connection Type 为 `音频`         | 设置 **连接类型** 到 **视频** on `ConvaiRoomManager`.                                             |
| `IsPublishing` 保持 `false` | 房间未连接                          | 等待连接或检查 API 密钥/网络。                                                                       |
| `IsPublishing` 保持 `false` | 未找到帧源                          | 添加 `CameraVisionFrameSource` 到同一个或子 GameObject 上。                                        |
| 调试覆盖层空白，FPS = 0           | 帧源处于 `失败` 状态                   | 检查 `ErrorKind` ——参见 [帧源问题](#frame-source-issues).                                        |
| 视频流为黑屏                    | 错误的 `CameraCaptureMode` 用于渲染管线 | 请参见 [黑屏视频流](#black-feed).                                                                |
| `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 配置下的黑屏视频流问题。                   |

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

**未分配摄像机**

如果 **目标摄像机** 为空，且场景中没有摄像机被标记为 **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` 需要同时具备清单权限和正确的硬件。

所需的清单条目：

```xml
<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`.

### 决策树

```mermaid
flowchart TD
    A[IsPublishing = false?] --> B{Connection Type = Video?}
    B -- No --> B1[在 ConvaiRoomManager 上将 Connection Type 设为 Video]
    B -- Yes --> C{房间已连接？}
    C -- No --> C1[检查 API 密钥、网络和 Console 中的连接错误]
    C -- Yes --> D{找到帧源？}
    D -- No --> D1[将 CameraVisionFrameSource 添加到同一或子 GameObject]
    D -- Yes --> E{帧源状态 = Ready？}
    E -- No --> F{ErrorKind？}
    F -- InvalidConfiguration --> F1[分配目标摄像机或标记 MainCamera]
    F -- PermissionDenied --> F2[添加清单权限；引导用户前往设置]
    F -- UnsupportedPlatform --> F3[检查未选择 SrpNative；Quest 源需要 Quest 3/3S]
    F -- DeviceUnavailable --> F4[检查摄像头设备名称；验证硬件已连接]
    E -- Yes --> G{视频流黑屏？}
    G -- Yes --> G1[将 Camera Capture Mode 切换为 ExplicitRenderCompatibility]
    G -- No --> H[IsPublishing = true ——检查 VisionDebugPreview 覆盖层]
```

### 启用帧健康探针

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

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

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

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

### 日志记录

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

| 前缀                           | 组件                |
| ---------------------------- | ----------------- |
| `[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 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/convai-unity-sdk/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.