本頁面由英文機器翻譯而成。閱讀英文原文。

疑難排解

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

更新於 2026年11月4日 以 Markdown 檢視

本頁彙整使用 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。

本機 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。請找出該程序：

netstat -ano | findstr :<port>
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。

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 或全站 FAQ。