CICD Made Easier with Unity CLI

Sep 30, 2026
CLIDevOps
CICD Made Easier with Unity CLI

为方便起见，此网页已进行机器翻译。我们无法保证翻译内容的准确性或可靠性。如果您对翻译内容的准确性有疑问，请参阅此网页的官方英文版本。

请点击这里。

CI/CD 流水线往往会自然而然地发展壮大。最初只是一个打开Unity 编辑器并开始编译版本的脚本，它逐渐承担了更多职责：找到正确的编辑器可执行文件、安装平台模块、管理许可证、收集测试结果、处理签名凭据，并在作业完成后清理所有内容。

这种result或许有效，但可能难以理解，更难以复现。该管线不仅依赖于其配置文件中的代码，还依赖于运行器上安装和配置的所有内容。

新的Unity CLI 为自动化与Unity 的交互提供了一种更简单的方式。它为编译版本系统提供了一个统一的命令，用于安装编辑器、running测试、生成构建和管理许可证。它专为终端和自动化工作流程而设计，包括非交互式安装、结构化输出和清晰的退出代码。( unity.com )

这不会取代您的 CI 提供商或项目的编译版本代码。相反，它减少了连接两者所需的定制机械。

简化：明确管线需要做什么

在Unity CLI 出现之前，大多数 CI 流水线都是直接启动Unity 编辑器可执行文件。一个简化的测试命令可能如下所示：

UNITY_PATH="/opt/unity/editors/6000.2.10f1/Editor/Unity"

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -runTests \
  -testPlatform EditMode \
  -testResults ./results/editmode.xml \
  -logFile -

这种方法本身并没有什么错。真正的挑战在于围绕它需要发生的一切。

管线需要知道编辑器安装在哪里。另一个脚本或机器镜像需要确保所请求的版本存在。运行程序还必须具备正确的平台模块、许可配置和环境变量。Windows、macOS 和Linux运行程序可能需要略有不同的路径和设置逻辑。

该命令运行测试，但围绕它的管线包含许多 Unity 特有的实现细节。

使用Unity CLI，同样的步骤可以用其意图来表达：

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

这会指示管线运行项目的 EditMode 测试并将结果写入 NUnit XML文件。使用--allow-install 参数，CLI 可以读取项目所需的Unity版本，并在必要时进行安装。项目（而不是编译版本机器）成为确定使用哪个编辑器版本的唯一依据。

构建过程遵循相同的模式。以前，编译版本可能会直接调用编辑器：

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -buildTarget Android \
  -executeMethod Builder.PerformBuild \
  -logFile -

使用Unity CLI，编译版本更容易阅读：

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab \
  --allow-install

您现有的Builder.PerformBuild方法可以继续负责编译版本过程中指定的于您项目的部分：选择场景、应用编译版本设置、设置脚本符号、分配版本信息或running工作室特定的验证。

CLI 简化了该方法的自动化过程。CI 配置不再需要了解太多关于定位和启动编辑器。

综合起来，CI 作业可以通过一系列简短的命令，从一个全新的运行器生成一个经过测试的编译版本：

# Install Unity CLI on macOS and Linux
brew install --cask unity-cli

# Install Unity CLI on Windows
winget install Unity.CLI

# Install a specific Editor and its Android module
unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

# Run EditMode tests
unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

# Build an Android App Bundle
unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

或者，测试和编译版本命令可以使用--allow-install ，这样当项目应该确定版本时，就不需要单独的编辑器安装步骤了。

重要的变化不仅仅是命令变短了。它们的作用在于传达这项工作想要达成的目标。阅读该管线的人可以看到Unity 的安装位置、测试运行位置以及编译版本生成位置，而无需解码一系列编辑器路径和批处理模式标志。

生产管线中仍然会包含其他环节。您的 CI 提供商仍然会检出代码仓库、注入密钥、恢复缓存、发布测试报告和上传工件。Unity CLI 为这些系统提供了一种更简单、更一致的方式来处理 Unity 特有的步骤。

改进：消除管线中的风险

更简单的管线更容易阅读和维护，但简化只是好处的一部分。通过将Unity 的设置和执行移至一致的 CLI 之后，团队还可以解决 CI/CD 风险的几个常见来源。

运行程序使用的编辑器版本错误。

依赖于预配置机器的管线也依赖于该机器保持正确配置。有人可以更新编辑器、删除模块或更改安装路径。替换后的运行器在 CI 控制面板中可能看起来完全相同，但内部结构可能略有不同。

这些差异可能很难被发现。管线配置没有改变，项目也没有改变，但是由于机器发生了变化，编译版本行为突然变得不同了。

Unity CLI 允许作业声明它需要的编辑器和模块：

unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

或者，该作业可以使用--allow-install ，并让项目的ProjectVersion.txt确定所需的编辑器。

这样一来，编译版本环境就成为了管线的一部分，而不是运行器的一个未记录的属性。升级Unity 的分支可以将该要求带入 CI，而无需等待编译版本工程师更新每个运行器镜像。

这也使得短暂的跑鞋更加实用。一个新的跑步者不需要从一开始就是一个精心准备的Unity编译版本机器。它可以安装 CLI 并配置所需的环境，作为作业的一部分。

CI 的行为与开发人员机器的行为不同。

提供商特定的脚本可能会在本地开发和持续集成之间造成差距。当作业失败时，开发人员可能会收到一个包含路径和选项的大型编辑器命令，这些路径和选项只有在编译版本运行器上make意义。

要在本地重现该故障，需要将 CI脚本翻译成可以在开发人员机器上运行的脚本。

Unity CLI缩小了这种差距，因为同一个命令可以在两地使用：

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

CI 环境仍会存在一些差异——例如密钥、许可和瑕疵发布——但面向 Unity 的条目点保持不变。

这样一来，调查工作failed的原因就更容易了。开发人员可以复制测试或编译版本命令，从项目目录运行它，然后开始重现问题，而无需先重建运行器的编辑器调用。

Custom封装器脚本本身就构成了基础设施。

许多工作室都有脚本来查找Unity安装位置、将编译版本目标转换为编辑器参数、流式传输日志、解释退出代码并将测试结果移动到正确的目录。

这些脚本通常是出于正当理由而编写的。然而，随着时间的推移，它们会成为另一层需要测试和维护的基础设施。它们也可能在多个项目中重复出现，或者为每个 CI 提供商重新编写。

Unity CLI 为常见操作提供了一个统一的条目点：

unity install
unity test
unity build

但这并不意味着每个项目都会变得完全相同。工作室可以（也应该）将项目特定的逻辑保留在它应该在的地方。AC#编译版本方法可以继续定义游戏的构建方式，而 CLI 则提供了一种标准方式，使自动化能够调用它。

界限变得更加清晰：项目拥有编译版本，而 CI 作业拥有编译版本运行的时间和地点权限。

故障难以诊断。

Unity作业failed可能会产生amount输出。如果测试结果仅存在于编辑器日志中，开发人员可能需要下载并search该日志才能找到实际的故障。对于临时运行程序，有用的诊断文件也可能在作业完成后立即消失。

Unity 测试可以直接编写 NUnit XML报告：

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

CI 提供商可以接收并显示该上报。此外，它还使用定义的退出代码并维护 CLI 特定的日志，这有助于自动化区分测试失败与其他问题。( docs.unity.com )

result不仅仅是日志记录量的增加。它在开发人员已经查看的地方（例如作业日志、测试上报和编译版本工件）提供了更有用的输出。

管线可以保​​留每次运行的关键输出：

results/editmode.xml
results/playmode.xml
out/app.aab
Editor.log
cli-log.json

这使得管线更容易缩放运行。开发人员可以自行调查例行测试失败，而编译版本工程师则可以保留诊断基础设施问题所需的详细日志。

资格证书和执照的效力远超工作本身。

Build运行程序通常需要访问敏感材料：服务帐户凭据、 安卓密钥库、签名密码或离线许可证文件。除非管线执行仔细的清理，否则长时间运行的机器可能会在构建之间保留这些文件或环境更改。

CLI 优先的工作流程与秘密存储和临时运行器非常契合。凭据可以作为环境变量注入，供作业使用，并在运行程序被已移除时丢弃。

文件签名也可以遵循相同的模式。例如， 安卓密钥库可以存储为 base64 编码的 CI 密钥，仅在编译版本时解码，并在拆卸期间删除：

echo "$ANDROID_KEYSTORE_BASE64" \
  | base64 --decode > ./android.keystore

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

rm -f ./android.keystore

许可也可以成为工作生命周期中一个明确的组成部分。运行程序在执行Unity工作之前会激活许可证，并在作业结束时归还许可证：

unity license activate --floating

# Run tests and produce builds

unity license return

Unity CLI 支持激活和返回工作流程，包括浮动许可和离线许可选项。（ docs.unity.com ）

对于临时运行器，返回命令应该放在无条件清理步骤中，以便即使测试或编译版本失败也能运行。这样可以防止failed的作业导致座位被占用，从而影响后续的构建。

该管线与一个 CI 提供商关联。

每个 CI平台都有自己的配置语言，但是当提供程序发生变化时，作业内部的Unity工作不应该也随之改变。

管线可以使用GitHub Actions、 GitLab CI、Jenkins、Buildkite、TeamCity 或内部编排系统。这些系统将继续管理调度、密钥、缓存和工件。用于测试和编译版本Unity项目的命令可以保持一致：

unity test . --mode EditMode --output ./results/editmode.xml
unity build . --target Android --output-path ./out/app.aab

这并不makeCI 迁移变得轻松，但可以减少必须重写的 Unity 特定自动化代码amount。提供程序运行命令； Unity CLI 处理与Unity 的交互。

这种一致性在各个项目之间也很有用。Build团队可以建立通用的管线模式，而无需每个项目都共享相同的内部编译版本实现。

归根结底， Unity CLI 并不会改变一个好的 CI/CD管线需要完成的任务。该管线仍然需要配置其环境、运行测试、生成构建、保护凭据、发布有用的输出以及清理自身。

改变的是，make这些步骤与Unity工作，需要多少自定义机制。

团队无需依赖硬编码的编辑器路径、预配置的运行器和日益复杂的封装器脚本，而是可以使用一设置命令来描述他们的意图。result的管线更易于阅读、更易于复现，并且对特定编译版本机器的状态依赖性更低。

使用Unity CLI 简化从干净的运行器到经过测试的编译版本的路径，并提高整个过程的可靠性。