> 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-unreal-engine-plugin/troubleshooting/installation-and-plugin-issues.md).

# 安装和插件问题

修复 Convai Unreal Engine 插件中的插件未找到错误、模块加载失败、仅 Blueprint 项目限制和 Android 打包错误。

使用此页面解决安装期间发生的问题，或插件在 Unreal 编辑器中无法加载时的问题。插件加载后出现的问题——例如 API 密钥或音频错误——已在其他故障排除页面中说明。

### 一线检查

在排查具体症状之前，请先完成这三个检查。它们可确认 Unreal 是否能够发现插件并加载运行时模块。

{% stepper %}
{% step %}

#### 确认插件是否出现在插件列表中

打开 **Edit > Plugins** 中搜索 `Convai`。插件条目必须显示并启用（复选框已勾选）。如果未显示，则文件夹结构不正确——请参见 [插件未出现在插件列表中](#plugin-does-not-appear-in-the-plugins-list).
{% endstep %}

{% step %}

#### 检查输出日志中是否有 LogConvai 条目

打开 **窗口 > 输出日志** 并输入 `LogConvai` 到搜索字段中。原生库加载失败会显示为 `无法从 %s 加载 %s`。如果没有出现任何 Convai 日志类别，Unreal 可能没有发现该插件。
{% endstep %}

{% step %}

#### 验证插件文件夹结构

对于项目级安装，插件根目录必须位于 `<YourProject>/Plugins/Convai/` 并且必须包含 `ConvAI.uplugin`。对于引擎级安装，插件根目录位于引擎的 `Engine/Plugins/Marketplace/Convai/` 文件夹。
{% endstep %}
{% endstepper %}

### 插件未出现在插件列表中

**症状：** 将插件文件夹复制到项目或引擎后，Convai 条目不会出现在 **Edit > Plugins**.

**原因——安装位置或文件夹结构不正确：** 解压后的文件夹不包含 `ConvAI.uplugin` 位于插件根目录中，或者该文件夹被放在 Unreal 不会扫描的位置。

**修复：** 将解压后的插件文件夹移动到受支持的位置之一，然后重新启动 Unreal 编辑器：

| 安装类型  | 文件夹                                                 |
| ----- | --------------------------------------------------- |
| 项目级安装 | `<YourProject>/Plugins/Convai/`                     |
| 引擎级安装 | `<UnrealEngine>/Engine/Plugins/Marketplace/Convai/` |

所选文件夹必须在其根目录中包含 `ConvAI.uplugin` 。

**验证：** 打开 **Edit > Plugins**，搜索 `Convai`，并确认该条目出现。如果尚未启用，请将其启用，然后在提示时重启编辑器。

***

**原因——Fab 或 Marketplace 安装未传播：** 当插件通过 [Fab](https://www.fab.com/listings/ba3145af-d2ef-434a-8bc3-f3fa1dfe7d5c)获取时，Epic Games Launcher 必须先将其安装到引擎中，编辑器才能检测到它。

**修复：** 打开 Epic Games Launcher，进入你的 Library，找到 Convai 插件条目，然后点击 **安装到引擎** ，对应你正在使用的引擎版本。

**验证：** 重新启动 Unreal 编辑器。插件应出现在 **Edit > Plugins** 在……下的 **运行时** 类别。

### 插件已启用，但编辑器未能正常重启

**症状：** 你启用了 Convai 插件并点击 **立即重启**，但编辑器崩溃，或在重启时显示编译对话框。

**原因——C++ 项目需要重新编译：** 当在项目级添加源代码插件时，Unreal Engine 可能会重新编译项目代码。如果编译失败，编辑器将无法启动。

**修复：** 在 Visual Studio（或你配置的 IDE）中打开项目，选择 **生成 > 生成解决方案**，解决所有编译错误，然后再次启动编辑器。

**验证：** 编辑器在没有编译对话框的情况下打开，Convai 组件会出现在 **添加组件** 菜单中（编辑蓝图时）。

### 蓝图专用项目无法加载插件

**症状：** 插件已正确安装，但编辑器在重启时崩溃，或显示无法编译模块的对话框。你使用的是没有 C++ 源文件的蓝图专用项目。

**原因：** 项目级源代码插件可能需要 Unreal Build Tool 来编译诸如 `Convai`, `ConvaiEditor`，以及 `ConvaiVisionBase`之类的模块。蓝图专用项目没有生成的 C++ 目标，因此 Unreal 无法编译项目级源代码插件。

{% hint style="warning" %}
蓝图专用项目应为 Convai 插件使用 Fab 或引擎级安装路径。当项目具有 C++ 构建目标时，再使用项目级安装。
{% endhint %}

**修复——方案 A（推荐）：转换为 C++ 项目**

在 Unreal 编辑器中，选择 **文件 > 新建 C++ 类**，接受默认 `无` 父类和默认文件名，然后点击 **创建类**。这会生成项目文件并设置构建环境。IDE 打开后，构建解决方案，然后重新启动编辑器。

**修复——方案 B：引擎级安装**

将插件安装到引擎目录，而不是项目目录。将插件文件夹放在：

```
C:\Program Files\Epic Games\UE_5.x\Engine\Plugins\Marketplace\Convai\
```

替换 `5.x` ，替换为你的引擎版本。引擎本身已具备构建环境，因此引擎级插件不需要按项目单独编译。

**验证：** 构建完成后，编辑器会正常重启。Convai 组件会出现在 **添加组件** 菜单中。

### `ConvaiEditor` 模块不可用

**症状：** 在 Unreal Engine 5.1 或更早版本中，Convai 编辑器窗口不会出现。输出日志显示 `ConvaiEditor: 编辑器 UI 已禁用 - 需要 UE 5.2 或更高版本`.

**原因：** 该 `ConvaiEditor` 模块需要一种属性绑定编辑器功能，而该功能在 UE 5.1 及更早版本中不可用。该模块在这些引擎版本中被有意禁用。

**修复：** 升级到 Unreal Engine 5.2 或更高版本以使用 Convai 编辑器窗口。在 UE 5.1 及更早版本中，请通过设置手动配置 API 密钥 `API_Key` 在 `Config/DefaultEngine.ini` 在……下的 `[/Script/Convai.ConvaiSettings]` 部分。

**验证：** 在配置文件中设置密钥后，打开 **编辑 > 项目设置 > 插件 > Convai** 并确认 `API 密钥` 字段会显示你设置的值。

插件版本 <code class="expression">space.vars.unreal\_plugin\_version</code> 支持从 5.0 开始的所有 Unreal Engine 5.x 版本； `ConvaiEditor` 是唯一需要 5.2 或更高版本的组件。

### `AudioCapture` 插件依赖项缺失

**症状：** 编辑器显示引用缺失 `AudioCapture` 模块的错误，或者插件因依赖项错误而无法加载。

**原因：** 该 `AudioCapture` 引擎插件是必需依赖项。它可能已在项目的插件配置中被禁用。

**修复：** 打开 **Edit > Plugins**，搜索 `Audio Capture`，并将其启用。重启编辑器。

**验证：** Convai 插件无错误地加载。检查输出日志中是否有 `LogConvai` 启动时的消息——不应出现缺失模块错误。

### 插件可在 Windows 上加载，但在 Android 上不可用

**症状：** 该插件可在 Windows 编辑器和 Windows 打包版本中正常工作，但在为 Android 目标打包时无法加载或导致错误。

**原因——缺少 Android SDK 或 NDK 配置：** 当未配置 Android NDK 或 SDK 路径，或者 `AndroidPermission` 插件依赖项在项目中被禁用时，可能会导致打包失败。

**修复：**

1. 确认 Android NDK 和 SDK 路径已在 **编辑 > 项目设置 > 平台 > Android SDK**.
2. 打开 **Edit > Plugins**，搜索 `Android Permission`中设置，并将其启用。
3. 重新为 Android 目标构建项目。

**验证：** 打包日志完成时，不会出现针对 `Convai` 或 `ConvaiVisionBase`.

***

**原因——APK 中缺少本机库：** 插件的 Android APL 会复制 `libconvai_client.so`, `libconvai_http_helper.so`，以及 `libwebrtc.jar` 到 Android 构建中。如果自定义打包步骤删除了这些文件，实时连接在设备上可能会失败。

**修复：** 这由插件的 `Convai_AndroidAPL.xml`。如果你看到原生加载失败，请确认：

1. 插件的 `Convai_AndroidAPL.xml` 文件位于 `Plugins/Convai/Source/Convai/` 且未被删除或修改。
2. 你的 ProGuard 或 R8 配置没有覆盖插件插入的保留规则。APL 包含适用于 WebRTC JNI 类和本机方法的规则：

```proguard
-keepattributes Signature
-dontskipnonpubliclibraryclassmembers
-keep class **.jni_zero.** { *; }
-keep class **.webrtc.** { *; }
-keepclasseswithmembernames class * {
    native <methods>;
}
```

**验证：** 运行 `adb shell ls /data/app/<your.package.name>/lib/arm64/` 在安装 APK 后。你应该会看到 `libconvai_client.so` 和 `libconvai_http_helper.so` 被列出。

{% hint style="danger" %}
删除 `Intermediate/` 和 `Binaries/` 文件夹会强制进行完全重新编译，并且可能解决损坏的构建状态——但这只应作为最后手段。在删除这些文件夹之前，请关闭编辑器和 IDE，因为打开的文件句柄可能会导致删除失败，或使项目处于部分清理的状态。请先在 IDE 中重新构建，然后再重新启动编辑器。
{% endhint %}

### 下一步

{% content-ref url="/pages/f1b3d71c37ea498f3d6d84fdf60594d3020ae6bf" %}
[连接和 API 密钥问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md)
{% endcontent-ref %}

{% content-ref url="/pages/76a35097e5aafc7db6e701235cba4c330c02ad3a" %}
[诊断和日志导出](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.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-unreal-engine-plugin/troubleshooting/installation-and-plugin-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.