> 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/troubleshooting/installation-and-package-issues.md).

# 安装与包问题

修复 Convai Unity SDK 导入失败、不受支持的 Unity 版本、缺失的包依赖项以及启动器启动警告。

包导入和初始配置问题占 Convai Unity SDK 首次运行失败的大多数。大多数问题在你进入播放模式的瞬间——甚至更早，作为编译错误——就在 Unity 控制台中给出清晰信息。受支持的 Unity 版本不正确是最常见的根本原因，而且完全不会给出清晰信息，因此请先确认它，然后再逐一完成下面的设置健康检查和其余的一线检查。

### 一线检查

在深入具体问题之前，先完成这些步骤。它们涵盖最常见的根本原因，耗时不到三分钟。

{% stepper %}
{% step %}

#### 确认 Unity 版本

打开 `帮助 → 关于 Unity` （Windows）或 `Unity → 关于 Unity` （macOS），并读取确切的构建号。Convai Unity SDK 需要 Unity <code class="expression">space.vars.unity\_min\_version</code> —— 这是对确切补丁版本的硬性下限，不是四舍五入后的版本：更早的 `6000.0` 补丁版本，例如 `6000.0.20f1` 会被拒绝，而且在 Unity 2023 或更早版本上没有受支持的配置。只要编辑器达到或高于最低补丁版本， `6000.0` 到 `6000.5` 流都受支持。

如果编辑器更旧，请在安装 SDK 之前升级——该包依赖于只存在于 Unity 6 中的包。
{% endstep %}

{% step %}

#### 运行设置健康检查

前往 **编辑 → 项目设置 → Convai SDK**。 **设置健康** 部分会首先打开，并自动运行一组项目配置检查——每一项都会显示一个彩色状态徽章、标题和消息。

这些检查包括 `设置资源` （标记缺失的 `ConvaiSettings.asset`), `API 密钥` （标记缺失的密钥）， `iOS 麦克风使用说明` （标记空的 `Info.plist` 说明）， `为录音准备 iOS` （标记 Convai 麦克风录音和扬声器播放所使用的 iOS 音频会话设置）， `Android 麦克风权限` （信息性），以及一个 `定义漂移` 检查，用于检查每个在不同构建目标组之间存在差异的 Convai 功能标志脚本定义。

选择 **修复方法** 在任何被标记的项旁边 **创建** 会添加缺失的 `ConvaiSettings.asset`，以及 **全部同步** 会在不同构建目标组之间对齐漂移的脚本定义。完成手动更改后，在该部分标题中选择 **刷新** 以重新运行所有检查。

如果每一项都显示健康（绿色）徽章，则项目级设置正确，问题出在别处——请继续进行下面的下一项检查。
{% endstep %}

{% step %}

#### 打开 Unity 控制台

按 **Ctrl+Shift+C** （Windows）或 **Cmd+Shift+C** （Mac）来打开控制台。在搜索框中输入 `Convai` 以筛选消息。

查找以下两个确切消息中的任意一个——它们会在你按下 Play 的瞬间出现：

* `Convai Bootstrapper: 未找到 ConvaiSettings！请通过 编辑 > 项目设置 > Convai SDK 配置设置。` → `ConvaiSettings` 资源缺失或未创建。SDK 无法启动。
* `Convai Bootstrapper: API 密钥未配置。请在 编辑 > 项目设置 > Convai SDK 中设置你的 API 密钥。` → 设置资源存在，但 API 密钥字段为空。

如果你看到的是编译器错误而不是这些运行时消息，则程序集链已损坏——在进入播放模式之前，请先查看 [缺失或损坏的程序集](#missing-or-broken-assemblies) 下面的内容。
{% endstep %}

{% step %}

#### 验证 ConvaiSettings 资源

在项目窗口中，导航到 `Assets/Resources/`。查找名为 `ConvaiSettings`.

此资源必须存在于精确路径 `Assets/Resources/ConvaiSettings.asset`。SDK 的引导程序会在启动时通过 `Resources.Load` 加载它。如果它在任何其他位置——包括 `Resources/` 的子文件夹中——都不会被找到。

如果文件缺失，请打开 **编辑 → 项目设置 → Convai SDK**。打开设置窗口时，如果资源不存在，会自动创建该资源。
{% endstep %}

{% step %}

#### 确认设置窗口已打开

前往 **编辑 → 项目设置 → Convai SDK**。窗口打开时会显示六个部分： **设置健康**, **凭据**, **运行时默认值**, **诊断**, **高级**，以及 **关于**.

* 如果窗口是空白的，或没有显示任何部分，则项目中存在编译器错误。请先修复所有脚本错误——只有当所有编辑器脚本都能顺利编译时，设置提供程序才会渲染。
* 如果窗口已打开，但 **凭据** 部分没有显示任何 API 密钥，请选择 **凭据**，然后从 [Convai 开发者控制台](https://convai.com/)中粘贴你的密钥，然后选择 **验证并保存**.

当一切配置正确时，按下 Play 会在控制台中显示 `Convai Bootstrapper: 初始化完成。` 。
{% endstep %}
{% endstepper %}

### 包要求

| 项目              | 所需值                                                            |
| --------------- | -------------------------------------------------------------- |
| **包名**          | <code class="expression">space.vars.sdk\_package\_id</code>    |
| **版本**          | <code class="expression">space.vars.unity\_sdk\_version</code> |
| **最低 Unity 版本** | <code class="expression">space.vars.unity\_min\_version</code> |

#### 所需依赖

当你安装 Convai SDK 包时，UPM 会自动拉取这四个依赖项。如果任何一个缺失或版本不正确，程序集编译就会失败。

| 依赖项                               | 最低版本                                                                      | 备注                         |
| --------------------------------- | ------------------------------------------------------------------------- | -------------------------- |
| `com.unity.ai.inference`          | <code class="expression">space.vars.dep\_ai\_inference\_version</code>    | 客户端语音活动检测                  |
| `com.unity.nuget.newtonsoft-json` | <code class="expression">space.vars.dep\_newtonsoft\_json\_version</code> | JSON 序列化——所有 SDK 通信都需要     |
| `com.unity.ugui`                  | <code class="expression">space.vars.dep\_ugui\_version</code>             | UI Toolkit 模块——所有 UI 组件都需要 |
| `com.unity.inputsystem`           | <code class="expression">space.vars.dep\_inputsystem\_version</code>      | 新输入系统——对话输入所需              |

要验证已安装的版本： **窗口 → 包管理器 → 项目中**.

### 缺失或损坏的程序集

程序集定义错误会阻止项目进入播放模式。控制台会在任何 Convai 引导程序消息出现之前显示如下错误： `找不到类型或命名空间名称 'X'` 。

#### 缺少 Newtonsoft.Json

**错误：** `找不到类型或命名空间名称 'Newtonsoft'`

**修复：** 打开 **窗口 → 包管理器**。点击 **+** → **按名称添加包**。输入 `com.unity.nuget.newtonsoft-json` 并确认。Unity 会自动安装 <code class="expression">space.vars.dep\_newtonsoft\_json\_version</code> 版本或更高版本。

**验证：** 打开控制台。Newtonsoft 命名空间错误消失，项目可正常编译。

#### 缺少输入系统

**错误：** `找不到类型或命名空间名称 'InputSystem'`

**修复：** 安装 `com.unity.inputsystem` 版本 <code class="expression">space.vars.dep\_inputsystem\_version</code> 或更高版本，通过包管理器。安装后，Unity 会提示你切换到新的输入系统后端——接受该提示。

**验证：** 打开控制台。InputSystem 命名空间错误消失。如果 Unity 显示切换后端的提示，请接受。

#### 缺少 AI 推理

**错误：** `命名空间 'Unity' 中不存在类型或命名空间名称 'InferenceEngine'`

**修复：** 打开 **窗口 → 包管理器**。点击 **+** → **按名称添加包**。输入 `com.unity.ai.inference` 并确认。Unity 会自动安装 <code class="expression">space.vars.dep\_ai\_inference\_version</code> 版本或更高版本。

**验证：** 打开控制台。 `Unity.InferenceEngine` 命名空间错误消失，项目可正常编译。

#### 缺少 XR 模块

**错误：** `命名空间 'UnityEngine' 中不存在类型或命名空间名称 'XR'`

**修复：** `com.unity.modules.xr` 是 Unity 内置模块，而不是注册表包，SDK 也未将其列为依赖项。它默认启用；如果项目的 `Packages/manifest.json` 显式排除了它，请移除该排除项并让 Unity 重新导入。XR 按住说话输入需要它。

**验证：** 打开控制台。 `UnityEngine.XR` 命名空间错误消失，项目可正常编译。

#### 程序集重新编译循环

如果 Unity 在安装包后进入无限重新编译循环，请关闭 Unity 并删除 `Library/` 文件夹，然后重新打开项目。

{% hint style="danger" %}
删除 `Library/` 文件夹会强制 Unity 从头重新导入整个项目。此过程可能需要 5–30 分钟，具体取决于项目大小。删除该文件夹前请完全关闭 Unity。仅当所有其他修复都失败时才这样做。
{% endhint %}

**验证：** Unity 完成资源导入，不会再次进入重新编译循环。

### 排查安装失败

| 症状                                               | 可能原因                                                                          | 修复方法                                                                                                                      | 验证                                          |
| ------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| Unity 拒绝打开项目，或包管理器报告编辑器版本不兼容                     | 编辑器低于 Unity <code class="expression">space.vars.unity\_min\_version</code> 下限 | 升级到 Unity <code class="expression">space.vars.unity\_min\_version</code> 或更新版本——任何 `6000.0` 到 `6000.5` 达到或高于最低补丁版本的构建都受支持 | `帮助 → 关于 Unity` 报告的构建版本达到或高于下限              |
| 设置健康部分显示一个 **警告** 或 **阻止** 项                     | 某个必需的项目设置缺失或已漂移——设置资源、API 密钥、iOS 麦克风使用说明、iOS 录音准备，或某个脚本定义                     | 打开 编辑 → 项目设置 → Convai SDK → 设置健康，并在该项旁边选择 **修复方法** ，或者手动更正并选择 **刷新**                                                      | 该项的状态徽章会变为健康（绿色）                            |
| `Convai Bootstrapper: 未找到 ConvaiSettings！` 在控制台中 | `ConvaiSettings.asset` 缺失或已删除                                                 | 打开 编辑 → 项目设置 → Convai SDK 以自动重新创建它                                                                                        | 重新进入播放模式—— `Convai Bootstrapper: 初始化完成。` 出现 |
| `API 密钥未配置` 播放时的警告                               | API 密钥字段为空                                                                    | 将 Convai 仪表板中的密钥粘贴到 编辑 → 项目设置 → Convai SDK → 凭据，然后选择 **验证并保存**                                                            | 重新进入播放模式—— `API 密钥未配置` 警告消失                 |
| `找不到类型或命名空间 'Newtonsoft'`                        | Newtonsoft.Json 包缺失                                                           | 安装 `com.unity.nuget.newtonsoft-json` 通过包管理器                                                                               | 项目编译时不再出现 Newtonsoft 命名空间错误                 |
| `找不到类型或命名空间 'InputSystem'`                       | 输入系统包缺失或版本过旧                                                                  | 安装 `com.unity.inputsystem` <code class="expression">space.vars.dep\_inputsystem\_version</code>+                          | 项目编译时不再出现 InputSystem 命名空间错误                |
| `命名空间 'Unity' 中不存在类型或命名空间名称 'InferenceEngine'`   | `com.unity.ai.inference` 缺失或版本过旧                                              | 安装 `com.unity.ai.inference` <code class="expression">space.vars.dep\_ai\_inference\_version</code>通过包管理器 +                | 项目编译时不再出现 `Unity.InferenceEngine` 命名空间错误    |
| `命名空间 'UnityEngine' 中不存在类型或命名空间名称 'XR'`          | `com.unity.modules.xr` 已从 `Packages/manifest.json`                            | 移除排除项 `Packages/manifest.json` 并让 Unity 重新导入                                                                              | 项目编译时不再出现 `UnityEngine.XR` 命名空间错误           |
| 通过 UPM 名称添加时找不到包                                 | 未配置范围注册表                                                                      | 按照 UPM 安装指南将 Convai 范围注册表添加到 `manifest.json`                                                                              | SDK 包出现在包管理器中                               |
| 从资源商店导入失败，并出现冲突错误                                | 上一个 SDK 版本的文件仍然存在                                                             | 重新导入前删除旧的 `Assets/Convai/` 文件夹                                                                                            | 包导入时没有冲突错误                                  |
| 项目设置 → Convai SDK 窗口是空白的                         | 存在脚本编译错误                                                                      | 修复控制台中的所有 CS 错误；只有当编辑器脚本编译通过时，设置 UI 才会渲染                                                                                  | 编辑 → 项目设置 → Convai SDK 显示全部六个部分             |
| 设置资源存在，但窗口没有显示任何密钥                               | 资源路径错误                                                                        | `ConvaiSettings.asset` 必须恰好位于 `Assets/Resources/ConvaiSettings.asset` —— 不允许子文件夹                                          | 编辑 → 项目设置 → Convai SDK → 凭据显示 API 密钥字段      |
| 关于 `UGUI` 或 `UI/Default` 着色器                     | `com.unity.ugui` 缺失或版本不正确                                                     | 安装 `com.unity.ugui` <code class="expression">space.vars.dep\_ugui\_version</code>通过包管理器 +                                 | 项目编译时不再出现 UGUI 着色器错误                        |
| 示例场景已正确导入但无法运行                                   | 缺少 URP 包                                                                      | 示例场景需要 URP；请安装 `com.unity.render-pipelines.universal` 并在 项目设置 → 图形 中分配 URP 资源                                             | 示例场景进入播放模式时没有错误                             |

### 控制台日志参考

这些是 SDK 引导程序在初始化期间发出的确切消息。它们通过 `[RuntimeInitializeOnLoadMethod(BeforeSceneLoad)]` 触发——在你的 `Awake` 方法运行之前。

| Message                                                                    | 级别        | 含义                                                                |
| -------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------- |
| `Convai Bootstrapper: 正在初始化...`                                            | 信息        | SDK 初始化已开始                                                        |
| `Convai Bootstrapper: 未找到 ConvaiSettings！请通过 编辑 > 项目设置 > Convai SDK 配置设置。` | **Error** | `ConvaiSettings.asset` 未在 `Assets/Resources/ConvaiSettings.asset` |
| `Convai Bootstrapper: API 密钥未配置。请在 编辑 > 项目设置 > Convai SDK 中设置你的 API 密钥。`   | 警告        | 找到设置资源，但 API 密钥字段为空                                               |
| `Convai Bootstrapper: 初始化完成。`                                              | 信息        | 所有设置均已成功加载；SDK 已就绪                                                |

{% hint style="warning" %}
该 `未找到 ConvaiSettings` 错误不会阻止运行——SDK 会记录它并继续。你的场景会加载，但任何连接尝试都会立即失败，返回 `config.api_key_missing`。在测试对话之前，务必先解决引导程序错误。
{% endhint %}

### 下一步

一旦 SDK 成功初始化并且引导程序记录 `Convai Bootstrapper: 初始化完成。`，下一类要检查的问题就是连接和 API 密钥验证。

{% content-ref url="/pages/07c0ce6cfe225bcb17f8209c5187483d2497d1a4" %}
[连接与 API 问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/connection-and-api-issues.md)
{% endcontent-ref %}


---

# 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/troubleshooting/installation-and-package-issues.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.