# 安装 — Unreal Engine · AI Game Developer Wiki

使用 AI Game Dev 应用或 unreal-mcp-cli 为 Unreal Engine 5.5+ 安装 Unreal MCP 插件。包含环境要求、更新、卸载与 Fab 状态。

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

本页介绍如何将 Unreal MCP（面向 Unreal Engine 的 AI Game Developer 插件）安装到项目中。选择一种安装方式，按步骤操作，然后继续阅读[快速上手](https://ai-game.dev/zh-hans/docs/wiki/unreal/getting-started)。

## 环境要求

| 要求 | 说明 |
| --- | --- |
| Unreal Engine | 5.5 或更高版本。正式发布版本已针对 5.5、5.6、5.7 和 5.8 验证。 |
| 项目类型 | 一个 **C++ Unreal 项目**。插件包含需要针对你的项目编译的编辑器模块，因此项目必须能够构建 C++。 |
| C++ 工具链 | 你的 Unreal Engine 版本在你的平台上所需的编译器工具链（例如 Windows 上的 Visual Studio、macOS 上的 Xcode）。 |
| 操作系统 | Windows（x64）、macOS（Apple 芯片和 Intel）以及 Linux（x64）。发布包为以上每种系统都提供了对应的 bridge 构建。 |
| Node.js | 仅 `unreal-mcp-cli` 需要：`^20.19.0` 或 `>=22.12.0`。桌面应用不需要。 |
| .NET 9 SDK | 仅当你从源码构建 bridge 时才需要。打包安装已内置。 |

插件并未在其描述符中固定确切的引擎版本，因此同一个插件可以在更新的引擎版本上加载。

**注意：** 纯蓝图项目需要先有一个 C++ 模块才能构建插件。在 Unreal Editor 中添加任意 C++ 类（Tools、New C++ Class）即可将其转换为 C++ 项目，或使用 `unreal-mcp-cli create-project` 创建一个全新的 C++ 项目。

## 方式 1：AI Game Dev 桌面应用

桌面应用是最简单的方式。它内置了安装逻辑，因此你不需要 Node.js、npm 或终端。

1. 从[下载页面](https://ai-game.dev/zh-hans/download)安装 AI Game Dev。[应用安装指南](https://ai-game.dev/zh-hans/docs/wiki/app/installation)会带你完成整个过程。
2. 使用你的 ai-game.dev 账号登录。
3. 选择 **Open folder…** 并选中你的 Unreal 项目文件夹（即包含 `.uproject` 文件的文件夹）。应用会将其识别为 Unreal 项目。或者使用 **Create new project** 新建项目，此时插件会自动安装。
4. 点击侧边栏中的 **Install Package**。应用会安装最新发布的 Unreal MCP 版本，并先校验下载内容。如果已安装的插件版本更新，应用会保留它。
5. 点击 **Open Editor**，以你已登录的会话启动 Unreal Editor，这样插件就会通过 ai-game.dev 连接，无需手动填写 token。

在应用的 CLI 中，相同的操作对应 `/install-plugin` 和 `/open` 命令。应用还可以安装可选的[扩展](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)。详情见[项目与引擎](https://ai-game.dev/zh-hans/docs/wiki/app/projects-and-engines)。

## 方式 2：unreal-mcp-cli

`unreal-mcp-cli` 发布在 npm 上，可在 Windows、macOS 和 Linux 上使用。它无需克隆仓库，也不需要自身的构建步骤。

全局安装该 CLI：

```bash
npm install -g unreal-mcp-cli
```

或者不安装，直接运行一次任意命令：

```bash
npx unreal-mcp-cli@latest status
```

然后安装插件、登录并打开编辑器：

```bash
# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject
```

这些命令的作用：

- `install-plugin` 会下载与 CLI 版本匹配的插件源码（来自 GitHub release 的 `unreal-mcp-plugin-source-<version>.zip`），并在解压前校验其签名。被篡改或未签名的下载将被拒绝。适用于你平台的 bridge 已包含在该包内。
- `login` 会将你的凭证保存到机器级存储（`~/.ai-game-dev/credentials.json`），与桌面应用和其他引擎的 CLI 共享。
- `open` 会根据项目的 `EngineAssociation` 找到对应的引擎，在需要编译时先构建原生编辑器模块，并在已知的 Unreal 启动提示（例如 "Missing Modules"）仍然出现时将其关闭。

**提示：** 安装或更新插件前请先关闭 Unreal Editor。Unreal 无法替换已被运行中的编辑器加载的插件。

## 方式 3：从源码手动安装

手动安装面向贡献者和插件开发。

1. 将 [Unreal-MCP 仓库](https://github.com/IvanMurzak/Unreal-MCP) 中的 `UnrealMCP/` 文件夹复制到 `<YourProject>/Plugins/UnrealMCP/`。
2. 源码检出中不含内置 bridge。使用 `unreal-mcp-cli bootstrap-local ./YourProject` 构建一个（需要 .NET 9 SDK），或将 `UNREAL_MCP_BRIDGE_PATH` 指向你构建的 bridge。
3. 打开项目。Unreal 会在首次启动时编译插件的模块。

若要进行实时开发，`unreal-mcp-cli install-plugin --junction` 会以链接方式引用插件文件夹而不是复制它（Windows）。

## Fab / Epic Marketplace

Fab 上架计划中，但**尚未上线**。在它发布之前，Fab 上没有可安装的内容；请使用应用或 CLI。

## 检查安装

编辑器启动后，输出日志（Output Log）会打印：

```text
[Unreal-MCP] plugin loaded
```

你也可以运行 `unreal-mcp-cli status --path ./YourProject` 查看包、项目、插件和连接状态。

随后插件会以 **AI Game Developer** 的名称出现在编辑器的 **Tools** 菜单下。接下来请继续阅读[快速入门](https://ai-game.dev/zh-hans/docs/wiki/unreal/getting-started)。

## 更新插件

- **应用：** 当存在更新的插件版本时，侧边栏会显示 **Update Package**。
- **CLI：** 运行 `unreal-mcp-cli update ./YourProject`。当版本发生变化时，它会删除已安装插件的 `Intermediate/` 文件夹及其编译后的 C++ `Binaries/`，以便 Unreal 进行干净的重建，同时保留内置的 bridge。添加 `--force` 可重新安装同一版本，添加 `--no-clean` 可保留构建缓存。
- **手动复制：** 关闭编辑器，删除 `Plugins/UnrealMCP/Intermediate/` 和 C++ 的 `Binaries/`（保留 `Binaries/ThirdParty/`），然后重新打开项目。

构建缓存过期是更新看似无效的最常见原因。参见[故障排除](https://ai-game.dev/zh-hans/docs/wiki/unreal/troubleshooting#stale-build)。

## 移除插件

```bash
unreal-mcp-cli remove-plugin ./YourProject
```

或者在关闭编辑器的情况下删除 `<YourProject>/Plugins/UnrealMCP/`。

## 让插件不进入打包后的游戏

如果你只在编辑器中使用 Unreal MCP 来获得 AI 帮助，可以在**你的项目**的 `.uproject` 插件条目中将其排除在打包构建之外：

```json
{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}
```

这样插件在编辑器中仍保持启用，但包括 bridge 在内的任何部分都不会被编译或暂存到打包后的游戏中。不要将任何 `UnrealMcp*` 模块添加到你的游戏模块的 `Build.cs` 依赖中：直接依赖会覆盖该拒绝列表。若想在运行中的游戏内使用 AI 工具，请参见[游戏内工具](https://ai-game.dev/zh-hans/docs/wiki/unreal/custom-tools#runtime)。

---

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

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