企业官网建设流程全解析

Unity MCP 连接排错与配置调优踩坑清单：4 个高频场景一次讲清

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp

Unity MCP（AI 助手与 Unity 编辑器之间的 MCP 服务器桥梁）最常见的抱怨就两件事：连不上、启动慢。下面按你实际会遇到的场景拆成 4 个问题，每个问题都给出现象、根因和验证方法，对照自查即可。

同时开两个 Unity 工程，客户端连错实例

现象：开着工程 A，又打开工程 B，AI 客户端有时答的是 A 的场景信息；或者 B 启动后状态一直不绿。

根因：每个工程的桥接器（Unity 内部监听 socket 的进程）默认都从 6400 端口起步找空位。PortManager.cs（端口自动探测与持久化逻辑） 的逻辑是：先试 6400，被占就从 6401 向上最多扫 100 个端口，找到后把端口连同工程路径写进~/.unity-mcp/下的 JSON，下次同一工程复用它。所以"连错实例"多半是客户端缓存了旧端口。

动手改：

1. 打开 Window 菜单下的 MCP for Unity 面板，切到 Connection 页签。
2. 看 Unity Socket Port 输入框——这就是当前工程实际在用的端口，多个工程要错开时，在这里直接改成想要的端口。
3. 按回车或点别处保存；若端口已被占，会弹出 "Port Unavailable" 提示，换一个再存。
4. 改完到 AI 客户端那边重启会话，让它重新发现实例。

怎么确认好了：状态标签显示 Session Active（项目名），且输入框显示的端口和你手动设的一致。

重编译后卡在 Resuming... 不动

现象：改了一段 C# 脚本触发域重载，面板状态停在 Resuming...，客户端短暂断连，过一会儿又自己好了。

根因：域重载时旧监听进程释放 socket 有延迟，Windows 和 macOS 上尤其明显。桥接器会先坚持原端口重试，持续 3 秒（BusyPortFallbackWindowSeconds）才判定被外部占用、换一个新端口；这期间单次健康检查会闪红灯，但属于正常抖动。

动手改：

1. 先等 3~5 秒，多数情况状态会自己转回 Session Active。
2. 仍卡住就点 End Session 再点 Start Session 手动重连。
3. 反复出现的话，检查是不是有残留的 Unity 进程占着端口——任务管理器里清掉即可。

怎么确认好了：健康指示不再闪红灯，端口输入框即使从 6402 跳到 6403 也属预期，只要最终稳定即可。

连不上时怎么定位到底卡在哪

现象：客户端报 "No Unity Instances Found"，或工具列表是空的，但你说不清是桥没起、服务器没起、还是配置错。

根因：这类问题信息量不足——桥接器、Python 服务器进程、客户端配置三层任何一层断了都长一个样，必须开诊断日志才能分层看。

动手改：

1. 切到面板的 Advanced 页签，勾选 Debug Logs，详细日志会打进 Unity Console。
2. 点 Test Connection 按钮手动触发一次健康检查。
3. 读 Advanced 页签的健康状态文字，对照判断：Unknown 是没检查过，Ping Failed 是网络层不通，Unhealthy 是桥在但协议握手失败。
4. 需要追踪具体工具调用时，再勾上 Log Record，每次工具执行（工具名、action、状态、耗时）会写进Assets/UnityMCP/Log/mcp.log。McpAdvancedSection.cs（Advanced 面板的全部开关定义） 里每个开关的 tooltip 都写清了它管什么。

怎么确认好了：Test Connection 后健康状态变 Healthy，Console 里能看到完整的端口探测和握手日志；排查完记得关掉 Debug Logs，避免刷屏拖慢编辑期。

把启动速度再压一压：只动这三个开关

现象：服务器冷启动慢、日志把工程撑得越来越脏、每次开工程都要手动点连接。

根因：慢的开销主要在服务器首次拉取依赖和 uvx 缓存构建；烦的开销主要在手动步骤和日志堆积。

动手改（都在 Advanced 页签，按需勾选）：

改完重启编辑器生效。多工程并行开发时，给每个工程在上一节提到的端口框里固定不同端口，能省掉每次冷启动的端口重探测。

怎么确认好了：打开编辑器几秒后状态自动变 Session Active，不用碰任何按钮；用 Log Record 的耗时记录确认慢在哪一步工具调用上，而不是凭感觉加配置。

还有更具体的报错（macOS 的 ICU 库缺失、WSL2 跨系统桥接、uv 路径选错等），去仓库的 website/docs/guides/troubleshooting.md（常见问题排错文档） 按客户端名字找对应小节，文档更新比博客快。

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp