> 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 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 密钥字段为空。

如果看到的是编译器错误，而不是这些运行时消息，则程序集链已损坏——在进入 Play 模式前，请参阅下文的 [程序集缺失或损坏](#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 密钥，请选择 **凭据**，然后从 [Convai 开发者控制面板](https://convai.com/)，然后选择 **验证并保存**.

配置正确后，按下 Play，控制台中会显示 `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>      | 新输入系统——对话输入需要此依赖项              |

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

### 程序集缺失或损坏

程序集定义错误会导致项目无法进入 Play Mode。控制台会显示类似 `The type or namespace name 'X' could not be found` 的错误，且不会显示任何 Convai bootstrapper 消息。

#### 缺少 Newtonsoft.Json

**错误：** `The type or namespace name 'Newtonsoft' could not be found`

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

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

#### 缺少 Input System

**错误：** `The type or namespace name 'InputSystem' could not be found`

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

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

#### 缺少 AI Inference

**错误：** `The type or namespace name 'InferenceEngine' does not exist in the namespace 'Unity'`

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

**验证：** 打开 Console。 `Unity.InferenceEngine` 命名空间错误应已消失，项目也应能顺利编译。

#### 缺少 XR 模块

**错误：** `The type or namespace name 'XR' does not exist in the namespace 'UnityEngine'`

**修复方法：** `com.unity.modules.xr` 是 Unity 内置模块，而非注册表软件包，SDK 也未将其列为依赖项。该模块默认启用；如果项目的 `Packages/manifest.json` 中明确排除了该模块，请移除排除项并让 Unity 重新导入。XR 按键通话输入需要此模块。

**验证：** 打开 Console。 `UnityEngine.XR` 命名空间错误应已消失，项目也应能顺利编译。

#### 程序集反复重新编译

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

{% hint style="danger" %}
删除 `Library/` 文件夹会强制 Unity 从头重新导入整个项目。根据项目大小，此过程可能需要 5–30 分钟。删除文件夹前，请完全关闭 Unity。只有在所有其他修复方法都失败后，才执行此操作。
{% endhint %}

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

### 排查安装失败问题

| 症状                                                                                     | 可能原因                                                                                | 解决方法                                                                                                                        | 验证                                                                |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Unity 拒绝打开项目，或 Package Manager 报告编辑器版本不兼容                                              | 编辑器版本低于 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 not found!` 出现在控制台中                               | `ConvaiSettings.asset` 缺失或已被删除                                                      | 打开编辑 → 项目设置 → Convai SDK，系统会自动重新创建该文件                                                                                       | 重新进入播放模式—— `Convai Bootstrapper: Initialization complete.` 出现     |
| `API key not configured` 警告在播放时出现                                                      | API 密钥字段为空                                                                          | 将 Convai 控制台中的密钥粘贴到编辑 → 项目设置 → Convai SDK → 凭据中，然后选择 **验证并保存**                                                              | 重新进入播放模式—— `API key not configured` 警告不再出现                        |
| `The type or namespace 'Newtonsoft' could not be found`                                | 缺少 Newtonsoft.Json 包                                                                | 安装 `com.unity.nuget.newtonsoft-json` ，使用包管理器                                                                                | 项目编译时不再出现 Newtonsoft 命名空间错误                                       |
| `The type or namespace 'InputSystem' could not be found`                               | 缺少 Input System 包或其版本过旧                                                             | 安装 `com.unity.inputsystem` <code class="expression">space.vars.dep\_inputsystem\_version</code>+                            | 项目编译时不再出现 InputSystem 命名空间错误                                      |
| `The type or namespace name 'InferenceEngine' does not exist in the namespace 'Unity'` | `com.unity.ai.inference` 缺失或版本过旧                                                    | 安装 `com.unity.ai.inference` <code class="expression">space.vars.dep\_ai\_inference\_version</code>+，使用包管理器                  | 项目编译时不再出现 `Unity.InferenceEngine` 命名空间错误                          |
| `The type or namespace name 'XR' does not exist in the namespace 'UnityEngine'`        | `com.unity.modules.xr` 已从……中排除 `Packages/manifest.json`                             | 在……中移除排除项 `Packages/manifest.json` 并让 Unity 重新导入                                                                            | 项目编译时不再出现 `UnityEngine.XR` 命名空间错误                                 |
| 通过 UPM 名称添加时找不到程序包                                                                     | 未配置作用域注册表                                                                           | 按照 UPM 安装指南，将 Convai 作用域注册表添加到 `manifest.json`                                                                              | 程序包显示在 Package Manager 中                                          |
| 通过 Asset Store 导入时出现冲突错误                                                               | 仍存在旧版 SDK 的文件                                                                       | 重新导入前，移除旧的 `Assets/Convai/` 文件夹                                                                                             | 程序包导入时不再出现冲突错误                                                    |
| Project Settings → Convai SDK 窗口为空白                                                    | 存在脚本编译错误                                                                            | 在 Console 中修复所有 CS 错误；只有编辑器脚本成功编译后，设置界面才会显示                                                                                 | Edit → Project Settings → Convai SDK 中显示全部六个部分                    |
| 设置资源存在，但窗口中未显示密钥                                                                       | 资源路径错误                                                                              | `ConvaiSettings.asset` 必须位于准确路径 `Assets/Resources/ConvaiSettings.asset` ——不得放在子文件夹中                                         | Edit → Project Settings → Convai SDK → Credentials 中显示 API Key 字段 |
| 关于 `UGUI` 或 `UI/Default` 着色器的错误                                                        | `com.unity.ugui` 缺失或版本不正确                                                           | 通过 Package Manager 安装 `com.unity.ugui` <code class="expression">space.vars.dep\_ugui\_version</code>+                       | 项目编译时不再出现 UGUI 着色器错误                                              |
| 示例场景导入正确，但无法运行                                                                         | 缺少 URP 程序包                                                                          | 示例场景需要 URP；请安装 `com.unity.render-pipelines.universal` 并在 Project Settings → Graphics 中指定 URP 资源                             | 示例场景进入 Play Mode 时不再出现错误                                          |

### 控制台日志参考

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

| 消息                                                                                                                   | 级别     | 含义                                                                       |
| -------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| `Convai Bootstrapper: Initializing...`                                                                               | 信息     | 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 not found` 错误不会阻止运行——SDK 会记录该错误并继续执行。场景仍会加载，但任何连接尝试都会立即失败，并返回 `config.api_key_missing`。测试对话前，请务必先解决引导程序错误。
{% endhint %}

### 后续步骤

SDK 成功初始化，且引导程序记录了 `Convai Bootstrapper: Initialization complete.`后，接下来要检查的问题类别是连接和 API 密钥验证。

{% content-ref url="/pages/07c0ce6cfe225bcb17f8209c5187483d2497d1a4" %}
[连接与 API 问题](https://docs.convai.com/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.
