> 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/unity-plugin/troubleshooting-guide.md).

# 故障排除指南

## 常见问题（FAQ）

### 问：我看不到 Convai 菜单。

答：请检查控制台中是否有任何错误。Unity 需要能够编译所有脚本，才能显示任何自定义编辑器菜单选项。解决所有控制台错误将修复此问题。

### 问：我的控制台里有很多错误。

答：主要有两个问题会导致控制台中出现错误，这些错误可能源自 Convai Unity 插件。你可以使用下面的链接快速修复它们。

1. [禁用程序集验证](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/enabled-assembly-validation.md)
2. [缺少 Newtonsoft Json](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/missing-newtonsoft-json.md)

### 问：我正在和角色对话，但我看不到用户转录，而且角色似乎没有连贯地回应我说的话。

答：这可能表示麦克风有问题。请确保麦克风已正确连接。你还需要确保这些应用程序有权访问菜单。

[麦克风权限问题](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/microphone-permission-issues.md)

### 问：我的角色动画看起来非常奇怪。

答：我们正在使用的动画 Avatar 可能与角色网格不兼容。修复这一点可以解决问题。

[默认动画不兼容](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/default-animations-incompatibility.md)

### 问：Mobile Transcript UI 中有两个设置面板按钮。

答：如果你使用的是 Unity 2021，可能会出现意外的 prefab 变体问题。这是因为 Unity Mobile Transcript UI 是主转录 UI prefab 的变体。随着 Unity 2022 中 Prefab 系统的更改，它在 Unity 2022 中可以正常工作。如果你使用的是 Unity 2021，可能会遇到 prefab 相关问题。你可以移除多余的设置面板按钮来解决此问题。

### 问：唇形同步非常微弱或不可见。

**答：** 我们正在使用的动画可能正在修改面部动画。编辑动画以移除面部动画应能修复任何与唇形同步相关的问题。

[动画具有面部 Blendshape](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/animations-have-facial-blendshapes.md)

**答：** 该脚本还要求 Avatar 不要映射到下颌骨，这样它才能自行操控下颌骨。

[头像中的下颌骨未解锁](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/jaw-bone-in-avatar-is-not-free.md)

### **问：我在使用 `grpc_csharp_ext.bundle` DLL 时在 MacOS 的 Unity 编辑器中遇到安全权限问题**

**答：** macOS 的严格安全措施可能会阻止某些未签名的外部 DLL。要解决此问题，你可以在“安全性与隐私”设置中手动允许该 DLL，通过终端修改 Gatekeeper 的设置，确保该 DLL 的文件权限正确，检查其在 Unity 中的设置，并更新 Unity 的 Player Settings 中的 Mac Configuration。

[macOS 权限问题](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/troubleshooting-guide/macos-permission-issues.md)

### **问：我在为 macOS（Intel64+Apple Silicon 构建）构建 Unity 项目后，无法与我的角色对话，尤其是在 Intel Mac 上**

**答：** 问题根源在于 `grpc_csharp_ext.bundle` 在 Unity 中用于联网的。此 DLL 有针对 Intel 和 Apple Silicon 架构优化的独立版本。在尝试创建同时适用于两者的通用构建时，会出现兼容性问题，尤其是在 Intel Mac 上。目前，最好的解决方案是使用针对每种架构的独立 Standalone 构建设置。

[为 macOS 通用应用构建](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin/building-for-supported-platforms/microphone-permission-issue-on-intel-macs-with-universal-builds.md)

## 错误索引

请参考此表以快速定位我们最常见的错误。

<table><thead><tr><th width="160">名称</th><th width="232">示例错误</th><th width="211">错误原因</th><th></th><th data-hidden>示例错误日志</th><th data-hidden>解决方案链接</th><th data-hidden>原因</th></tr></thead><tbody><tr><td>已启用程序集验证</td><td><pre data-overflow="wrap"><code>由于错误，程序集 'Assets/Convai/Plugins/Grpc.Core.Api/lib/net45/Grpc.Core.Api.dll' 将不会被加载： 
Grpc.Core.Api 引用了强命名的 System.Memory 程序集引用：4.0.1.1，项目中找到的是：4.0.1.2。
</code></pre></td><td>Unity 默认会检查所包含程序集的精确版本号。对于我们的插件来说，这并非必要，因为我们使用的是最新库。</td><td><a data-mention href="/pages/428b3143baf96e0551a6f263ade83abcfce26016">/pages/428b3143baf96e0551a6f263ade83abcfce26016</a></td><td>由于错误，程序集 'Assets/Convai/Plugins/Grpc.Core.Api/lib/net45/Grpc.Core.Api.dll' 将不会被加载：Grpc.Core.Api 引用了强命名的 System.Memory 程序集引用：4.0.1.1，项目中找到的是：4.0.1.2。</td><td><a data-mention href="/pages/428b3143baf96e0551a6f263ade83abcfce26016">/pages/428b3143baf96e0551a6f263ade83abcfce26016</a></td><td>Unity 默认会</td></tr><tr><td>缺少 Newtonsoft Json</td><td><pre data-overflow="wrap"><code>Assets\Convai\Plugins\GLTFUtility\Scripts\Spec\GLTFPrimitive.cs(8,4)：错误 CS0246：找不到类型或命名空间名“JsonPropertyAttribute”（是否缺少 using 指令或程序集引用？）
</code></pre></td><td>我们的插件需要 Newtonsoft Json 作为依赖项。它通常作为 Unity 的一部分存在，但有时也可能缺失。</td><td><a data-mention href="/pages/2080494ca1e8b42b0c13e93e10dd7a8d8dddc9a7">/pages/2080494ca1e8b42b0c13e93e10dd7a8d8dddc9a7</a></td><td></td><td></td><td></td></tr><tr><td>缺少 Animation Rigging</td><td><pre data-overflow="wrap"><code>Assets\Convai\Scripts\Utils\HeadMovement.cs (2,30)：错误 CS0234：命名空间“UnityEngine.Animations”中不存在类型或命名空间名“Rigging”（是否缺少程序集引用？）
</code></pre></td><td>我们使用 Animation Rigging 包进行眼睛和颈部跟踪。如果 Unity 没有自动添加它，我们需要从包管理器中手动添加。</td><td></td><td></td><td></td><td></td></tr><tr><td>麦克风权限问题</td><td>麦克风图标亮起了，但聊天 UI 中没有用户转录。角色似乎没有回应用户所说的话。</td><td>该插件需要麦克风访问权限，而这有时默认并未启用。</td><td><a data-mention href="/pages/fa8bcea1d82b0f2c20bd04ecef602534d09eb567">/pages/fa8bcea1d82b0f2c20bd04ecef602534d09eb567</a></td><td></td><td></td><td></td></tr><tr><td>默认动画不兼容</td><td>插件自带的默认动画似乎有问题。双手似乎与身体相交。</td><td>动画 Avatar 与角色网格不兼容。</td><td><a data-mention href="/pages/b6eab1f53a01ae1a6f35ac6d107dc5794d6fc327">/pages/b6eab1f53a01ae1a6f35ac6d107dc5794d6fc327</a></td><td></td><td></td><td></td></tr><tr><td>动画包含面部 BlendShape</td><td>角色的唇形同步要么不可见，要么非常微弱。</td><td>某些类型的动画会控制面部 BlendShape。这些动画会阻止唇形同步脚本正确编辑面部 BlendShape。</td><td><a data-mention href="/pages/4f366f5958b1e4e5d02f62175b0d9a0f94fbb32b">/pages/4f366f5958b1e4e5d02f62175b0d9a0f94fbb32b</a></td><td></td><td></td><td></td></tr><tr><td>Avatar 中的下颌骨未解除绑定</td><td>角色的唇形同步要么不可见，要么非常微弱。</td><td>角色的动画 Avatar 可能正在使用下颌骨。如果我们将映射自由设置为无，脚本就能够自由操控下颌骨。</td><td><a data-mention href="/pages/5f34cc332185ed7b93e31f536b96224b0a85cdc1">/pages/5f34cc332185ed7b93e31f536b96224b0a85cdc1</a></td><td></td><td></td><td></td></tr><tr><td>Mac 安全权限问题</td><td>与以下项相关的安全权限问题： <code>grpc_csharp_ext.bundle</code> MacOS 上 Unity 中的 DLL。</td><td>macOS 的安全协议可能会阻止某些未签名的外部 DLL，例如 <code>grpc_csharp_ext.bundle</code>，在 Unity 中正常运行。</td><td><a data-mention href="/pages/b2ce8620e855c3055d169ab23371e6cb73b9b220">/pages/b2ce8620e855c3055d169ab23371e6cb73b9b220</a></td><td></td><td></td><td></td></tr><tr><td>Unity 中 Intel Mac 上通用构建的麦克风权限问题</td><td>未弹出麦克风访问请求</td><td>Intel 和 Apple Silicon 版本的 <code>grpc_csharp_ext.bundle</code> 在尝试进行通用构建时。</td><td><a data-mention href="/pages/357c294dd669ecd78d36d03645aa3bac2fc774ae">/pages/357c294dd669ecd78d36d03645aa3bac2fc774ae</a></td><td></td><td></td><td></td></tr></tbody></table>

如有其他问题，欢迎通过以下方式联系我们： [Convai 开发者论坛](https://forum.convai.com/).


---

# 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/unity-plugin/troubleshooting-guide.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.