unity-cli

Unity CLI

通过命令行简化 Unity 项目工作流和自动化流程。

适用场景

• 在环境中安装并验证 Unity CLI
• 为 CI/CD 流水线或自动化构建设置身份验证
• 以编程方式创建或管理 Unity 项目
• 自动化构建、测试或项目初始化工作流
• 配置云存档、许可证或组织设置
• 将 Unity CLI 集成到 GitHub Actions、Jenkins 或类似的 CI 系统

不适用场景

• 交互式游戏开发工作流 → 使用 unity-gamedev-skill-pack
• 图形/渲染任务 → 使用 threejs-* 或特定引擎的技能
• 游戏场景中的 UI 设计 → 使用 game-studio-harness 或 open-design-game-ui-*
• VFX 或动画 → 使用 game-vfx 或 video-motion-previs

说明

第 1 步：明确自动化目标

确定：

• 目标：构建自动化、项目设置、CI/CD 集成、云操作或许可证管理
• 环境：本地开发、GitHub Actions、Jenkins、GitLab CI 或自定义运行器
• 范围：单个项目、单体仓库或组织范围的自动化
• 身份验证：服务账号、个人令牌或交互式登录

第 2 步：检查先决条件

验证：

dotnet --version
which unity-cli || which unity

如果尚未安装，请继续第 3 步。

第 3 步：安装 Unity CLI

本地安装：

bash .agent-skills/unity-cli/scripts/setup.sh --install

Docker（CI/CD）：

使用预装 CLI 的官方 Unity Docker 镜像：

docker pull unityci/editor:<version>-<platform>-<architecture>

手动安装（系统范围）：

按照 Unity CLI 安装文档操作，并将其添加到 PATH。

第 4 步：进行身份验证

交互式登录：

unity-cli manage licensing --authenticate

CI/CD 令牌（推荐）：

export UNITY_SERIAL=<serial>
export UNITY_EMAIL=<email>
export UNITY_PASSWORD=<password>

unity-cli manage licensing --validate

对于服务账号，请使用个人访问令牌，而不是明文密码。

第 5 步：运行常见工作流

创建新项目：

unity-cli project create --name myproject --template 3d

管理 Editor 安装：

# List available Editor versions
unity-cli install --list

# Install exact Editor version with specific modules
unity-cli install 2023.2.10f1 -m android ios webgl --accept-eula --yes

# Open project with auto-detected Editor version
unity-cli open ./MyGame

使用可验证输出进行构建（JSON/TSV）：

# Machine-readable build output
unity-cli build --project /path/to/project \
  --platform WebGL \
  --output /path/to/build \
  --format json > build-result.json

# Parse results in CI
cat build-result.json | jq '.success'

调用 Pipeline 软件包（localhost API）：

# Requires: com.unity.pipeline experimental package installed
# Requires: Editor running with --api-port flag

# Example: Evaluate C# in running Editor
curl -X POST http://localhost:14000/eval \
  -H "Authorization: Bearer $PIPELINE_TOKEN" \
  -d '{"code": "Debug.Log(Application.version)"}'

验证设置：

unity-cli doctor

运行测试并获取证据：

unity-cli test --project /path/to/project \
  --results-file test-results.xml \
  --format json > test-output.json

第 6 步：集成到 CI/CD

GitHub Actions 工作流示例：

name: Unity Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: bash .agent-skills/unity-cli/scripts/setup.sh --ci
      - run: unity-cli build --project . --platform WebGL --output ./dist
      - uses: actions/upload-artifact@v3
        with:
          name: build
          path: ./dist

Jenkins、GitLab CI 和其他运行器的配置见 references/ci-cd-patterns.md。

第 7 步：排查故障

许可证验证失败：

unity-cli manage licensing --validate --verbose

构建因缺少依赖项而失败：

unity-cli project validate --project /path/to/project

找不到 CLI：

bash .agent-skills/unity-cli/scripts/setup.sh --diagnose

常见问题和解决方案见 references/troubleshooting.md。

示例

示例 1：为 WebGL 构建设置 CI/CD

GitHub Actions 工作流需要构建 WebGL 游戏。使用此技能安装指定版本的 Editor、验证项目、生成结构化构建输出并解析结果。

示例 2：验证生产环境中的游戏构建

AI Agent 需要确认构建是否成功并获取输出路径。使用 JSON 格式的构建输出解析成功或失败状态，并让 Agent 根据结构化结果做出决策。

示例 3：通过 Pipeline 软件包查询正在运行的 Editor

CI 作业需要在 Editor 运行时检查构建信息。安装 com.unity.pipeline 软件包，使用 --api-port 启动 Editor，并通过脚本查询自定义 CLI 命令。

最佳实践

1. 在 CI/CD 中使用令牌，切勿在仓库文件中使用明文密码。
2. 构建前先验证——使用 project validate 尽早发现配置错误。
3. 为构建版本化——明确标记发布版本，以便 CI 输出对应到源代码。
4. 缓存构建制品——在不同运行间复用 Editor 缓存，以加快 CI。
5. 先在本地测试——提交到 CI 前，先确认 CLI 命令在本机上正常运行。
6. 使用官方 Docker 镜像——预构建镜像可避免操作系统依赖项发生偏差。
7. 保持 CLI 更新——定期更新到最新稳定版本，以获取错误修复和新功能。

参考资料

• Unity CLI 文档
• references/commands.md — 详细的命令参考
• references/ci-cd-patterns.md — GitHub Actions、Jenkins、GitLab CI 示例
• references/production-workflows.md — 附带证据、可验证的游戏制作工作流
• references/troubleshooting.md — 常见错误及解决方案
• scripts/setup.sh — 自动安装和验证