# 疑難排解 — 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-hant/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# 專案中。請參閱 [Extensions](https://ai-game.dev/zh-hant/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**。
- 工具已被隱藏。請檢查 dock 的 MCP features 區段，或執行 `godot-cli configure --list`。隱藏的工具不會列給 agent。

## C# 重建期間工具呼叫失敗

建置後的 DLL 變更約半秒後，Godot 會重新載入專案的 C# 組件（`script-build`、Build 按鈕或 `dotnet build`）。addon 屬於該組件的一部分，因此會被卸載、重建，並在幾秒內重新連線。重新載入前後，新的呼叫會被拒絕並回傳可重試的錯誤（「Godot is about to reload the project's C# assembly … Retry in a few seconds」）。請稍候再重試；`script-build` 會在重新載入後才送出結果。

## 在 .NET 10 上重新載入後編輯器崩潰或卡住

這是 .NET 執行階段的錯誤（dotnet/runtime#135441）。在 .NET 10 的維護更新修正推出前，請為編輯器行程設定這個環境變數，並重新啟動 Godot：

```text
DOTNET_ThreadPool_ThreadsToKeepAlive=-1
```

在 Windows 上可以用 `setx DOTNET_ThreadPool_ThreadsToKeepAlive -1` 設定。透過 `godot-cli open` 或 `exec` 啟動的編輯器會自動取得此設定。等你的 .NET 執行階段包含修正後，請移除這個設定。

## 呼叫送到舊的建置版本

如果工具呼叫的行為像是你程式碼的舊版本，可能是同一個專案連上了多個編輯器，例如忘記關閉的 headless 編輯器。請關閉多餘的編輯器（`godot-cli close --owned-only` 會關閉由 `godot-cli` 啟動的編輯器），只保留一個編輯器連線。

## 建置失敗並出現 MissingMethodException

專案的 `Godot.NET.Sdk` 版本應與你執行的編輯器相符。以 4.3 建置的專案，在 API 已變更的 4.4 或更新版編輯器上可能會擲出 `MissingMethodException`。請將 `.csproj` 中的 `Sdk="Godot.NET.Sdk/…"` 版本更新為你的編輯器版本，然後重新建置。

## 還是卡住

請查看[常見問題](https://ai-game.dev/zh-hant/docs/wiki/godot/faq)與網站的[常見問題](https://ai-game.dev/docs/faq)，或帶著 Output 面板的記錄檔，以及你的 Godot、.NET 與 addon 版本，到 [Godot-MCP 問題追蹤器](https://github.com/IvanMurzak/Godot-MCP/issues)回報問題。

---

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

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