For the complete documentation index, see llms.txt. This page is also available as Markdown.

安装与包问题

通过分步修复,解决 Convai Unity SDK 导入失败、依赖缺失、程序集错误和 bootstrapper 启动警告。

包导入和初始配置问题占据了 Convai Unity SDK 首次运行失败的大多数原因。大多数问题在你进入 Play Mode 的瞬间——甚至更早,在编译器错误中——就会在 Unity Console 中显示清晰的消息。在深入排查具体问题之前,请先完成下面的首要检查。

首要检查

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

1

打开 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 之前,请先查看 缺失或损坏的程序集 如下。

2

验证 ConvaiSettings 资源

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

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

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

3

确认设置窗口已打开

转到 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/ 文件夹,然后重新打开项目。

验证: 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 字段

关于 UGUIUI/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 方法运行之前。

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 已就绪

下一步

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

连接与 API 问题

最后更新于

这有帮助吗?