本页由英文机器翻译而成。阅读英文原文。

故障排查

解决常见的 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 服务器（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 是从其他文件夹启动的。 只有当客户端在 Unity 项目文件夹中运行时，才会读取 .mcp.json 或 .cursor/mcp.json 等项目级配置。
  • 在 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 会在切换账号前询问。

账号的会话与设备管理见 Authentication。

本地 MCP 服务器无法启动（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 服务器显示为 External。找到该进程：

netstat -ano | findstr :<port>
lsof -i :<port>

停止该进程，或者断开连接并在 Server URL 中输入另一个端口（例如 http://localhost:25000），然后再次点击 Configure，让 agent 使用新端口。

编译期间断开连接

每次代码更改后以及进入 Play 模式时，Unity 都会重新加载脚本。插件会在重载前断开连接，并在重载后重新连接，因此短暂的 "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 的情况下以无头模式启动；unity-mcp-cli open --headless 已经这样做了。
  • 自定义工具抛出线程错误。 将 Unity API 调用包裹在 MainThread.Instance.Run 中。参见 Custom tools。

unity-mcp-cli 问题

  • open 停在 "Enter Safe Mode?"。 CLI 会自动点击 Ignore。在 macOS 上请为终端授予辅助功能（Accessibility）权限；在 Linux 上请安装 xdotool。
  • exec 等待后放弃。 项目已在某个并非由 CLI 启动的 Editor 中打开，且其插件没有在本地响应（例如它连接到了云端）。请连接插件、将其切换到 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。