> 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 版本是最常见的根本原因，而且不会给出任何清晰提示，所以请先确认这一点，然后再按下面的 Setup Health 检查和其余首要检查逐项排查。

### 首要检查

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

{% 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 %}

#### 运行 Setup Health 检查

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

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

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

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

{% step %}

#### 打开 Unity 控制台

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

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

* `Convai Bootstrapper: ConvaiSettings not found! Please configure settings via Edit > Project Settings > Convai SDK.` → 该 `ConvaiSettings` 资源缺失或未创建。SDK 无法启动。
* `Convai Bootstrapper: API key not configured. Please set your API key in Edit > Project Settings > Convai SDK.` → 设置资源存在，但 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**。该窗口包含六个部分： **Setup Health**, **Credentials**, **运行时默认值**, **诊断**, **高级**以及 **关于**.

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

当一切都配置正确时，按下播放会在控制台中显示 `Convai Bootstrapper: Initialization complete.` 。
{% 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”` 之前会出现任何 Convai 启动器消息。

#### Newtonsoft.Json 缺失

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

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

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

#### Input System 缺失

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

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

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

#### AI Inference 缺失

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

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

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

#### XR 模块缺失

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

**解决方法：** `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` 报告的构建版本达到或高于下限                                |
| Setup Health 部分显示一个 **警告** 或 **阻塞** 项                  | 所需的项目设置缺失或已漂移——设置资源、API 密钥、iOS 麦克风使用说明、iOS 录制准备，或某个 scripting define          | 打开 编辑 → 项目设置 → Convai SDK → Setup Health，并在该项旁边选择 **修复方法** ，或者手动修正后再选择 **刷新**                                              | 该项的状态徽章会变为健康（绿色）                                              |
| `Convai Bootstrapper: ConvaiSettings not found!` 在控制台中 | `ConvaiSettings.asset` 缺失或已删除                                                 | 打开 编辑 → 项目设置 → Convai SDK 可自动重新创建它                                                                                         | 重新进入播放模式 — `Convai Bootstrapper: Initialization complete.` 出现 |
| `API key not configured` 在播放时显示警告                      | API key field is empty                                                        | 将 Convai 控制台中的密钥粘贴到 编辑 → 项目设置 → Convai SDK → Credentials 中，然后选择 **验证并保存**                                                  | 重新进入播放模式 — 该 `API key not configured` 警告消失了                   |
| `找不到类型或命名空间“Newtonsoft”`                               | Newtonsoft.Json 包缺失                                                           | 安装 `com.unity.nuget.newtonsoft-json` 通过包管理器                                                                                | 项目编译时不再出现 Newtonsoft 命名空间错误                                   |
| `找不到类型或命名空间“InputSystem”`                              | Input System 包缺失或版本过旧                                                         | 安装 `com.unity.inputsystem` <code class="expression">space.vars.dep\_inputsystem\_version</code>+                           | 项目编译时不再出现 InputSystem 命名空间错误                                  |
| `类型或命名空间名称“InferenceEngine”在命名空间“Unity”中不存在`           | `com.unity.ai.inference` 缺失或版本过旧                                              | 安装 `com.unity.ai.inference` <code class="expression">space.vars.dep\_ai\_inference\_version</code>通过包管理器 +                 | 项目编译时不再出现 `Unity.InferenceEngine` 命名空间错误                      |
| `类型或命名空间名称“XR”在命名空间“UnityEngine”中不存在`                  | `com.unity.modules.xr` 已从 `Packages/manifest.json`                            | 在…中移除排除项 `Packages/manifest.json` 并让 Unity 重新导入                                                                            | 项目编译时不再出现 `UnityEngine.XR` 命名空间错误                             |
| 通过 UPM 名称添加时找不到包                                       | 未配置作用域注册表                                                                     | 按 UPM 安装指南将 Convai 作用域注册表添加到 `manifest.json`                                                                               | SDK 包出现在包管理器中                                                 |
| Asset Store 导入失败并出现冲突错误                                | 旧版 SDK 的文件仍然存在                                                                | 移除旧的 `Assets/Convai/` 文件夹后再重新导入                                                                                            | 包导入时没有冲突错误                                                    |
| 项目设置 → Convai SDK 窗口是空白的                               | 存在脚本编译错误                                                                      | 修复控制台中的所有 CS 错误；只有当编辑器脚本干净编译时，设置 UI 才会渲染                                                                                   | 编辑 → 项目设置 → Convai SDK 显示全部六个部分                               |
| 设置资源存在，但窗口没有显示密钥                                       | 资源路径错误                                                                        | `ConvaiSettings.asset` 必须正好位于 `Assets/Resources/ConvaiSettings.asset` — 不能有子文件夹                                            | 编辑 → 项目设置 → Convai SDK → Credentials 显示 API Key 字段            |
| 关于 `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` 方法运行之前。

| 消息                                                                                                                   | 级别     | 含义                                                                      |
| -------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------- |
| `Convai Bootstrapper：正在初始化...`                                                                                       | 信息     | SDK 初始化已开始                                                              |
| `Convai Bootstrapper: ConvaiSettings not found! Please configure settings via Edit > Project Settings > Convai SDK.` | **错误** | `ConvaiSettings.asset` 未在以下位置找到 `Assets/Resources/ConvaiSettings.asset` |
| `Convai Bootstrapper: API key not configured. Please set your API key in Edit > Project Settings > Convai SDK.`      | 警告     | 设置资源已找到，但 API 密钥字段为空                                                    |
| `Convai Bootstrapper: Initialization complete.`                                                                      | 信息     | 所有设置已成功加载；SDK 已准备就绪                                                     |

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

### 下一步

一旦 SDK 干净初始化且启动器记录了 `Convai Bootstrapper: Initialization complete.`，下一个要检查的问题类别是连接和 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 dynamically by asking a question.

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

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.