# 故障排查 — 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 服务器（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](https://ai-game.dev/docs/auth)。

## 本地 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**。找到该进程：

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

```bash
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](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools#main-thread)。

## 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](https://ai-game.dev/zh-hans/docs/wiki/unity/faq) 或全站 [FAQ](https://ai-game.dev/docs/faq)。

---

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

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