> 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 控制台中给出明确消息。先从项目设置中的 Setup Health 检查开始，然后在深入具体问题之前，依次完成下面其余的第一步检查。

### 第一步检查

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

{% stepper %}
{% step %}

#### 运行 Setup Health 检查

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

这些检查包括 `设置资源` （标记缺失的 `ConvaiSettings.asset`), `API 密钥` （标记缺失的密钥）， `iOS 麦克风使用说明` （标记空的 `Info.plist` 描述）， `Android 麦克风权限` （信息性），以及 `定义漂移` 检查每个在不同构建目标组之间不一致的 Convai 功能标志脚本定义。

选择 **修复** 某个被标记项旁边的内容以应用自动修复——例如 **创建** 会添加缺失的 `ConvaiSettings.asset`，并且 **全部同步** 可使在不同构建目标组间漂移的脚本定义保持一致。选择 **刷新** 部分标题中的该项，以在手动更改后重新运行所有检查。

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

{% step %}

#### 打开 Unity 控制台

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

查找以下两条精确消息中的任意一条——它们会在你按下播放时立刻出现：

* `Convai Bootstrapper：未找到 ConvaiSettings！请通过 Edit > Project Settings > Convai SDK 配置设置。` → 该 `ConvaiSettings` 资源缺失或未创建。SDK 无法启动。
* `Convai Bootstrapper：未配置 API 密钥。请在 Edit > Project Settings > Convai SDK 中设置您的 API 密钥。` → 设置资源存在，但 API 密钥字段为空。

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

{% step %}

#### 验证 ConvaiSettings 资源

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

此资源必须位于准确路径 `Assets/Resources/ConvaiSettings.asset`。SDK 的引导程序通过 `Resources.Load` 在启动时加载它。如果它位于其他任何位置——包括 `Resources/` ——都将无法找到。

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

{% step %}

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

前往 **Edit → Project Settings → Convai SDK**。窗口会打开六个部分： **设置健康**, **凭据**, **运行时默认值**, **诊断**, **高级**，并且 **关于**.

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

当一切配置正确时，按下播放会显示 `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.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>      | 新输入系统——对话输入所必需             |

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

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

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

#### 缺少 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 显示后端切换提示，请接受。

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

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

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

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

### 排查安装失败

| 症状                                              | 可能原因                                          | 修复                                                                                               | 验证                                                             |
| ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| Setup Health 部分显示 **警告** 或 **阻止** 项             | 某个必需的项目设置缺失或已漂移——设置资源、API 密钥、iOS 麦克风使用说明或脚本定义 | 打开 Edit → Project Settings → Convai SDK → Setup Health，并选择 **修复** 该项旁边的内容，或手动更正后选择 **刷新**        | 该项的状态徽章变为健康（绿色）                                                |
| `Convai Bootstrapper：未找到 ConvaiSettings！` 在控制台中 | `ConvaiSettings.asset` 缺失或已删除                 | 打开 Edit → Project Settings → Convai SDK 以自动重新创建它                                                 | 重新进入播放模式—— `Convai Bootstrapper：初始化完成。` 出现                     |
| `未配置 API 密钥` 播放时警告                              | API 密钥字段为空                                    | 将来自 Convai 控制台的密钥粘贴到 Edit → Project Settings → Convai SDK → Credentials 中，然后选择 **验证并保存**         | 重新进入播放模式—— `未配置 API 密钥` 警告消失                                   |
| `找不到类型或命名空间 'Newtonsoft'`                       | 缺少 Newtonsoft.Json 包                          | 安装 `com.unity.nuget.newtonsoft-json` 通过包管理器                                                      | 项目编译时不再出现 Newtonsoft 命名空间错误                                    |
| `找不到类型或命名空间 'InputSystem'`                      | 缺少输入系统包或版本过旧                                  | 安装 `com.unity.inputsystem` <code class="expression">space.vars.dep\_inputsystem\_version</code>+ | 项目编译时不再出现 InputSystem 命名空间错误                                   |
| 通过 UPM 名称添加时未找到包                                | 未配置作用域注册表                                     | 按照 UPM 安装指南将 Convai 作用域注册表添加到 `manifest.json`                                                    | SDK 包出现在包管理器中                                                  |
| 从资源商店导入时出现冲突错误而失败                               | 之前 SDK 版本的文件仍然存在                              | 移除旧的 `Assets/Convai/` 文件夹，然后再重新导入                                                                | 包导入时不再出现冲突错误                                                   |
| 项目设置 → Convai SDK 窗口为空                          | 存在脚本编译错误                                      | 修复控制台中的所有 CS 错误；只有当编辑器脚本能干净编译时，设置界面才会渲染                                                          | Edit → Project Settings → Convai SDK 显示全部六个部分                  |
| 设置资源存在，但窗口未显示密钥                                 | 资源路径错误                                        | `ConvaiSettings.asset` 必须正好位于 `Assets/Resources/ConvaiSettings.asset` ——不能有子文件夹                  | Edit → Project Settings → Convai SDK → Credentials 显示 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` 方法运行之前触发。

| 消息                                                                                      | 级别     | 含义                                                                      |
| --------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------- |
| `Convai Bootstrapper：正在初始化...`                                                          | 信息     | SDK 初始化已开始                                                              |
| `Convai Bootstrapper：未找到 ConvaiSettings！请通过 Edit > Project Settings > Convai SDK 配置设置。` | **错误** | `ConvaiSettings.asset` 未在以下位置找到 `Assets/Resources/ConvaiSettings.asset` |
| `Convai Bootstrapper：未配置 API 密钥。请在 Edit > Project Settings > Convai SDK 中设置您的 API 密钥。`  | 警告     | 已找到设置资源，但 API 密钥字段为空                                                    |
| `Convai Bootstrapper：初始化完成。`                                                            | 信息     | 所有设置已成功加载；SDK 已准备就绪                                                     |

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

### 下一步

一旦 SDK 干净初始化并且引导程序记录 `Convai Bootstrapper：初始化完成。`，

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