# 疑難排解 — Unity · AI Game Developer Wiki

解決常見的 Unity MCP 問題：AI 用戶端中沒有工具、登入與連線錯誤、伺服器下載失敗、NuGet DLL 錯誤，以及連接埠衝突。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/unity/troubleshooting)。

本頁彙整使用 Unity MCP 時最常遇到的問題，以及對應的解決方式。請先從快速檢查清單開始；若仍無法解決，請在下方尋找符合的症狀。

## 快速檢查清單

1. 開啟 **Window > AI Game Developer — MCP** 並查看時間軸：**Unity**、**MCP server** 與 **AI agent** 都應顯示為綠色。
2. 檢查 Unity Console 是否有錯誤。專案中任何一處編譯錯誤都會導致外掛的編輯器腳本無法載入。
3. 執行 `unity-mcp-cli status ./MyUnityProject`，查看 Unity 是否正在執行，以及可連上哪一個伺服器。
4. 任何設定變更後，請重新啟動你的 AI 用戶端。
5. 確認外掛與你的擴充功能都是最新版本。

## AI 用戶端沒有顯示任何 Unity 工具

- **用戶端在 Unity 就緒前就已連線。** 請在用戶端重新連線 MCP server（在 Claude Code 中為 `/mcp`），或在視窗顯示 **Connected** 後重新啟動用戶端。
- **用戶端尚未設定，或使用舊的設定。** 請在視窗中為你的 agent 點選 **Configure**（或 **Reconfigure**），或執行 `unity-mcp-cli setup-mcp <agent> .`，然後重新啟動用戶端。
- **Cloud 模式尚未登入。** 視窗會顯示「Authorization Required」。請點選 **Authorize**，並在瀏覽器中核准代碼。
- **同時開啟了多個專案。** 未釘選的 `https://ai-game.dev/mcp` URL 可能會導向另一個 Editor。請使用 **Configure** 所寫入的釘選 URL。
- **agent 從其他資料夾啟動。** 像是 `.mcp.json` 或 `.cursor/mcp.json` 這類專案層級設定，只有在用戶端於 Unity 專案資料夾中執行時才會被讀取。
- **在 VS Code 中**，請將 Copilot Chat 切換到 **Agent** 模式。

## Cloud 登入問題

- **「Authorization Required」反覆出現。** 你的憑證已過期或被撤銷。請再次點選 **Authorize**，或執行 `unity-mcp-cli login --force`。
- **「Connection Required」。** 登入成功，但 Unity 並未連線。請點選 **Connect**。
- **登入到錯誤的帳號。** 請點選 **Revoke**（這會登出此機器上所有 AI Game Dev 工具），再以正確的帳號點選 **Authorize**。`unity-mcp-cli login` 會在切換帳號前詢問。

帳號的 session 與裝置管理請參閱 [Authentication](https://ai-game.dev/docs/auth)。

## 本機 MCP server 無法啟動（Custom 模式）

- **二進位檔尚未下載。** 它會下載到 `Library/mcp-server/<platform>/`。若下載失敗（離線、防火牆、代理伺服器），視窗會顯示「Server binary error」以及 **Download / Retry server** 按鈕。你也可以使用 **Tools > AI Game Developer > Server > Download Binaries**。
- **防毒軟體封鎖了執行檔。** 請在安全軟體中允許 `gamedev-mcp-server`，然後重試。
- **傳輸方式為 stdio。** 使用 stdio 時，AI agent 會自行啟動伺服器，因此 **Start** 按鈕會停用。若想由 Unity 啟動，請切換為 `http`。
- **查看伺服器日誌。** 請使用 **Tools > AI Game Developer > Server > Open Logs** 與 **Open Log Errors**。
- **直接測試伺服器。** **Tools > AI Game Developer > Server > Launch MCP Inspector** 會對本機伺服器開啟 MCP Inspector（僅限 HTTP 傳輸；需要 Node.js）。

## 連接埠衝突

每個專案會依其路徑取得 20000 到 29999 之間的固定連接埠。若該連接埠已被其他程式佔用，視窗會將 MCP server 顯示為 **External**。請找出該程序：

```powershell
netstat -ano | findstr :<port>
```

```bash
lsof -i :<port>
```

請停止該程序，或中斷連線並在 **Server URL** 中輸入其他連接埠（例如 `http://localhost:25000`），然後再次點選 **Configure**，讓 agent 使用新的連接埠。

## 編譯期間連線中斷

Unity 在每次程式碼變更後以及進入 Play 模式時都會重新載入腳本。外掛會在重新載入前中斷連線，並在之後重新連線，因此短暫顯示「Disconnected」或「Connecting...」是正常的。重新載入期間正在進行的工具呼叫可能會失敗；請要求 agent 重試。

## 安裝後出現編譯錯誤或缺少 DLL

外掛會從 NuGet 下載其 .NET 相依性到 `Assets/Plugins/NuGet`。

- **出現缺少 McpPlugin、ReflectorNet 或 SignalR 型別的錯誤。** 請等待第一次匯入完成，然後使用 **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**。
- **Windows 上出現「Path too long」。** 即使已啟用長路徑，Unity 的執行環境仍無法開啟超過 Windows 260 字元路徑上限的 DLL。請將專案移到較短的路徑，例如 `C:/Projects/MyGame`。
- **完全重新安裝。** 關閉 Unity，刪除 `Assets/Plugins/NuGet` 及其 `.meta` 檔案，然後重新開啟專案。

## 專案路徑包含空格

若 Console 顯示「The project path contains spaces」，請將專案移到不含空格的資料夾。外掛會提出警告，因為這類路徑可能在使用時造成問題。

## 工具呼叫失敗或逾時

- **出現「object not found」之類的錯誤。** 請要求 agent 先查詢（例如使用 `rql-query`），而不是猜測名稱或路徑。資源路徑會以 `Assets/` 開頭。
- **長時間操作逾時。** 對於耗時的光照烘焙或大型測試執行，請在視窗中調高 **Tool timeout (ms)**（預設 300000）。
- **批次模式下截圖失敗。** 以 `-nographics` 啟動的 Editor 沒有圖形裝置。請在不加 `-nographics` 的情況下以 headless 啟動；`unity-mcp-cli open --headless` 已經這麼做了。
- **自訂工具拋出執行緒錯誤。** 請將 Unity API 呼叫包在 `MainThread.Instance.Run` 中。請參閱 [Custom tools](https://ai-game.dev/zh-hant/docs/wiki/unity/custom-tools#main-thread)。

## unity-mcp-cli 問題

- **`open` 停在「Enter Safe Mode?」。** CLI 會自動點選 **Ignore**。在 macOS 上請授予終端機「輔助使用」權限；在 Linux 上請安裝 `xdotool`。
- **`exec` 持續等待後放棄。** 專案已在非 CLI 啟動的 Editor 中開啟，且其外掛未在本機回應（例如已連線到 cloud）。請連線外掛、將其切換為 Custom，或傳入 `--url`。
- **`setup-skills` 失敗。** 它需要一個正在執行且外掛已連線的 Editor。請先執行 `open` 與 `wait-for-ready`。
- **在任何命令加上 `--verbose`** 即可取得詳細日誌。

## 完全重設

1. 關閉 Unity。
2. 刪除專案中的 `Library/mcp-server/`。
3. 重新開啟 Unity，並選擇 **Tools > AI Game Developer > Reset Config**。
4. 再次登入（Cloud）或啟動伺服器（Custom），然後為你的 agent 點選 **Configure**。
5. 重新啟動你的 AI 用戶端。

## 尋求協助

請使用 AI Game Developer 視窗底部的 **Help / Talk**（Discord）或 **Bug Report**（GitHub issues）。請附上你的 Unity 版本、作業系統、外掛版本（顯示於視窗中）、Console 中的錯誤，以及重現步驟。你也可以瀏覽 [FAQ](https://ai-game.dev/zh-hant/docs/wiki/unity/faq) 或全站 [FAQ](https://ai-game.dev/docs/faq)。

---

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

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