安装与包问题
通过分步修复，解决 Convai Unity SDK 导入失败、依赖缺失、程序集错误和 bootstrapper 启动警告。
包导入和初始配置问题占据了 Convai Unity SDK 首次运行失败的大多数原因。大多数问题在你进入 Play Mode 的瞬间——甚至更早，在编译器错误中——就会在 Unity Console 中显示清晰的消息。在深入排查具体问题之前，请先完成下面的首要检查。
首要检查
在深入排查具体问题之前，请先完成这三个步骤。它们涵盖了最常见的根本原因，耗时不到两分钟。
打开 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 之前，请先查看 缺失或损坏的程序集 如下。
确认设置窗口已打开
转到 Edit → Project Settings → Convai SDK。该窗口应打开并显示以下字段： API Key, Server URL，并且 Logging.
如果窗口是空白的或没有显示任何字段，则项目中存在编译器错误。请先修复所有脚本错误——只有当所有编辑器脚本都能顺利编译时，设置提供程序才会渲染。
如果窗口已打开但 API Key 为空，请从 Convai 开发者控制台.
中粘贴你的密钥。配置全部正确时，按下 Play 会显示 Convai Bootstrapper: 初始化完成。 在 Console 中。
包要求
包名称
com.convai.convai-sdk-for-unity
版本
4.2.0
最低 Unity 版本
2023.1 or later
所需依赖
当你安装 Convai SDK 包时，这三个依赖会由 UPM 自动引入。如果任何一个缺失或版本不正确，程序集编译就会失败。
com.unity.nuget.newtonsoft-json
3.2.2
JSON 序列化——所有 SDK 通信都需要
com.unity.ugui
2.0.0
UI Toolkit 模块——所有 UI 组件都需要
com.unity.inputsystem
1.18.0
新输入系统——对话输入所需
要验证已安装的版本： 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 会自动安装 3.2.2 或更高版本。
验证： 打开 Console。Newtonsoft 命名空间错误消失，项目可顺利编译。
缺少 Input System
错误： 找不到类型或命名空间名称“InputSystem”
修复方法： 安装 com.unity.inputsystem 版本 1.18.0 或更高版本。安装后，Unity 会提示你切换到新的 Input System 后端——请接受该提示。
验证： 打开 Console。InputSystem 命名空间错误消失。如果 Unity 显示后端切换提示，请接受它。
程序集重新编译循环
如果 Unity 在安装包后进入无限重新编译循环，请关闭 Unity 并删除 Library/ 文件夹，然后重新打开项目。
删除 Library/ 文件夹会强制 Unity 从头重新导入整个项目。此过程可能需要 5–30 分钟，具体取决于项目大小。删除文件夹前请完全关闭 Unity。仅当所有其他修复都失败时才这样做。
验证： 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 1.18.0+
项目编译时不再出现 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 2.0.0+ 通过 Package Manager
项目编译时没有 UGUI 着色器错误
示例场景导入正确，但无法运行
缺少 URP 包
示例场景需要 URP；请安装 com.unity.render-pipelines.universal 并在 Project Settings → Graphics 中分配 URP 资源
示例场景进入 Play Mode 时没有错误
Console 日志参考
这些是 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 key。
警告
找到设置资源，但 API key 字段为空
Convai Bootstrapper: 初始化完成。
信息
所有设置已成功加载；SDK 已就绪
该 未找到 ConvaiSettings 错误不会阻塞——SDK 会记录它并继续运行。你的场景会加载，但任何连接尝试都会立即失败，并返回 config.api_key_missing。在测试对话之前，请务必先解决启动器错误。
下一步
一旦 SDK 顺利初始化并且启动器记录 Convai Bootstrapper: 初始化完成。，接下来需要检查的问题类别是连接和 API key 验证。
最后更新于
这有帮助吗？