A beginner’s guide to Unity CLI and the Pipeline package
Thomas Krogh-Jacobsen - Unity Technologies
Senior Technical Content Marketing Manager
我们最近推出了Unity CLI ，收到的反馈非常积极，越来越多的鼓舞人心的用例涌现出来。但是，如果您像许多其他人一样，觉得命令行工具位令人生畏，感觉自己更像个设计师而不是程序员，或者只是还没有时间去尝试，那么本指南就是为您设计的。
什么是Unity CLI？
Unity 编辑器的最大优势之一是其GUI)，它使用户能够轻松地以可视化的方式管理复杂的项目。在编辑器中，只需点击几下鼠标，即可检查预制件、调整材质值、running测试、烘焙照明或追踪控制台错误。该工作流程已为用户服务近二十年，它已成为重复性任务、自动化和人工智能驱动（代理）工作流程的瓶颈。AI 代理可以导航点击和纯视觉界面，但这需要额外的、非原生的视觉解释层，这会减慢处理速度并增加不必要的开销，从而迅速消耗令牌。
这时，新的Unity CLI 和实验性的Unity Pipeline 包就派上用场了。
Unity CLI，顾名思义，是一个用于管理Unity 的命令线界面。由于它没有图形用户界面，因此非常适合自动化和代理工作流程。它作为一个独立的二进制文件（应用程序）运行，其中包含了运行、管理和与Unity交互所需的一切。换句话说，你可以从终端运行直接与Unity通信的命令，从而取代 Hub 或编辑器中的鼠标点击层和整个工作流程。
注意：新建功能和改进功能会频繁添加。截至撰写本文时， Unity CLI 的 1.0.0-beta.6 版本与管线包的 0.5.0-exp.1 版本以及Unity 6000.6.0b9 版本相结合，是目前最新的配置。如果遇到问题，检查查看Unity CLI文档： https://docs.unity.com/en-us/unity-cli/use-unity-cli
Unity CLI 和 Pipeline 包如何协同工作
虽然独立的Unity CLI 二进制文件可以处理您的环境设置（例如安装编辑器、模块和管理许可证），但真正的价值在于将其与Unity Pipeline 包 ( 管线 ) 结合使用。
这个Unity Pipeline 包本质上是将你running的编辑器变成了一个本地 HTTP 服务器。由于编辑器在后台保持打开状态，因此您加载的场景和资源数据库会“保持”在系统内存中。通过预先加载所有内容，您可以完全避免从冷启动状态启动引擎所带来的令人沮丧的启动开销。现在，您的终端（或 AI 代理）可以立即驱动编辑器运行测试、加载场景或修改GameObjects。
该系统还能解决臭名昭著的域名重载瓶颈。在 Pipeline 包出现之前，每当您或您的 AI 代理直接更改磁盘上的C#脚本时，您都必须等待Unity重建项目并重新加载域。有些操作甚至需要您在编辑器中聚焦或点击某些内容才能继续进行。
但是 Pipeline 包的本地服务器完全异步地处理该编译过程。编译过程中连接始终保持稳定和活跃，确保在编辑器于后台重新加载时，终端会话不会断开或超时。
使用eval命令动态执行代码时，速度会更快。在这里，编辑器中的 Pipeline 包就像一个即时翻译器，可以即时编译你的C#代码片段，并将其直接放到 Unity 的主线程上。由于这种动态执行是完全独立的，因此它完全绕过了项目范围的重新编译和域重新加载过程。您完全无需经历漫长的等待，即可在几毫秒内获得结果。
这意味着，即使后台正在进行大型项目编译，你的重型自动化脚本也不会崩溃或失去连接，而你的快速终端命令仍然可以以近乎零延迟的方式执行。同一款工具即可兼具稳定性和速度。
从 MCP 迁移到Unity CLI
你可能会想，“那么官方的Unity模型上下文协议 (MCP) 服务器呢？”我为什么不能继续使用或坚持使用它呢？
简而言之，我们不会放弃对 MCP 的支持。然而， Unity CLI 和 Pipeline 包可以处理与 MCP 相同的用例，甚至更多，而且处理得更好、更快。
更详细的答案归根结底在于建筑结构。传统的 MCP 设置需要一个主动客户端框架（如 Claude Desktop 或 Cursor）来充当 AI 代理和Unity之间的翻译器。但像 Claude Code 这样的现代终端原生代理程序已经非常擅长直接running标准 shell 命令。通过使用unity command或unity eval等直接 CLI 输入，您可以完全绕过配置和维护 MCP 服务器的开销。您的代理可以通过统一、超高速的本地 HTTP 服务器直接与Unity通信。这意味着您可以编写更简洁的配置，减少调试连接套接字的时间，并让您的 AI 以纯粹的、原生的终端速度运行。
此外，旧版 MCP 服务器作为C#包直接在编辑器进程内运行。这意味着连接桥本身绑定到了 Unity 的主线程和内存空间。一旦编译代码或触发域重新加载， Unity就会刷新其内存，这经常导致连接套接字断开、抛出空异常或代理在循环中卡顿。
当前的管线包也是一个在编辑器内running的C#包，但它公开了一个 HTTP 服务器和REST API （而不是套接字桥），因此它对域重新加载具有更强的适应能力。由于此本地服务器异步处理命令，即使在进行大量编译和域重新加载期间，您的终端连接仍将保持完全稳定和活动状态。
总之，通过迁移到Unity CLI，您可以完全避免连接中断和令牌浪费。最后，如果您有想要使用 MCP 的指定的用例，CLI 还提供了 MCP 模式。
安装 CLI 和 Pipeline 包
在最新版本中，使用Unity Hub会自动安装 CLI 和 Pipeline 包。截至撰写本文时，安装Unity CLI 的方法有多种，因此make务必参考文档以获取最新信息。
如果您由于某种原因尚未安装该软件，最简单的方法是使用终端命令进行安装。您可以观看视频或按照以下说明操作。
要安装Unity CLI，您只需根据您使用的平台，在终端中运行以下命令：# macOS or Linux
curl -fsSL 云端| UNITY_CLI_CHANNEL=beta bash
# Windows
$env:UNITY_CLI_CHANNEL='beta'; irm 云端| iex
下一步是安装Unity Pipeline 包：Unity 管线安装
安装完成后，您可以再次检查它们是否正常running。
验证安装情况
要确认安装是否成功，只需运行以下命令：统一status
它应该返回类似这样的内容：Unity 编辑器（端口 7800）：readyProject：/ Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersion：6000.6.0b7PID: 85009
如果在第一行旁边看到就绪状态，则表示编辑器已启动并可访问。它还会确认编辑器所在的端口、项目路径、编辑器版本和进程标识符 (PID)。
Next，为了确保您的访问已通过身份验证，请运行以下命令：
Unity 身份验证登录
这将打开您的浏览器，以便通过 OAuth 登录您的Unity帐户。完成身份验证后，CLI 会将您的凭据存储在系统密钥环中，以便将来需要身份验证的命令（如unity projects list、unity 编译版本、unity 许可证、unity 云端 ）无需重新提示即可自动运行。
运行一些基本命令
CLI 和 Pipeline 包安装完毕后，是时候尝试更多命令了。我们先来看unity --help命令，它可以让你快速了解所有可以执行的操作。
unity --帮助
unity --help命令会列出所有可用的基本命令，并概述每个命令及其可用选项。
一开始选项的数量可能会让人感到位不知所措，但 CLI语法遵循非常合乎逻辑、一致的模式。
让我们使用刚才作为示例的命令，但这次加上一个选项：
unity auth 登录 --非交互式
从左到右：
unity 命令用于激活Unity CLI，因此是主要命令。auth login是子命令。你可以把它们看作是动词，它们告诉主程序要采取什么行动。在这里，auth指示 CLI 连接到身份验证系统，而 login 则指示它登录。--non-interactive是选项。可以将选项视为类似于参数。它们是修饰符，用来告诉命令如何运行。在这种情况下，它告诉 CLI 直接通过终端日志，而不是打开可视浏览器窗口。在开/关选项的上下文中，选项有时也被称为“标志”。
此外，还有一个单字母快捷键，专为日常终端工作流程中的快速输入而设计。
回到我们的帮助选项（ --help ），除了runningunity --help之外，你也可以直接使用 unity -h ，两者都会给出相同的答案。unity --帮助 # 长标志版本（改进可读性） unity -h # 短标志版本（日常运行速度更快）
短标志使用单破折号 (-)，旨在简化说明；长标志使用双破折号 (--)，是等效的完整单词描述，旨在提高可读性。
--help命令是你的工具包中最重要的工具；你可以将其附加到嵌套命令的任何关卡，以便快速获取文档。以下是我们刚才介绍的身份验证命令的一些示例：
# 身份验证命令的帮助
unity auth --help
# 专门提供登录命令的帮助
unity auth 登录 --help
每个帮助屏幕都会立即输出命令的具体功能、可用选项以及所需的参数。如果拿不准，直接问命令就行了！
我们再以发布命令为例：
Unity发布
这让我可以很好地了解撰写本文时Unity的所有可用版本。
现在让我们添加--help选项：
Unity 发布 --帮助
unity releases --help命令会解释所有可以添加的各种选项，以便缩小Unity版本的search范围。
例如，在撰写本文时，我们使用的是Unity 6.6b7 的测试版，并且想要安装最新的测试版。我们可以使用基本的Unity 安装命令，它会提供一个简单的可视化界面，我们可以在其中选择所需的版本。
Unity 安装
我们选择 b9 版本，它将在后台running安装程序（需要几分钟才能完成）。
除了使用安装向导之外，您还可以使用--help命令来获取所有命令的概览：
unity install --help
这将为您提供如下所示的概览：
从列表中可以看出，您可以将要安装的Unity版本作为参数传递。这意味着，如果您想要安装指定的版本，可以使用以下命令通过单个命令完成安装：#只需将版本号替换为您想要使用的版本即可
unity install 6000.5.9f1
与此同时，我们的新版编辑器已经安装完毕，所以现在我们需要升级项目。为此，请添加您要打开项目的指定的版本。这相当于您进入 Hub 并选择另一个编辑器版本通过项目打开，从而触发升级项目。
unity open --version 6000.6.0b9
正如我们之前提到的，Pipeline 包打开了一个庞大的工具箱，其中包含了几乎所有你可以在Unity 编辑器中执行的操作（并且随着 beta 版的成熟，还会不断添加新的命令）。
如果想查看当前项目中可用的命令，请运行：
团结列表
此命令会生成一个高级表格，显示每个命令的名称、组和简短描述。它非常适合作为起点，可以快速浏览数百个内置命令，例如eval 、 add_animator_layer 、 编译版本和find_assets 。
当您需要确切地知道如何格式化输入内容时。你可以运行：
团结指挥部
不带任何参数运行此命令，即可获得Unity命令的详细“蓝图”，其中包含每个已注册命令的文档，包括选项（命令所需的确切标志和数据类型）。
这两个命令都与同一个连接的编辑器进程通信，但它们返回的细节级别不同。当您开始构建自定义自动化脚本或设置底层驱动Unity 的代理工作流时， unity command将很快成为您构建清晰、自动化呼叫时最常用的查找工具。
最后，让我们来看看eval命令，以及如何在Unity 控制台中运行一个简单的Debug.Log ( “ Hello World ” )测试。eval 是一个 Pipeline 包命令（可以说是 140 多个内置命令中最令人兴奋的一个），它可以在编辑器进程中动态编译和执行C#代码。请尝试running以下命令：
unity 命令 eval --代码'Debug.Log("hello from unity cli");'
这样，JSON 返回“success”时，如果成功，则会得到以下result：true。
现在，您可以在编辑器中通过控制台窗口验证此操作是否确实有效。
让我们来分析一下这条命令：
unity 命令 eval --代码'Debug.Log("hello from unity cli");'
从左到右阅读：
Unity运行Unity CLI 工具。command是指示它“与已连接的编辑器通信”的子命令。eval是一个子子命令，意思是“为我执行（运行）一些代码”。-- 代码是一个选项（或标志），表示“以下是要运行的代码”。'Debug.Log("hello from unity cli");'是代码的值；实际要执行的代码。
连接LLM
熟悉一些基本命令可以帮助加快Unity安装的一些维护工作，但它真正的优势在于当你开始自动化和集成代理工作流程时。
借助Unity CLI 和 Pipeline 包，您可以连接您选择的代理。也就是说，无论您使用的是 Claude、Codex、Copilot 还是本地模型等，CLI 都旨在与您现有的首选设置集成，并且无需任何额外设置即可连接。
只需打开终端，使用 cd 命令直接导航到Unity项目目录，然后输入“claude”（或您的代理命令）来启动代理即可。您可以通过向客服人员询问类似以下的问题来确认是否已连接：
在 bash 中运行“unity command”命令，告诉我它的功能，然后测试一个简单的“eval”命令。
使用 MCP 连接 LLM
Unity已弃用com.unity.ai.assistant包中的编辑器内 MCP 服务器。它已被Unity CLI 内置的 MCP 服务器（ unity mcp ）取代，该服务器由Unity Pipeline 包提供支持。它使用相同的协议，因此客户端可以无缝连接。对于无法运行任意 shell 命令或难以进行命令行组合的代理，MCP 模式仍然得到全面支持。
要使用 MCP，请运行以下命令：
Unity MCP配置
此命令会自动将配置直接注入到代理的设置中。要测试 LLM 是否已连接，请执行一个简单的测试，提示 LLM 工具运行类似以下内容：
我希望你在当前打开的场景中心创建一个 2 × 2 × 2 的立方体。然后编写一个脚本，使其以每秒 45 度的速度绕三个轴连续旋转。
以下是克劳德·科德的回应：
完成后，它应该会进入播放模式并运行场景，以便您可以验证立方体是否正确旋转。
扩展您自己的自定义命令
CLI 的内置套件涵盖了所有基本功能，例如切换播放模式、重新编译和running单元测试。然而，这种架构的真正力量在于其可扩展性。您可以轻松编写自定义命令，为您的 AI 代理提供量身定制的、特定于项目的上下文以及专为您的游戏构建的独特工具。
创建自定义命令非常简单。你All需要编写一个标准的静态C#方法，并用[CliCommand]和[CliArg]特性修饰它即可。
Pipeline 包在编译过程中会自动发现这些属性，这意味着它不需要任何手动配置或注册文件。当您运行不带任何参数的unity 命令时，CLI 会动态列出所有可用的自定义命令以及内置命令。
注意：[CliCommand]属性使命令可通过 CLI 被发现和调用。对于参数化执行，您可以使用C#语法直接使用unity 命令 eval调用该方法，而不是传递 CLI 风格的标志。
让我们来看一个简单的“Hello World”自定义命令的实际应用。
Create一个名为HelloWorldCommand.cs的新C#脚本。请确保类和方法是静态的，并包含Unity命名空间：
使用 UnityEngine；
使用Unity；
public static 类 HelloWorldCommand
{
[CliCommand("hello-world", "一个简单的 hello world 命令")]
public static void SayHello()
{
Debug.Log("Hello, 世界!这是一个自定义的 CLI 命令。
}
}
要运行你的新命令，请打开终端并执行以下命令：
Unity 命令 Hello World
终端界面应该看起来像这样
你的控制台日志应该如下所示：
如果需要使用[CliArg]特性传递参数，也可以扩展此功能。
使用 UnityEngine；
使用Unity；
public static 类 HelloWorldCommand
{
[CliCommand("hello-world", "一个简单的 hello world 命令")]
public static void SayHello(
[CliArg("name", "问候对象")] string name)
{
Debug.Log($"你好，{name}！"这是一个自定义的 CLI 命令。
}
}
要运行你的新命令，请打开终端并执行：
unity 命令 hello-world --name "thomas"
安装Unity Agent插件
Unity还提供了一个官方的游戏开发插件，截至撰写本文时，该插件适用于 Claude Code、Codex 和 Grok。它提供游戏开发和性能优化方面的精选技能。安装完成后，当您在上述任何一种Unity项目中工作时，这些技能都会自动加载。要为 Claude 安装，只需运行以下命令：
claude插件市场添加 Unity-Technologies/unity-agent-plugin
github.com/Unity-Technologies/unity-agent-plugin
如果您是 Claude Code 用户并且正在启动一个新项目，另一个快速提示是运行初始化阶段，该阶段会通过创建claude.md文件来设置 Claude 与您的项目相关的基本上下文。这是一个位于项目文件夹根目录下的 Markdown 文件，Claude Code 会在每次会话开始时读取该文件。
/init # 在 Claude Code 中运行此命令
这样你就可以用它来告诉 Claude 你偏好的技术栈，例如你可能更喜欢 uGUI 而不是UI Toolkit 作为UI，更喜欢新的Input System而不是旧的输入管理器等等。它还可以用于架构决策，例如使用服务定位器模式而不是单例模式，在UI设计中使用 MVP 等。
Claude 在工作过程中会自动构建记忆，无需您编写任何内容即可跨会话保存学习成果，而 Claude.md 文件则有助于指导指定的项目的整体方向。
随着流程的推进，您可以考虑添加更多自定义说明，例如您的代码风格指南。我写了一篇文章，介绍了人工智能助手自定义指令的工作原理，但如果你有兴趣了解更多，Claude Code 的原理也完全相同。
后续建议
希望这篇介绍能对您有所帮助，让您顺利入门。如果您有兴趣进一步优化您的代理工作流程，检查查看有关为您的 LLM 设置自定义指令的文章，包括定义Unity C#代码风格指南。
Check此处观看视频：