# 故障排查 — Godot · AI Game Developer Wiki

解决常见的 Godot MCP 问题：插件无法加载或编译、Extensions 列表为空、工具缺失、重载报错以及 .NET 10 崩溃。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/godot/troubleshooting)。

大多数 Godot MCP 问题都源于以下四种情况之一：Godot 构建版本不对、`.csproj` 与插件不匹配、C# 程序集没有构建，或者 AI 客户端没有指向正确的服务器。请按你看到的现象找到对应小节逐一排查。如果仍然卡住，可把停靠面板的 **Log Level** 调到 `Debug`，复现问题并查看 Output 面板。

## 插件无法加载

### 首次打开时提示“Unable to load addon script”

Godot 编辑器一启动就会实例化已启用的插件。对于一个从未构建过的 C# 项目，第一次打开时还没有任何程序集，因此 Godot 会报告无法加载 `res://addons/godot_mcp/Editor/GodotMcpPlugin.cs` 并禁用该插件。

修复方法：先构建，然后在 **Project, Project Settings, Plugins** 中重新启用插件。

```bash
godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject
```

`godot-cli open` 总是先构建再启动编辑器，因此可以避免这个问题。

### 插件无法编译

- 你使用的是标准版 Godot。Godot MCP 需要 Godot 4.3 或更新版本的 **.NET (mono)** 构建。
- `.csproj` 缺少 NuGet 包，或者其中的版本与你安装的插件不一致。请重新运行 `godot-cli install-plugin`，或从[安装](https://ai-game.dev/zh-hans/docs/wiki/godot/installation#nuget-packages)复制对应插件版本的那段配置。
- 项目中没有 `.csproj`。请在 Godot 中创建 C# 解决方案，或对新项目使用 `godot-cli create-project --dotnet`。
- 未安装 .NET 8 SDK，或它不在 `PATH` 中。

### 找不到某个 NuGet 程序集（FileNotFoundException）

Godot 编辑器本身不会解析项目的 NuGet 包；插件会通过读取构建产物的 `.deps.json` 和你的 NuGet 缓存来完成解析。如果仍有程序集找不到，请运行 `dotnet restore` 并重新构建。如果问题依旧，请删除 `.godot/mono/temp/obj` 和 `.godot/mono/temp/bin` 后重新构建：陈旧的构建输出通常是原因所在。

## 用 Play 启动的游戏无法创建 C# 脚本

症状：在出现指名某个 `EditorPlugin` 类的 `TypeLoadException` 之后，所有 C# 脚本都报“Cannot instantiate C# script because the associated class could not be found”。你的 `.csproj` 缺少 `<EnableDynamicLoading>true</EnableDynamicLoading>`，导致包程序集没有复制到游戏程序集旁边。请把它加到 `<TargetFramework>` 所在的 `<PropertyGroup>` 中并重新构建。`godot-cli install-plugin` 和 `create-project` 会自动为你设置。

## Extensions 列表为空

停靠面板从你编译后的项目中读取扩展目录。你的 `.csproj` 需要包含下面这一行，然后重新构建：

```xml
<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
```

`LogicalName` 必须完全等于 `Godot-MCP.extensions.catalog.json`。如果停靠面板提示找不到 `.csproj`，说明插件不在 Godot C# 项目中。参见[扩展](https://ai-game.dev/zh-hans/docs/wiki/godot/extensions#catalog)。

## 编辑器无法连接

- **云模式，未登录。** 在停靠面板中点击 **Authorize**，或运行 `godot-cli login`。停靠面板会显示你的登录状态。
- **被环境变量覆盖。** 出现黄色提示“Overridden by environment (GODOT\_MCP\_\*)”表示某个变量或 `.env` 文件强制指定了模式或主机，此时在停靠面板中修改无效。请删除或修改该变量。
- **自定义模式，没有服务器。** 在停靠面板中点击 **Start Server**，或启动你自己的服务器。离线时，服务器下载会失败，Output 面板中会出现警告，并且不会启动本地服务器；请改用云模式，或运行你已有的服务器。
- **自定义模式，在远程主机上使用 `oauth`。** 插件只会把账户令牌发送给 localhost 服务器。对于其他主机，请设置 `GODOT_MCP_TOKEN`，否则连接会失败并提示“Refusing to send your ai-game.dev account token”。

可在终端中用 `godot-cli status ./MyGodotProject` 和 `godot-cli wait-for-ready ./MyGodotProject` 检查。

## AI 智能体看不到 Godot 工具

- 智能体在其配置写入之前就已启动。请重启它，或重新加载它的 MCP 服务器。
- Claude Code 会读取其启动目录下的 `.mcp.json`。请在项目文件夹中启动它，或把配置写到你的启动目录。
- 多个编辑器同时连接，而智能体使用的是不带项目标识的 `/mcp` URL。请使用 `setup-mcp` 默认写入的带项目标识的 URL，这样智能体才能连到正确的项目。
- 配置指向的服务器与编辑器使用的不是同一个（云端 vs 本地）。更改模式后请重新运行 `godot-cli setup-mcp <agent>`，或在停靠面板中点击 **Reconfigure**。
- 工具被隐藏了。请查看停靠面板的 MCP 功能区域，或运行 `godot-cli configure --list`。隐藏的工具不会向 agent 列出。

## C# 重新构建期间工具调用失败

构建出的 DLL 发生变化后（`script-build`、Build 按钮或 `dotnet build`），Godot 会在约半秒后重新加载项目的 C# 程序集。该插件是此程序集的一部分，因此它会被销毁、重新构建，并在几秒内重新连接。在重新加载前后，新的调用会被拒绝并返回可重试的错误（“Godot is about to reload the project's C# assembly … Retry in a few seconds”）。请稍等后重试；`script-build` 会在重新加载完成后返回结果。

## 在 .NET 10 上重新加载后编辑器崩溃或卡死

这是 .NET 运行时的一个 bug（dotnet/runtime#135441）。在 .NET 10 的维护修复版本发布之前，请为编辑器进程设置以下环境变量，并重启 Godot：

```text
DOTNET_ThreadPool_ThreadsToKeepAlive=-1
```

在 Windows 上，可以用 `setx DOTNET_ThreadPool_ThreadsToKeepAlive -1` 进行设置。由 `godot-cli open` 或 `exec` 启动的编辑器会自动获得该设置。当你的 .NET 运行时包含此修复后，请移除该变量。

## 调用发往了旧的构建版本

如果工具调用的表现像是你代码的旧版本，那么同一个项目可能连接了多个编辑器，例如一个被遗忘的无头编辑器。请关闭多余的编辑器（`godot-cli close --owned-only` 会关闭由 `godot-cli` 启动的编辑器），只保留一个编辑器连接。

## 构建失败并报 MissingMethodException

项目的 `Godot.NET.Sdk` 版本应与你所运行的编辑器一致。基于 4.3 构建的项目在 4.4 或更新版本的编辑器上（API 已发生变化）可能抛出 `MissingMethodException`。请把 `.csproj` 中 `Sdk="Godot.NET.Sdk/…"` 的版本改为你的编辑器版本，然后重新构建。

## 仍然卡住

请查看[常见问题](https://ai-game.dev/zh-hans/docs/wiki/godot/faq)和站点[常见问题](https://ai-game.dev/docs/faq)，或者到 [Godot-MCP issue tracker](https://github.com/IvanMurzak/Godot-MCP/issues) 上报告问题，并附上 Output 面板日志以及你的 Godot、.NET 和插件版本。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/godot/troubleshooting

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/godot/troubleshooting