Resources

Unity Pipeline 包和Unity CLI：安装指南和操作步骤

Aug 13, 2026
EngineProgramming and DevOps
Unity Pipeline 包安装

重要信息

  • Unity Pipeline 包在Unity编辑器内运行，并通过 HTTP 和 JSON API公开命令。
  • Unity CLI 是一个独立的客户端，允许终端、代理和自动化脚本执行这些命令。
  • 内置和自定义命令支持可重复的工作流程，例如项目设置、重新编译、测试和运行时控制。
  • 同一个命令合约可以为Unity CLI、代理工作流和自定义界面提供支持。

概述

Unity CLI是免费的，目前处于测试阶段。将其与Unity Pipeline 包结合使用，即可从终端驱动编辑器进行 CI、脚本编写和 AI 代理。

Unity Pipeline 包会在Unity编辑器内添加一个轻量级服务器，使其能够通过标准 Web 协议直接与终端或其他工具通信。您可以从外部触发状态检查、编译或测试运行等命令。由于这些操作是异步管理的，因此即使在脚本更改后编辑器重新加载，它们也会保持活动状态。这种设置使您的自动化流程具有一致性、可预测性和易于编写脚本的特点。

安装指南

组件

  • Unity CLI ：Unity CLI 是一个独立于编辑器之外的二进制文件，它连接到正在运行的编辑器，并从终端驱动它。Pipeline 包需要Unity 6.0 或更高版本。
  • Unity Pipeline 包：通过CLI 安装到项目 (com.unity.pipeline) 中。该软件包在编辑器内部运行，并在编辑器加载时自动启动本地服务器。
  • 命令：每个命令都是项目中的一个函数，并已添加标签，以便Unity可以自动注册它。内置命令涵盖播放模式、状态、重新编译和运行测试，并可选择添加您自己的命令。
  • 评价：这会直接在Unity实时分层（编辑器或正在运行的版本）中运行 C#，以执行一次性操作。它可以执行任意 C# 代码，并受安全令牌保护；请将其视为远程代码执行程序，并仅用于本地开发。
测试

建筑

  • 客户：调用者可以是终端、代理、CI/CD 设置或自定义 UI等。
  • Unity CLI ：主要客户端负责将命令转换为API调用；自定义 UI 也可以直接使用该协议。
  • 协议：HTTP + JSON以及客户与Unity之间的合同
    • 任何能够发出 HTTP 请求的客户端都可以驱动Unity，无论使用何种语言。默认情况下，服务器绑定到本地主机，因此客户端与编辑器运行在同一台机器上；远程调用者通过您公开的任何网络路径访问它。
  • Unity Pipeline 包：已安装到项目中，随编辑器自动启动。
    • Pipeline 包托管两个服务器：编辑器服务器（播放模式、状态、重新编译、运行测试、项目设置）和运行时服务器（通过运行时管道管理器在运行的构建中进行实时编辑）。

配置建议

第一步：安装Unity CLI

Unity CLI 是一个独立的二进制文件（实验性）。使用脚本或通过软件包管理器安装，然后进行验证。完整说明请参见Unity CLI 文档。

# macOS / Linux — install script

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

# macOS / Linux — Homebrew (keeps it current)

brew install --cask unity-cli

# Windows — PowerShell install script

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
unity --version          # verify it's on your PATH

第二步：登录

控制编辑器需要经过身份验证的会话级别/会话次数：

unity auth login         # opens a browser sign-in flow

unity auth status        # confirm you're signed in

步骤 3：将Unity Pipeline 包添加到项目中

Unity Pipeline 包在编辑器内运行，并连接到Unity CLI。如果从终端安装，请确保位于要安装的Unity项目的根目录中。运行unity pipeline install 命令，默认情况下它会将目标目录设置为当前目录或正在运行的编辑器。您还可以通过包管理器添加 com.unity.pipeline。请参阅Unity Pipeline 包文档。

unity pipeline install

安装完成后，编辑器会自动启动服务器。请查看新的“管道”菜单以确认。

第四步：连接并列出命令

安装好软件包后，连接到正在运行的编辑器，并列出可编写脚本的内容：

unity command            # list this project's commands

列表包括内置命令（播放模式、状态、重新编译、运行测试）以及任何自定义命令。它们无需额外配置即可与任何代理配合使用。

从终端驱动编辑器

进入播放模式，运行测试，列出构建目标，或截取屏幕截图。

unity command editor_play

unity command run_tests

unity command list_build_targets

unity command screenshot

运行是确定性的，以上只是其中的一小部分；Unity 列表显示了完整的内置内容（场景、预制件、材质、动画、照明/导航网格烘焙、构建、屏幕截图、包等等）。

自定义命令

自定义命令可以将一系列操作串联成一个命令行调用。命令是项目中带有标签的函数。例如：

  • 运行测试并通知：运行测试套件，并通过一次通话将结果发布给团队。
  • 报告未使用的素材资源：扫描项目并列出没有引用的素材资源，以便在构建之前删除。

书面命令具有确定性和可重复性：相同的呼叫，相同的结果，这也使得将其交给代理人变得简单明了。

运行时控制

运行时服务器驱动正在运行的构建。要启用它，请添加一个空的游戏对象，添加运行时管线管理器组件，并勾选“在构建中启用” 。构建过程正在运行，从终端执行以下操作：

  • 减慢、暂停或重新开始时间。
  • 在运行时动态更改游戏对象的值，并缩放或移动变换。
  • 在运行时交换素材资源和特效。

对于重复执行的操作，编写运行时命令并将其打包到游戏中（调整游戏玩法值、覆盖游戏模式）。它是确定性的、可重复的，并且可以由代理调用。

代理人和评估

所有命令都可通过 CLI 或其 MCP 模式供任何代理使用：内置命令、自定义命令和评估命令。一个代理人有两个档位：

  • 用于可重复步骤的确定性命名命令
  • 当没有命令时，对一次性 C# 进行求值

一个用例是，代理使用 eval 函数来构建或修改某些内容，运行一个确定性命令来执行该操作，截取屏幕截图，并将图像与提示进行比对，如此反复直到匹配为止。eval 函数是使用令牌门控的任意 C# 代码，因此可以限定代理可以操作的范围。

安防

Unity CLI 和 Pipeline 包是为本地开发而设计的，而不是为已发布的游戏而设计的。默认情况下，所有内容都保留在您的计算机上；它仅在您开发时运行，并且运行实时代码（eval）受每个项目的访问密钥限制，因此如果没有该密钥，代理将无法针对您的编辑器执行任意 C# 代码。将 CLI 交给 AI 代理就像让任何助手访问你的计算机一样：它可以做你能做的事情，所以要决定允许它接触什么，并将 eval 命令限制在本地工作。

更多资源

Unity CLI 文档

Unity Pipeline 包文档