> 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 首次运行失败的大多数原因。大多数问题在你进入 Play Mode 的瞬间——甚至更早，在编译器错误中——就会在 Unity Console 中显示清晰的消息。在深入排查具体问题之前，请先完成下面的首要检查。

### 首要检查

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

{% stepper %}
{% step %}

#### 打开 Unity Console

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

请查找以下两个完全一致的消息之一——它们会在你按下 Play 的瞬间出现：

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

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

{% step %}

#### 验证 ConvaiSettings 资源

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

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

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

{% step %}

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

转到 **Edit → Project Settings → Convai SDK**。该窗口应打开并显示以下字段： **API Key**, **Server URL**，并且 **Logging**.

* 如果窗口是空白的或没有显示任何字段，则项目中存在编译器错误。请先修复所有脚本错误——只有当所有编辑器脚本都能顺利编译时，设置提供程序才会渲染。
* 如果窗口已打开但 **API Key** 为空，请从 [Convai 开发者控制台](https://convai.com/).

中粘贴你的密钥。配置全部正确时，按下 Play 会显示 `Convai Bootstrapper: 初始化完成。` 在 Console 中。
{% 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>      | 新输入系统——对话输入所需              |

要验证已安装的版本： **Window → Package Manager → In Project**.

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

程序集定义错误会阻止项目进入 Play Mode。Console 会在出现任何 Convai 启动器消息之前显示类似 `找不到类型或命名空间名称“X”` 的错误。

#### 缺少 Newtonsoft.Json

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

**修复方法：** 打开 **Window → Package Manager**。点击 **+** → **Add package by name**。输入 `com.unity.nuget.newtonsoft-json` 并确认。Unity 会自动安装 <code class="expression">space.vars.dep\_newtonsoft\_json\_version</code> 或更高版本。

**验证：** 打开 Console。Newtonsoft 命名空间错误消失，项目可顺利编译。

#### 缺少 Input System

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

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

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

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

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

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

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

### 排查安装失败

| 症状                                                     | 可能原因                          | 修复方法                                                                                                  | 验证                                                 |
| ------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `Convai Bootstrapper: 找不到 ConvaiSettings！` 在 Console 中 | `ConvaiSettings.asset` 缺失或已删除 | 打开 Edit → Project Settings → Convai SDK 以自动重新创建它                                                      | 重新进入 Play Mode—— `Convai Bootstrapper: 初始化完成。` 出现  |
| `API key 未配置` Play 时的警告                                | API key 字段为空                  | 将 Convai 控制台中的密钥粘贴到 Edit → Project Settings → Convai SDK 中                                            | 重新进入 Play Mode—— `API key 未配置` 警告消失                |
| `找不到类型或命名空间“Newtonsoft”`                               | Newtonsoft.Json 包缺失           | 安装 `com.unity.nuget.newtonsoft-json` 通过 Package Manager                                               | 项目编译时不再出现 Newtonsoft 命名空间错误                        |
| `找不到类型或命名空间“InputSystem”`                              | Input System 包缺失或版本过旧         | 安装 `com.unity.inputsystem` <code class="expression">space.vars.dep\_inputsystem\_version</code>+      | 项目编译时不再出现 InputSystem 命名空间错误                       |
| 通过 UPM 名称添加时未找到包                                       | 未配置作用域注册表                     | 按照 UPM 安装指南，将 Convai 作用域注册表添加到 `manifest.json`                                                        | SDK 包出现在 Package Manager 中                         |
| 从 Asset Store 导入时出现冲突错误                                | 之前 SDK 版本的文件仍然存在              | 删除旧的 `Assets/Convai/` 文件夹后再重新导入                                                                       | 包导入时没有冲突错误                                         |
| Project Settings → Convai SDK 窗口为空白                    | 存在脚本编译错误                      | 修复 Console 中所有 CS 错误；只有当编辑器脚本能顺利编译时，设置 UI 才会渲染                                                        | Edit → Project Settings → Convai SDK 显示所有字段        |
| 设置资源存在，但窗口没有显示密钥                                       | 资源路径错误                        | `ConvaiSettings.asset` 必须正好位于 `Assets/Resources/ConvaiSettings.asset` ——不能有子文件夹                       | Edit → Project Settings → Convai SDK 显示 API Key 字段 |
| 关于 `UGUI` 或 `UI/Default` 着色器                           | `com.unity.ugui` 缺失或版本不正确     | 安装 `com.unity.ugui` <code class="expression">space.vars.dep\_ugui\_version</code>+ 通过 Package Manager | 项目编译时没有 UGUI 着色器错误                                 |
| 示例场景导入正确，但无法运行                                         | 缺少 URP 包                      | 示例场景需要 URP；请安装 `com.unity.render-pipelines.universal` 并在 Project Settings → Graphics 中分配 URP 资源       | 示例场景进入 Play Mode 时没有错误                             |

### Console 日志参考

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

| Message                                                                                  | 级别     | 含义                                                                |
| ---------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------- |
| `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 key。` | 警告     | 找到设置资源，但 API key 字段为空                                             |
| `Convai Bootstrapper: 初始化完成。`                                                            | 信息     | 所有设置已成功加载；SDK 已就绪                                                 |

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

### 下一步

一旦 SDK 顺利初始化并且启动器记录 `Convai Bootstrapper: 初始化完成。`，接下来需要检查的问题类别是连接和 API key 验证。

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

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/installation-and-package-issues.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.