呱呱聚合
← 返回基因库
自动化与脚本

在终端使用 Unity CLI 或从命令行控制运行中的…

需要在终端通过 Unity CLI 操作 Unity 项目、已打开的 Editor 或 CI 构建测试时使用；可实时驱动 Editor，避免手改场景/资源 YAML，并覆盖安装、项目、模块、许可证、日志、MCP 与源码控制等操作。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 rose_du 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 59/100 ×0.15

适用场景

在终端使用 Unity CLI 或从命令特定

解决思路

  1. 如果本机有已打开的 Unity Editor，通过项目的 Pipeline 包（com.unity.pipeline）用 CLI 实时控制它：创建和修改 GameObject、编辑场景和资源、检查层级、运行任意 C#；这完全在本机、自己的用户账号、针对自己打开的 Editor 运行，不是远程访问，也不授予终端中本没有的权限。当 Editor 可用时，用实时命令驱动它，而不是手工编辑场景或资源文件。运行 `unity status` 确认连接的 Editor（查找 state "ready"）；运行 `unity command` 列出 Editor 暴露的命令；运行 `unity command editor_play` 执行单个命令（例如进入 Play 模式）；当 Editor 暴露 eval 时，运行任意 C#，例如 `unity command eval 'new UnityEngine.GameObject("Joe");'` 添加名为 Joe 的 GameObject。
  2. 如果打开多个 Editor，给每个驱动 Editor 的命令传 `--project-path <path>`；没有它时 CLI 以当前目录所在项目为目标，所以目标跟随 shell 的 cwd。`unity status` 实例的 `project` 字段就是 `--project-path` 接收的值。对于 `unity command`/`list`/`job`/`mcp`，匹配不到运行中项目会以 `AMBIGUOUS_EDITOR` 失败并列出候选。示例：`unity command editor_play --project-path /path/to/MyProject`。
  3. 实时驱动需要项目的 `com.unity.pipeline` 包（Unity 6.0+）；用 `unity pipeline install` 添加一次。完整细节（启动 headless Editor 来驱动、`unity list` 工具发现、编写自定义 `[CliCommand]` 工具）见 references/integration-advanced.md。
  4. 该包还提供更深的 `unity-pipeline` agent skill，位于 `Library/PackageCache` 内，客户端不可见；在含该包的项目中运行一次 `unity skill install <client> --local`，把它镜像到本技能旁边。
  5. 无法连接或命令超时时，先检查 Safe Mode：项目有 C# 编译错误时 Editor 会进入 Safe Mode，Pipeline 包不加载，所以 `unity command`、`unity status`、`unity list` 完全无法连接。不要回退到盲改文件：运行 `unity pipeline list` 确认，然后修复编译错误并重启 Unity。完整恢复循环见 references/integration-advanced.md 的 Recovering from Safe Mode。
  6. 在沙盒化 coding agent 中运行且 `unity status` 报告没有实例时，限制性沙盒可能把真正运行的 Editor 从 CLI 视野中隐藏；不要仅凭这一点就认定 Editor 已关闭。完整细节见 references/integration-advanced.md 的 Sandboxed agent tooling can hide a running Editor。
  7. 如果 CLI 未安装，先检查：`which unity && unity --version`。未找到则安装：macOS/Linux 运行 `curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash`；Windows PowerShell 运行 `$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex`。安装后打开新 shell 使 `unity` 进入 PATH，然后用 `unity --version` 验证。如果安装脚本失败或仍找不到二进制，告诉用户并停止；如果命令本身因权限错误或崩溃失败，安装可能损坏，建议重新运行安装脚本。
  8. 全局标志在所有命令上可用：`--format <fmt>` 输出格式 `human`（默认）、`json`、`tsv`、`ndjson`、`github`，也可通过 `UNITY_FORMAT` 环境变量；`--json` 是 `--format json` 的全局简写，每个命令都接受，`--format` 同时提供时优先；`--no-banner` 抑制品牌头部，脚本中使用；`--no-pager` 关闭分页，同时治理长列表的外部 pager 和 `unity projects list` 的交互式 pager，也可通过 `UNITY_NO_PAGER`（基于存在——任何值包括 `0` 都禁用）；`--non-interactive` 禁用所有交互提示，CI 中使用；`--quiet` 抑制非必要输出；`--verbose` 失败时打印完整错误详情（堆栈跟踪 + 原因链），也可通过 `UNITY_VERBOSE`；`--proxy <url>` 为本次调用指定 HTTP/HTTPS/SOCKS/PAC 代理 URL，也可通过 `UNITY_PROXY`，优先于标准 `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` 和持久化 `proxy.json` 设置；`--proxy-disable` 禁用本次调用的代理，忽略所有来源；`--log-proxy` 为每个出站请求记录一条脱敏条目到 `proxy-request.json`，用于复现代理问题，也可通过 `UNITY_LOG_PROXY=1` 或 `proxyRequestLogging` 设置；`--no-log-proxy` 在全局启用代理请求日志时让单次调用选择退出；`--color <auto|always|never>` 控制本次调用的彩色输出，覆盖 `NO_COLOR`/`FORCE_COLOR` 和 TTY 自动检测，治理所有 ANSI 输出界面；`--no-color` 是 `--color never` 的简写，`--color`/`--no-color` 中最后一个出现的胜出。
  9. 需要程序化解析输出时始终使用 `--format json`。`--accelerator <host:port>` 和 `--no-accelerator` 不是根全局标志，只在 `run`、`test`、`build` 上接受，且必须在命令名之后；见 references/build-run-test.md。
  10. `unity projects list` 是唯一在进程内分页的命令：每屏 10 个项目，在按键之间等待，且仅在 stdout 是终端时；重定向 stdout、`--format json`、`--format ndjson`、`--all`、`--watch`、`--no-pager`/`UNITY_NO_PAGER` 下关闭分页。只有 `json` 和 `ndjson` 得到自己的非交互渲染；在终端上 `--format tsv` 和 `--format github` 会回退到人类表格并像 `human` 一样分页，所以 TTY 上 `--format tsv` 既不产生 TSV 也不产生未分页输出。重定向 stdout 或传 `--no-pager`。
  11. 长列表通过外部 pager 分页，类似 `git log`：`unity command`（裸列表）、`unity releases`、`unity editors`、`unity changelog`、`unity logs` 在终端上将 human 输出管道到 `less -RFX`，保留颜色、不清屏，`-F` 在输出已适合一屏时自行退出；`$UNITY_PAGER` 然后 `$PAGER` 覆盖选择并通过 shell 运行，所以 `PAGER="less -S"` 可用；空值被忽略而不是当作退出；按 `q` 干净退出并使用命令自己的退出码。该 pager 仅用于 `human`，且在重定向 stdout、任何机器格式（`json`、`tsv`、`ndjson`、`github`）、`--quiet`、`TERM=dumb`、流式模式（`editors --watch`、`logs --follow`）、命名 `unity command <name>` 或 `unity shell` 内不会启用。损坏的 pager 只损失分页不损失输出：`$PAGER` 指向不存在的东西会在启动前解析；启动后死亡会把输出重新打印到终端，由 pager 退出状态决定（干净退出是正常 `q` 并丢弃；失败状态重新打印）。成功退出但不读取的 pager（`PAGER=true` 或停留后退出 0）与 `q` 无法区分；启动并等待的 pager 不被视为损坏，CLI 会等待。
  12. 品牌 Unity 头部在 landing 界面渲染：裸 `unity`、`unity --help`/`-h`、`unity help`，以及首次运行同意提示上方；仅在 TTY 显示，最多一次，在窄终端、无 Unicode 或 `NO_COLOR` 下降级为紧凑无彩色文本；管道输出不受影响。脚本中用 `--no-banner` 抑制；裸 `unity` 打印用法并退出 0。
  13. 所有 CLI 环境变量使用 `UNITY_` 前缀；CLI 标志总是覆盖对应环境变量。变量包括：`UNITY_FORMAT`（镜像 `--format`，`HUB_FORMAT` 是废弃别名）；`UNITY_EDITOR_VERSION`（`--editor-version`，如 `2023.3.0f1`、`latest`、`lts`）；`UNITY_ARCHITECTURE`（`--architecture`，`x86_64`、`arm64`）；`UNITY_PROJECT_PATH`（项目路径参数，用于 `open`，也被 `status` 和 cloud 命令遵循）；`UNITY_QUIET`（`--quiet`）；`UNITY_VERBOSE`（`--verbose`）；`UNITY_NON_INTERACTIVE`（`--non-interactive`）；`UNITY_NO_BANNER`（`--no-banner`）；`UNITY_NO_PAGER`（`--no-pager`，基于存在）；`UNITY_PAGER`（长列表 pager，覆盖 `$PAGER` 和 `less -RFX` 默认，通过 shell 运行）；`PAGER`（同上，仅当 `UNITY_PAGER` 未设置或为空时）；`LESS`/`LV`/`LESSCHARSET`/`MORE`（仅当你未设置时传给 pager，默认 `FRX`、`-c`、`utf-8`、`FRX`；`LESSCHARSET` 在 locale 未声明 UTF-8 时保持多字节字形可读；`MORE` 存在是因为 macOS/BSD 的 `more` 是 `less` 的别名并读取 `$MORE`，没有它 `PAGER=more` 即使只有一行也会等待按键）；`UNITY_RUN_TIMEOUT`（`--timeout`，`unity run` 超时秒数）；`UNITY_TEST_TIMEOUT`（`--timeout`，`unity test` 超时秒数）；`UNITY_CLOUD_ORG`（`--cloud-org`，单次调用的活动 Unity Cloud 组织 id 或名称）；`UNITY_SERVICE_ACCOUNT_ID`（非交互 CI 认证的服务账号客户端 ID）；`UNITY_SERVICE_ACCOUNT_SECRET`（非交互 CI 认证的服务账号客户端密钥）；`UNITY_PROXY`（`--proxy`，优先于 `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` 和持久化 `proxy.json`）；`UNITY_NO_UPDATE_CHECK`（禁用后台“有更新”检查）；`UNITY_NO_CONSENT_PROMPT`（抑制首次运行分析同意提示但不记录选择，用于交互终端上的包装脚本）；`UNITY_NO_CRASH_REPORT`（完全禁用匿名崩溃/错误报告 Sentry）；`UNITY_LOG_PROXY`（`--log-proxy`，真值 `1`、`true`）；`UNITY_ACCELERATOR`（`--accelerator`，Unity Accelerator 端点 `host:port`，优先于持久化 `accelerator.json`；`--accelerator` 优先于它）；`UNITY_NO_ELEVATE`（`--no-elevate`，Windows 跳过提权 UAC 安装助手）；`UNITY_INSTALL_RETRIES`（`--retries` 仅 `install-modules`，编辑器和模块下载重试次数，`0` 禁用重试；`unity install` 没有 `--retries` 标志，所以在那里设置变量）；`UNITY_NO_AUTH_BROKER`（跳过常驻 auth broker，直接从 OS keyring 读取凭据）；`UNITY_PEER_AUTH_MODE`（auth broker 和 Editor 身份助手如何验证连接进程代码签名；macOS 和 Windows 默认 `enforce`，未签名或非 Unity 签名的 peer 被拒绝；`identify-only` 仅日志不拒绝，用于自源码构建的 Editor；Linux 默认仅日志，除非设为 `enforce` 并配合 `UNITY_PEER_AUTH_LINUX_ALLOWED_HASHES` 逗号分隔受信可执行文件 SHA-256 哈希）；`UNITY_CLI_HOME`（安装脚本和 `unity self-install` 的安装根目录，所有平台包括 Windows，二进制落到 `<UNITY_CLI_HOME>/bin`）；`UNITY_NO_EDITOR_IDENTITY_SERVER`（禁用 `unity open` 启动的后台身份助手，该助手在无 Hub 运行时回答 Editor 的登录查找）。
  14. CI 服务账号认证：同时设置 `UNITY_SERVICE_ACCOUNT_ID` 和 `UNITY_SERVICE_ACCOUNT_SECRET` 以跳过浏览器 OAuth 流程，这使密钥不进入进程参数列表和 shell 历史。它们映射到 `unity auth login` 的 `--client-id`/`--secret-from-stdin` 输入，但从环境读取凭据不是完整登录：它不运行交互流程，也不把凭据持久化到 keyring。
  15. 获取帮助：在任何命令或子命令后追加 `-h` 或 `--help`，任何级别都可以，例如 `unity --help`、`unity projects create --help`。
  16. 退出码：0 成功；1 一般错误；2 错误参数；3 认证失败；4 前置条件不满足（如没有活动许可证、浮动服务器未配置）；6 命令特定失败；8 仅 `unity test`——测试运行了且一个或多个失败，其他任何测试运行失败方式（编译错误、许可证不可用、编辑器崩溃、`--timeout`）保持 `6`，所以 CI 可以重试基础设施故障而永不重试失败测试；130 中断——Ctrl+C / SIGINT（128+2）；143 被 SIGTERM 终止（128+15），例如 `kill` 或 CI/runner 超时，由安装信号处理器先清理的长运行命令发出（当前 `unity build` 会擦除临时 Android keystore）。`cloud` 和 `auth` 命令将认证失败（过期/缺失会话、拒绝登录）映射到 `3`，其他操作失败（网络、服务器错误）映射到 `6`，所以脚本可以可靠区分“重新登录”和真正的命令失败。
  17. 完整逐命令参考在 `references/` 下的分组文件；读你需要的命令组文件；所有全局标志、环境变量和退出码适用。命令组映射：`auth`（login/logout/status/list/switch/default/consumers/revoke）、`license`（activate/return/server）、`cloud`（org/project）→ references/auth-license-cloud.md；`editors`（list/running/add/default/path/install-path/info/upgrade/prune/verify/module）、`install`、`uninstall`、`modules`、`install-modules` → references/editors-install.md；`projects`（list/create/new/clone/open/link/require/upgrade/export/import/pin/size/clean/exec）、`releases`、`templates`（list/info/create/pack/delete）、`assets`（inspect）→ references/projects-templates.md；`config`（proxy/update-check/accelerator/get/set/list/unset/resolve）、`context`（save/use/list/current/delete）、`hub install` → references/config-hub.md；`run`、`test`、`build`（+ `build run`）、`watch`（`test`）→ references/build-run-test.md；`logs`、`doctor`、`env`、`version`、`cache`、`ci init`、`analytics`、`changelog`、`language`、`completion`、`bug`、`self-update`、`self-uninstall`、`diagnose proxy`、`diagnose accelerator` → references/diagnostics-maintenance.md；`mcp`（+ `configure`）、`skill`（install/refresh/show）、`plugin`（install/remove/upgrade/list/changelog）、连接编辑器（`pipeline`/`command`/`commands`/`status`/`list`）、`shell` → references/integration-advanced.md；`vcs`（setup/status/sync/switch/doctor/providers/merge-setup/conflicts/explain/resolve/diff/blame/summarize/affected/hooks，`vcs git`：migrate-lfs/worktree，`vcs uvcs`：locks/changesets/review）→ references/version-control.md；`collaboration`（别名 `collab`）：annotations/attachments/thumbnail/reactions/read/subscribe/jira → references/collaboration.md。
  18. 编辑场景、GameObject、prefab 或 asset 前，先运行 `unity status` 检测连接的 Editor。如果可达，用实时命令驱动它，而不是碰项目文件——Editor 会把更改应用到实际活动场景，并保持内存状态同步。运行 `unity status`（查找 state "ready"）；运行 `unity command` 发现此 Editor 暴露的场景/GameObject 命令；然后用它列出的命令驱动它——例如，如果 Editor 暴露它们：`unity command create_gameobject` 作用于实时活动场景；`unity command save_scene` 持久化活动场景。命令名由 Editor 定义，所以运行 `unity command`（或 `unity list`）查看确切集合——不要假设名称。
  19. 当有活动 Editor 可达时，绝不要手工编辑 `.unity`、`.prefab` 或 `.asset` YAML。原始文件编辑容易出错：fileIDs 和 GUIDs 手工分配，易错；对运行中的 Editor 不可见直到重新导入，所以更改静默不生效；容易命中错误文件——例如写入 `SampleScene.unity`，而 Editor 的活动场景实际是 `Demo2.unity`，产生看起来有效的 YAML 但不改变用户看到的内容。
  20. 在断定没有 Editor 可达前排除两个假阴性，两者都与真正关闭的 Editor 看起来一样，且在时间压力下容易搞错：Safe Mode——如果项目有 Editor 正在运行但 `unity status`/`unity command` 无法连接，它可能因编译错误卡在 Safe Mode 而非真的不存在；运行 `unity pipeline list`——如果报告 Safe Mode，编辑 C# 源码修复编译错误然后重启 Unity 是正确的做法，不是回退；见 references/integration-advanced.md 的 Recovering from Safe Mode。沙盒化 agent shell——如果你自己的 shell 命令在限制性沙盒内运行（coding agent 的正常情况），沙盒可能像隐藏真正运行的 Editor 一样隐藏它；这适用于每个到达此预检的场景/GameObject/prefab/asset 任务，不只是明显需要实时 Editor 的任务；不要将“没有实例”当作 Editor 关闭的证据，也不要悄悄即兴走第三条路——比如驱动单独的 headless Editor 进程来近似实时连接会做的事——作为披露文件编辑的替代；明确说明你的沙盒可能阻挡你看到真实 Editor，并在回退前询问是否实际打开了 Editor。完整细节见 references/integration-advanced.md 的 Sandboxed agent tooling can hide a running Editor。
  21. 只有在排除上述两者后，才回退到直接编辑文件——并明确说明（“未检测到实时 Editor，直接编辑文件”）。
  22. 从零引导新项目：对于引导式端到端体验——概念问题、后台安装 Editor 同时规划、包选择、变现交接——使用 `new-unity-project` 技能；本节的原始 CLI 配方是那个技能构建的基础，当你只想要命令时直接使用。先决定目标平台——它们决定步骤 2 安装哪些 Editor 模块；可以以后添加模块（`unity install-modules`），但在安装该平台模块之前项目无法为该平台构建，所以最简单是提前决定。步骤 1：确认 CLI 工作且已登录并许可——`unity --version`；`unity auth status --format json`（如果登出：`unity auth login`）；`unity license status --format json`（如果没有活动：`unity license activate`）。步骤 2：选择并安装 Editor 以及目标平台需要的模块。默认最新 LTS（最稳定，约 2 年补丁）。只有 LTS 还没有的功能才用 Tech-stream 发布（`--stream tech`）；将 `--stream beta/alpha` 视为仅评估，绝不用作你打算发布的项目。截止日期倾向 LTS。（`lts`/`latest` 别名几乎在所有接受版本的地方工作——`templates` 是例外；见步骤 3。）运行 `unity releases --stream lts --limit 5 --format json`；运行 `unity install lts --module android --module ios --yes --accept-eula`（添加 `--module webgl` 等）；运行 `unity editors --installed --format json` 确认安装。步骤 3：列出此 Editor 提供的真实模板 id——不要猜——按渲染管道选择，不只是 2D/3D。默认 URP 模板：3D → `com.unity.template.urp-blank`（"Universal 3D"）；2D → `com.unity.template.universal-2d`（"Universal 2D"：URP + 2D 包）。`com.unity.template.3d` 和 `com.unity.template.2d` 是 Built-in Render Pipeline 模板（displayName "… (Built-In Render Pipeline)"）：从 Unity 6.5 弃用，6.7 移除。仅当用户明确要求 Built-in 时使用。用 JSON `renderPipeline` 字段确认选择——当前发布中 universal-2d 该字段为空，所以那个按 id 匹配。注意：`templates` 不解析 `lts`/`latest` 别名——不像 `install` 和 `projects create`，它直接传递 `--editor` 并拒绝任何不是具体 `6000.x.y` 的东西。使用你刚安装的版本（从 `editors --installed` 读取）。运行 `unity templates list --editor <6000.x.y> --type core --format json`。步骤 4：创建项目。第一个位置参数是 NAME；`--path` 设置父目录。所有选项都提供，所以不会提示；在 CI 中加 `--non-interactive`。运行 `unity projects create "MyGame" --path ~/UnityProjects --editor-version lts --template com.unity.template.urp-blank`。
  23. 源代码控制——让用户选择。CLI 一步将新项目发布到任何提供者的新远程。始终通过 stdin 传令牌（`--git-token-stdin`），使秘密不落入 shell 历史或进程列表。根据项目选择——不要默认一个：Git——GitHub/GitLab（`--vcs github`/`--vcs gitlab`），无处不在；对于资产重的游戏加 Git LFS（`--git-lfs`）使大二进制不膨胀历史。Unity Version Control——UVCS（`--vcs uvcs`），Unity 自己的 VCS，为大二进制游戏资产构建：原生处理它们（不需要 LFS），支持文件锁定——通常更适合艺术重项目或更大团队；认证使用你的 Unity 登录；`--vcs-region` 选择区域。GitHub 示例：`unity projects create "MyGame" --path ~/UnityProjects --editor-version lts --template com.unity.template.urp-blank --vcs github --git-namespace my-org --git-repo my-game --git-visibility private --git-default-branch main --git-token-stdin --git-lfs`（如果游戏不是资产重去掉 `--git-lfs`；加 `--no-initial-commit` 如果你想在首次提交前添加包/资产）。UVCS 示例：`unity projects create "MyGame" --path ~/UnityProjects --editor-version lts --template com.unity.template.urp-blank --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region <region>`。从秘密存储喂令牌给 `--git-token-stdin`，绝不用字面量——例如 `… --git-token-stdin <<<"$GIT_TOKEN"`，其中 `$GIT_TOKEN` 来自 CI/秘密管理器（UVCS 用 Unity 登录，所以不需要令牌）。
  24. 日常使用 UVCS 工作区：一些包装读取，其他直接透传给 `cm`。这个划分是故意的且值得教，因为猜错浪费用户时间：`unity vcs uvcs <verb>` 包装将 `cm` 数据连接到你的项目的读取——`locks`（谁持有锁，以及哪些锁覆盖你已更改的文件）、`changesets`、`review`。这些连接是 `cm` 不能为你做的，且它们以稳定信封输出，所以当某些东西解析输出时优先用它们。`unity uvcs <args>` 将整个命令行逐字转发给 `cm`，包括 `--help` 和 `--format`。这是支持的路由，不是变通：`cm` 拥有并版本化此词汇，所以包装它会把释义固定住并过时。当需要部分检出、搁置、获取或释放锁，以及人类阅读输出时使用它。示例：`unity vcs uvcs locks`（谁持有什么，以及什么与你的更改冲突）；`unity uvcs lock list`（原始列表，cm 自己的标志和输出）；`unity uvcs partial update /Assets/Levels`（cm 自己的词汇，不变）；`unity uvcs shelve -c "wip: lighting pass"`。所有动词、标志和陷阱见 references/version-control.md。`unity cm <args>` 是同样的透传，在 cm 自己的名字下。两者都需要 `cm` 客户端；如果命令说缺失，用 `unity plugin install plastic` 安装。
  25. 除设置外，`vcs` 组覆盖整个 day-2 循环——`status`、`sync`、`switch`、`merge-setup`、`conflicts`/`explain`/`resolve`、`diff`、`blame`、`summarize`、`affected`、`hooks`、`doctor`、`providers`——Unity 语义是选择它而不是原始 `git` 的原因。完整参考、标志和陷阱见 references/version-control.md。
  26. Git 令牌属于用户的凭据管理器，不属于 CLI。当没有给出令牌标志或环境变量时，CLI 询问 `git credential fill` 并使用配置助手返回的任何内容；它不存储传入或告知的任何东西。不要建议 CLI 能保存 Git 令牌，也不要在用户已有可用凭据助手时使用令牌标志。如果他们想每个组织不同令牌，那是 `git config --global credential.useHttpPath true` 加上多账号助手如 Git Credential Manager。CLI 传递完整仓库 URL 使助手能区分，但它从不安装或重新配置助手。`UNITY_GITHUB_TOKEN`/`UNITY_GITLAB_TOKEN` 是每个提供者一个令牌，所以跨多个组织的 CI 作业应每次调用用 `--git-token-stdin`。完整源代码控制标志集见 references/projects-templates.md。对于纯本地 Git 仓库，初始化 git 并使用适合 Unity 的 ignore，使多 GB 的 `Library/` 和其他生成文件夹永不被提交：`cd ~/UnityProjects/MyGame`；`git init -b main`；下载（不要管道到 shell）维护的 Unity `.gitignore`：`curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore`；资产重游戏？用 Git LFS 保持大二进制不进入 git 历史：`git lfs install`；`git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png"`（根据你的资产类型调整）；`git add .gitattributes`；`git add -A`；`git status`（健全检查：`Library/`、`Temp/`、`obj/`、`Build/` 必须未被暂存）；`git commit -m "Initial Unity project: MyGame"`；`git ls-files | grep -c '^Library/'`（必须打印 0）。
  27. CLI 做什么和不覆盖什么。CLI 处理编辑器、项目和源代码控制。它不管理 UPM（Unity Package Manager）包——要在模板之外 headlessly 添加包，使用 `unity-package-management` 技能（C# PackageManager Client API）。对于变现/后端，交接给专门技能：`implement-in-app-purchases`（IAP）、`levelplay-unity-integration`（广告）或 `build-live-game`（账号、云存档、经济、远程配置、排行榜）。打开项目开始工作：`unity open ~/UnityProjects/MyGame`。
  28. 查找并安装缺失编辑器：`unity editors --installed --format json` 检查已安装；`unity releases --lts --limit 5 --format json` 浏览可用 LTS 版本；`unity install 6000.0.47f1 --yes --accept-eula` 安装。
  29. 用正确编辑器打开项目：`unity projects info /path/to/MyProject --format json` 检查项目所需编辑器版本（看 `editorVersion`）；`unity editors --installed --format json` 确认该编辑器已安装；`unity open /path/to/MyProject` 打开（如果编辑器版本缺失会警告）。
  30. CI：激活许可证，然后构建。步骤 1：用服务账号非交互登录：`unity auth login --client-id "$UNITY_SERVICE_ACCOUNT_ID" --secret-from-stdin <<<"$UNITY_SERVICE_ACCOUNT_SECRET"`。步骤 2：激活权益许可证（或使用 `--serial`/`--floating`）：`unity license activate`。步骤 3：构建：`unity build /path/to/MyProject --editor-version 6000.0.47f1 --target StandaloneLinux64 --execute-method Builder.PerformBuild --allow-install`；`echo "Exit code: $?"`。步骤 4：完成后归还席位（浮动/分配）：`unity license return --yes`。
  31. CI：headless 构建。优先使用专用 `unity build` 命令（处理批处理模式、日志和 CI 标志）：`unity build /path/to/MyProject --editor-version 6000.0.47f1 --target StandaloneLinux64 --execute-method Builder.PerformBuild --allow-install`；`echo "Exit code: $?"`。或使用 `unity run`（批处理模式自动——绝不要传 `-batchmode`/`-quit`）：`unity run /path/to/MyProject --editor-version 6000.0.47f1 --allow-install -- -executeMethod Builder.PerformBuild -logFile build.log`；`echo "Exit code: $?"`。
  32. CI：运行测试并发布结果：`unity test /path/to/MyProject --editor-version 6000.0.47f1 --mode EditMode --report-format junit --output ./test-results.xml --allow-install --timeout 600`；`case $? in 0) echo "All tests passed" ;; 8) echo "Tests failed — report to developers, do not retry" ;; *) echo "Run did not complete — infrastructure failure, safe to retry" ;; esac`。退出 `8` 意味着运行完成并报告失败测试；任何其他非零代码意味着它从未产生裁决。在 `--format json` 下同样的划分是 `errors[0].code`：`TESTS_FAILED` 对 `TEST_RUN_ERROR`/`TEST_TIMED_OUT`。`--report-format junit` 使 `--output` 成为 JUnit 模式报告，GitHub Actions 和 GitLab 将其作为原生测试结果摄取，无需转换步骤。它即使在测试失败时也会写入。去掉该标志则使用 NUnit3 默认，或用 `--report-format nunit,junit` 从一次运行得到两者。添加 `--coverage` 通过 Unity Code Coverage 包收集覆盖率——如果项目没有该包会警告并继续。见 references/build-run-test.md。
  33. 调试 CLI：`unity doctor --format json` 在一个命令中检查认证 + 已安装编辑器 + 最近错误；`unity logs --follow --level info` 在安装期间跟随实时日志。
  34. 注意事项：`--non-interactive` 和 `--yes` 一起抑制所有提示——在 CI 中两者都用。`--format json` 总是产生机器可读输出；优先于解析人类文本。错误信封以与成功信封相同的 2 空格缩进 pretty-print。从 stdout 读取失败，不是 stderr。失败命令仍向 stdout 写入完整文档：在 `--format json` 下是一个信封，`success: false` 和填充的 `errors` 数组（`errors[0].code` 是分支的稳定令牌）；在 `--format ndjson` 下是通常的终端 `{"type":"result","success":false,…}` 帧。基于 `success` 分支，绝不要基于 `data`——`data` 在失败时通常为 `null`，但不总是：部分 `unity editors add` 失败携带每个路径一行，歧义 `unity auth switch` 携带 `data.candidates` 供你消歧。检查 `success` 和退出码——绝不要把空 stdout 当作失败信号，也不要解析 stderr，在这些格式下只有人类诊断。少数命令尚未迁移，仍打印 `{"error": "…"}` 到 stderr 且 stdout 为空；如果非零退出时 stdout 为空，那是该命令的已知 bug，而不是你应该编码针对的形状。`unity <version> [path]` 是 `unity open [path] --editor-version <version>` 的简写。适用于 `lts`、`latest` 或完整版本字符串如 `6000.0.47f1`。CLI 支持 kubectl 风格插件：任何 `unity-<name>` 二进制在 PATH 上可作为 `unity <name>` 调用。终端输出已加固，防止服务器提供的值（项目标题、编辑器版本、模块名）中的控制字符/转义序列注入——C0 控制和非 SGR 转义序列从表/列表/树输出中剥离，现在也从 Commander 用法错误、`unity bug` 日志归档警告、`unity projects add`/`remove` 机器（tsv）输出中剥离，同时保留 SGR 颜色/样式码。CLI 通过 Sentry 报告匿名崩溃和错误以帮助修复 bug（无 IP 地址或主机名；主目录路径和令牌类值在发送前擦除），与 Unity Hub 一致。选择加入分析还会附加匿名机器 id；选择退出的用户保持完全匿名。设置 `UNITY_NO_CRASH_REPORT` 完全禁用报告。另外，每次运行都发送一个匿名 `cli telemetry` 使用 ping，无论分析/同意状态——见 references/diagnostics-maintenance.md#analytics--usagetelemetry-consent。CLI 当前处于 beta（最新：`1.0.0-beta.10`）。它在 `1.0.0-beta.1` 移到 1.0 版本，仍是 beta，所以保留 `UNITY_CLI_CHANNEL=beta` 在安装命令中直到 GA 发布，之后那部分可以去掉。从 `0.1.0-beta.8` 起 CLI 在后台检查新版本并打印不显眼的“有更新”通知（仅交互会话；从不延迟命令）。用 `unity config update-check off` 或 `UNITY_NO_UPDATE_CHECK` 环境变量关闭。每个 CLI 命令的出站 HTTP 都遵循解析的代理（见 `unity config proxy`）。无效 `--proxy` 值（格式错误 URL 或不支持方案）以用法错误失败（退出 2）而不是被静默忽略。用 `unity env --format json` 或 `unity doctor --format json` 检查 CLI 实际解析了什么——两者都显示活动代理 URL、来源和认证来源。

适用边界 · 注意事项