# 安装 — Unity · AI Game Developer Wiki

通过桌面应用、unity-mcp-cli、OpenUPM 或 .unitypackage 安装器，在 Unity 项目中安装 Unity MCP（AI Game Developer）。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unity/installation)。

本页介绍向 Unity 项目添加 Unity MCP 插件的所有方式、每种方式会对项目做出哪些改动，以及如何再次移除该插件。所有方式安装的都是来自 OpenUPM registry 的同一个包 `com.ivanmurzak.unity.mcp`，因此你可以选择最符合自己工作流程的一种。

## 系统要求

- **Unity 2022.3 或更高版本。** 该包声明 `2022.3` 为最低版本；支持 Unity 6 各版本。
- **项目路径中不能包含空格。** `C:/Projects/MyGame` 可以，`C:/My Projects/My Game` 不行。路径包含空格时，插件会在启动时记录一条错误。
- **Windows 上项目路径要短。** 插件会将其 NuGet DLL 复制到 `Assets/Plugins/NuGet`。如果生成的路径会超过 Windows 的 260 字符限制，安装就会停止，并要求你把项目移动到更短的文件夹。
- **首次打开时需要联网。** 插件会从 NuGet 下载其 .NET 依赖项，在 Custom 模式下还会从 GitHub 下载其 MCP 服务器二进制文件。
- 仅适用于 `unity-mcp-cli`：**Node.js** `^20.19.0` 或 `>=22.12.0`。

## 方式 1：AI Game Dev 桌面应用（推荐）

[AI Game Dev 应用](https://ai-game.dev/docs/app) 会为你安装并连接插件，无需终端，也无需在机器上安装 Node.js。

1. [下载该应用](https://ai-game.dev/zh-hans/download) 并使用你的 ai-game.dev 账号登录。
2. 在应用中打开你的 Unity 项目文件夹。应用会检测到它是一个 Unity 项目。
3. 点击 **Install Package**。应用会将插件以 OpenUPM 上最新发布的版本添加到 `Packages/manifest.json`，并且绝不会降级你已有的更高版本。从应用创建的项目会自动获得该插件。
4. 从应用中打开编辑器。应用会传递你的会话，因此插件通过 ai-game.dev 连接，无需单独登录。

该应用还会安装扩展并自行运行 AI agent，因此你不需要单独的 MCP 客户端。详情见应用 wiki：[安装](https://ai-game.dev/zh-hans/docs/wiki/app/installation) 和 [项目与引擎](https://ai-game.dev/zh-hans/docs/wiki/app/projects-and-engines)。

## 方式 2：unity-mcp-cli

`unity-mcp-cli` 会直接编辑 `Packages/manifest.json`，因此无需打开 Unity：

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
```

你也可以不进行全局安装就直接运行它：

```bash
npx unity-mcp-cli install-plugin ./MyUnityProject
```

`install-plugin` 会添加包含作用域 `com.ivanmurzak` 和 `extensions.unity` 的 OpenUPM scoped registry，将 `com.ivanmurzak.unity.mcp` 以 OpenUPM 上的最新版本添加到 `dependencies`，并且绝不会降级已安装的更高版本。传入 `--plugin-version <version>` 可固定版本。在项目文件夹中运行该命令时，路径是可选的。

该 CLI 还可以先安装 Unity 并创建项目：

```bash
unity-mcp-cli install-unity
unity-mcp-cli create-project ./MyUnityProject
```

如果缺少 Unity Hub，CLI 会安装它。之后请在 Unity 中打开项目，以便 Package Manager 解析该包。所有命令见 [CLI 参考](https://ai-game.dev/zh-hans/docs/wiki/unity/cli)。

## 方式 3：OpenUPM

安装 [OpenUPM CLI](https://openupm.com/) 后，在项目文件夹中运行：

```bash
openupm add com.ivanmurzak.unity.mcp
```

如果不使用 OpenUPM CLI，请自行将 registry 和依赖项添加到 `Packages/manifest.json`。请使用 [OpenUPM 包页面](https://openupm.com/packages/com.ivanmurzak.unity.mcp/) 上显示的版本：

```json
{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.ivanmurzak", "extensions.unity"]
    }
  ],
  "dependencies": {
    "com.ivanmurzak.unity.mcp": "1.6.2"
  }
}
```

请将这些条目合并到现有文件中，不要替换其他依赖项。

## 方式 4：.unitypackage 安装器

1. 下载 [AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)。
2. 在 Unity 中打开你的项目。
3. 双击该文件，或使用 **Assets > Import Package > Custom Package** 并选择它。
4. 点击 **Import**。

该安装器是一个小型的编辑器脚本。它会将 OpenUPM scoped registry 和插件依赖项添加到 `Packages/manifest.json`，然后从 `Assets` 中删除自身。随后 Package Manager 会下载真正的包。

## 首次打开时会发生什么

包到位后，插件会自行完成准备工作：

- 它会从 NuGet 下载所需的 .NET 库（MCP 插件库、ReflectorNet、RQL、SignalR、System.Text.Json 等）到 `Assets/Plugins/NuGet`，缓存位于 `Library/NuGetCache`，Unity 会重新编译一次。如果这些 DLL 出现不同步，请使用 **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**。
- 它会从 GitHub 下载适用于你所在平台的 `gamedev-mcp-server` 二进制文件到 `Library/mcp-server/<platform>/`（例如 `win-x64`、`osx-arm64` 或 `linux-x64`）。该服务器仅在 Custom 模式配合 HTTP 传输时启动；默认的 Cloud 模式不会启动本地服务器。
- **AI Game Developer** 窗口会在 **Window > AI Game Developer — MCP** 下可用（快捷键 Ctrl+Alt+A，macOS 上为 Cmd+Option+A）。Scene View 工具栏也会新增一个 **AI** 覆盖按钮用于打开它。

默认情况下 `Library/` 不纳入版本控制，因此服务器二进制文件永远不会被提交。在 CI 环境中，插件会跳过服务器的下载和启动。

## 更新插件

当 OpenUPM 上有更新版本时，插件会在编辑器启动时显示更新弹窗。你也可以通过 **Tools > AI Game Developer > Updates > Check for Updates** 手动检查。要更新，可在 Package Manager 中更改版本、重新运行 `unity-mcp-cli install-plugin`（它会安装最新版），或让桌面应用更新它。

如果团队中由一人负责插件版本，请打开 **Edit > Project Settings > AI Game Developer** 并启用 **Disable update notifications for the entire team**。该设置保存在 `ProjectSettings/AI-Game-Developer-UpdateSettings.asset` 中；请提交该文件。同样的开关也位于 **Tools > AI Game Developer > Updates > Disable Update Notifications (Team)**。

## 卸载

1. 打开 **Window > Package Manager**，选择 **AI Game Developer — MCP** 并点击 **Remove**，或运行 `unity-mcp-cli remove-plugin ./MyUnityProject`。CLI 会保留 scoped registry，因为其他包可能会用到它。
2. 关闭 Unity，删除 `Assets/Plugins/NuGet` 文件夹及其 `Assets/Plugins/NuGet.meta` 文件。

## 后续步骤

- [快速开始](https://ai-game.dev/zh-hans/docs/wiki/unity/getting-started)：连接 AI 客户端并运行你的第一个提示词。
- [扩展](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)：添加用于 Cinemachine、ProBuilder、Tilemap 等的工具包。
- 如果安装过程中出现问题，请参阅 [故障排除](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)。

---

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

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