TEngine 集成指南:Unity Pipeline 构建 / 编译 / 测试命令全解析
TEngine 集成指南:Unity Pipeline 构建 / 编译 / 测试命令全解析
本文面向 TEngine(Unity 商用级开发框架)使用者,系统讲解
com.unity.pipeline包提供的构建、编译与测试命令族:如何通过本地 HTTP API 驱动运行中的 Unity Editor 完成 Player 构建(build/build_status)、切换构建目标(switch_build_target)、读写构建配置(get_build_settings/set_build_settings)、强制脚本重编译(recompile)以及运行测试(run_tests/test_status)。读完本文,你将掌握这套"触发—轮询(trigger-then-poll)"异步命令模式的完整用法、每个参数的语义与返回值结构,以及底层源码的实现原理,可直接对接 CI、CLI 或 Agent 自动化工作流。
命令族概览与核心设计模式
com.unity.pipeline 让 CLI、CI 或 AI Agent 通过本地 HTTP 接口驱动一个正在运行的 Unity Editor(或开发版 Player)执行注册命令。本文档对应命令参考页 build-and-compilation.md,覆盖三大类共 14 个命令:
| 类别 | 命令 |
|---|---|
| 构建 | build、build_status、switch_build_target、switch_build_target_status |
| 构建配置 | list_build_targets、get_build_settings、set_build_settings、list_build_profiles |
| 编译与测试 | recompile、recompile_status、list_tests、run_tests、test_status、cancel_tests |
阅读之前,先建立三个关键认知,它们贯穿全部命令:
- 触发—轮询(trigger-then-poll)异步模式:
build、switch_build_target、recompile、run_tests(异步模式)等命令会立即返回一个瞬时状态(如queued/switching/compiling/running),真正的耗时操作随后在编辑器的EditorApplication.update回调中执行。客户端必须轮询对应的*_status命令,直到状态变为completed。原因很直接:BuildPipeline.BuildPlayer、SwitchActiveBuildTarget等 API 是同步阻塞的,会长时间占用主线程,如果命令内联执行,会卡死服务器串行请求循环,调用永远无法返回。 MainThreadRequired = false的状态命令:build_status、switch_build_target_status、recompile_status、test_status都标记为MainThreadRequired = false,它们在后台线程直接读取 Temp 目录下的 JSON 状态文件,因此即使构建/切换正在霸占主线程,轮询依然能持续应答;状态文件还能在域重载(domain reload)后幸存,保证最后的状态可被恢复。confirm/dry_run变更门禁:所有破坏性或长耗时操作(真实构建、切换目标、改写设置)都要求显式传入confirm=true才会执行;dry_run=true则只做校验与预览、不产生任何变更。这是整个包统一的变更安全约定,详见 safety-and-mutations.md。
客户端在调用这些命令前,需要先通过端口描述文件发现实例并携带 bearer token 鉴权,连接方式见 connectivity.md;自定义命令的编写规范见 creating-commands.md。
build:触发异步 Player 构建
build 触发一次异步 Player 构建,并在完成后报告完整的 BuildReport。调用后立即返回(已入队),需要轮询 build_status 直到状态为 completed。默认包含 DetailedBuildReport,除非显式传入了 options 参数。
参数契约
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
target |
否 | – |
BuildTarget 名称(如 StandaloneWindows64),缺省使用当前活动目标,目标必须已安装 |
outputPath |
否 | – |
输出路径(绝对路径,或相对项目根目录),缺省使用上次/自动路径 |
profileName |
否 | – |
构建前激活的 Build Profile 名称(仅 Unity 6,其他版本忽略) |
options |
否 | – |
BuildOptions 名称列表;省略则只带 DetailedBuildReport;一旦提供任意值即禁用该默认 |
scenes |
否 | – |
参与构建的场景资源路径(如 Assets/Scenes/Main.unity),缺省使用 EditorBuildSettings |
confirm |
否 | false |
确认并执行构建;不传则调用被拒绝,校验用 dry_run |
dry_run |
否 | false |
只校验 target / outputPath / scenes,不执行构建 |
支持的 options 取值
options 取值不区分大小写,且只接受以下白名单——任何未识别的值都会触发校验错误而非被静默忽略,这是为了让拼写错误直接暴露而不是悄悄改变构建形态。源码中的完整映射表见 BuildCommand.cs 的 s_SupportedOptions:
| 选项 | 对应 BuildOptions | 说明 |
|---|---|---|
Development |
BuildOptions.Development |
构建 Development Player(启用调试器/Profiler) |
AllowDebugging |
BuildOptions.AllowDebugging |
允许脚本调试 |
ConnectWithProfiler |
BuildOptions.ConnectWithProfiler |
自动连接 Profiler |
EnableHeadlessMode |
BuildOptions.EnableHeadlessMode |
无头模式(Unity 6 中已过时,仍被接受并抑制弃用警告) |
SymlinkSources |
BuildOptions.SymlinkSources |
软链接源文件而非复制 |
BuildAdditionalStreamedScenes |
BuildOptions.BuildAdditionalStreamedScenes |
构建额外流式场景 |
CleanBuildCache |
BuildOptions.CleanBuildCache |
清理构建缓存 |
DetailedBuildReport |
BuildOptions.DetailedBuildReport |
生成详细构建报告(默认值) |
注意:一旦你自行提供了任意
options,默认的DetailedBuildReport就会被禁用。而BuildReport.packedAssets(打包资源明细)只有在DetailedBuildReport存在时才非空——因此除非你有明确理由,建议保留该默认选项。
返回与状态流转
build 返回 object,瞬时负载为 queued / busy / dry_run / error 之一,完成的报告通过 build_status 读取。典型交互流程:
- 不带
confirm调用 → 返回{ status = "error", success = false, message = "Refused: ... Pass confirm=true to build, or dry_run=true to validate without building." },调用被拒绝且不入队。 - 带
dry_run=true→ 返回{ status = "dry_run", valid, validationErrors },只校验不构建。 - 校验失败(如未知 target、未安装的构建支持、不存在的场景路径、无父目录的输出路径)→ 返回
{ status = "error", success = false, validationErrors, message = "Build configuration is invalid; nothing was queued." },同样不入队。 - 带
confirm=true且校验通过 → 生成buildId(格式build_+ 12 位十六进制),写入{"status":"queued"}状态文件并返回{ status = "queued", buildId }。此后编辑器 tick 会执行阻塞构建,客户端轮询build_status。
同一时间只允许一个构建:当已有构建在排队或进行中时,再次调用返回 busy。
从源码看,build 的完整调用链是:HTTP 请求 → RunOnMain 分发到主线程 → ValidateAndQueue 校验并置 s_Pending 标志 → 下一个 EditorApplication.update tick 的 OnUpdate 消费排队请求 → RunBuild 构造 BuildPlayerOptions(含 scenes、locationPathName、target、targetGroup、options)→ 调用 BuildPipeline.BuildPlayer → Project 方法把 BuildReport 投影为 JSON 友好的 BuildReportResult 并写回状态文件。校验阶段还会做一次非变异检查:解析输出路径并确认其存在某个祖先目录,从而在 dry run 阶段就发现"输出目录无法创建"的问题(BuildPipeline 会自己创建叶子目录,所以这里从不实际创建任何东西)。默认输出路径由 ResolveOutput 计算:<项目根>/Builds/<target>/<产品名>.<扩展名>,其中扩展名规则见 BuildCommand.cs——Windows 为 .exe、macOS 为 .app、Android 为 .apk,Linux 独立版等则无扩展名。
build_status:读取构建报告
build_status 无参数,返回当前/最近一次构建的状态:idle | queued | building | completed,状态一直保留到下一次构建开始。返回值为 JSON 字符串:
idle:尚无任何构建运行。queued/building:进行中;building状态下会附带实时的elapsedMs(在读取时基于buildStartedAt重新计算,让轮询能看到实时进度)。completed:返回完整的BuildReportResult。
BuildReportResult 字段
当 status 为 completed 时返回的结构(模型定义见 BuildModels.cs):
| 字段 | 说明 |
|---|---|
status |
恒为 completed |
buildId |
触发时 build 调用返回的 Id |
result |
Succeeded | Failed | Cancelled | Unknown |
platform |
报告对应的构建目标 |
outputPath |
最终输出位置 |
totalSizeBytes |
构建总大小(字节) |
buildTimeMs |
构建总耗时(毫秒) |
buildStartedAt / buildEndedAt |
ISO-8601 时间戳(未设置时省略) |
totalWarnings / totalErrors |
报告摘要中的错误/警告聚合计数 |
files |
输出文件列表(path、role、sizeBytes),仅构建成功时出现 |
packedAssets |
打包资源明细(按 Bundle 拆分),仅成功且启用 DetailedBuildReport 时出现 |
buildSteps |
各构建步骤的 name、durationMs、depth、messages |
errors / warnings |
构建问题列表,每条含 message 与尽力解析出的源文件 file |
其中 files 来自 BuildReport.GetFiles(),每条记录的 role 字段保持原样,例如 MainData、AssetBundle、BootConfig;packedAssets 每条包含 bundlePath、overheadBytes 以及 contents(每项含 assetPath、type、guid、sizeBytes)。构建步骤的 messages 中的日志类型会被映射为 Log / Warning / Error,其中 Error/Assert/Exception 归入 errors,Warning 归入 warnings;错误/警告还会通过 BuildMessage.Parse 解析 File.cs(line,col): ... 前缀来提取源文件位置(正则见 BuildModels.cs)。
从源码可以推断,状态文件位于
Temp/pipeline_build_status.json。构建进行中时,build_status在读取时动态重算elapsedMs;报告写入后,即使构建触发了域重载,文件依然存在,因此"最近一次报告保留到下一次构建"这一特性得以成立。
switch_build_target 与 switch_build_target_status:切换构建目标
switch_build_target 切换活动构建目标。这是破坏性且长耗时的操作——会触发完整资源重导入(reimport)和域重载,在大项目上可能耗时数分钟。因此同样采用触发—轮询模式,且必须 confirm=true(该操作不属于 Unity 的 Undo)。
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
target |
是 | – |
要切换到的 BuildTarget 名称(必须已安装,可先查 list_build_targets) |
confirm |
否 | false |
应用切换;不传则调用被拒绝 |
返回 object(switching / busy / completed / error)。几个值得注意的边界行为:
- 若目标已就是当前目标,直接返回
{ status = "completed", success = true, activeBuildTarget = ... },无需排队。 - 校验失败(未知目标、未安装)返回
error;已有切换在排队/进行中返回busy。 - 未传
confirm返回error并提示需要confirm=true。
切换动作在编辑器 tick 中调用 EditorUserBuildSettings.SwitchActiveBuildTarget(group, target)(Unity 6 中该 API 从 BuildPipeline 移到了 EditorUserBuildSettings,见 SwitchBuildTargetCommand.cs 的注释)。switch_build_target_status 无参数,返回 idle / switching / completed(成功时带 success 与 activeBuildTarget,失败时带 errors)。
域重载恢复机制:状态文件 Temp/pipeline_switch_target_status.json 会在切换触发的域重载中幸存。类构造函数中的 RecoverInterruptedOperation 在下次加载时核对遗留的 switching 记录与当前活动目标:若两者一致,判定切换成功;否则判定切换未生效。这样即使切换过程中进程经历了域重载,客户端最终仍能通过轮询得到确定性的 completed 结果。
构建配置命令:枚举目标、读写设置、列出 Build Profile
这一组命令用于"读取/检查构建配置",全部要求 MainThreadRequired = true,且不触发任何实际构建或切换。
list_build_targets:枚举已知构建目标
无参数,返回按 targetGroup 分组、再按名称排序的 BuildTargetInfo 列表,每项包含:
| 字段 | 说明 |
|---|---|
name |
BuildTarget 枚举名,如 StandaloneWindows64 |
displayName |
友好标签,如 Windows 64-bit |
targetGroup |
BuildTargetGroup 枚举名,如 Standalone |
isInstalled |
该平台的构建支持是否已安装(即 BuildPipeline.IsBuildTargetSupported) |
从源码看,实现会遍历 BuildTarget 枚举值,过滤掉非正数哨兵(NoTarget 等)、重复项与标记 <a href="https://link.gitcode.com/i/cc48340e4a63d956e9c4ebff868c8c4f" target="_blank">Obsolete] 的废弃值([BuildConfigCommands.cs)。displayName 对常见目标(Windows/macOS/Linux/Android/iOS/WebGL/UWP/PS4/PS5/XboxOne/Switch)有友好映射,其余回退为枚举名。这正是选择 build / switch_build_target 目标前的"标准查询手段"。
get_build_settings:读取当前构建配置
无参数,返回 BuildSettingsResult,反映 EditorUserBuildSettings / EditorBuildSettings 的当前值:
| 字段 | 说明 |
|---|---|
activeBuildTarget |
当前活动 BuildTarget 名 |
activeBuildTargetGroup |
当前活动 BuildTargetGroup 名 |
developmentBuild |
是否配置了 Development Player |
allowDebugging |
是否允许脚本调试 |
connectWithProfiler |
Profiler 是否自动连接 |
buildScriptsOnly |
是否只构建脚本(跳过数据) |
symlinkSources |
运行时/插件源是否软链接 |
il2CppCodeGeneration |
活动目标的 IL2CPP 代码生成模式:OptimizeSpeed | OptimizeSize |
scenes |
Build Settings 场景列表(每项含 path、guid、enabled) |
set_build_settings:改写可变构建配置字段
设置 EditorUserBuildSettings 的可变字段。注意职责边界:它不管理场景列表(场景增删用 add_scene_to_build / remove_scene_from_build,见 scenes.md),也不切换目标(用 switch_build_target)。支持 dry_run 预览。
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
settings |
否 | – |
要修改的字段;未提供的字段保持原样 |
confirm |
否 | false |
应用更改;不传则被拒绝 |
dry_run |
否 | false |
预览变更而不应用 |
settings 是结构化输入 DTO(实现了 IStructuredCommandInput,客户端以嵌套 JSON 对象形式传递),每个字段均可选,只改变显式提供的字段:
| 字段 | 说明 |
|---|---|
developmentBuild |
构建 Development Player(启用调试器/Profiler) |
allowDebugging |
允许脚本调试(仅在 developmentBuild=true 时生效) |
connectWithProfiler |
自动连接 Profiler(仅在 developmentBuild=true 时生效) |
buildScriptsOnly |
只构建脚本(跳过数据),加快迭代 |
symlinkSources |
软链接运行时/插件源而非复制(平台支持时) |
il2CppCodeGeneration |
活动目标的 IL2CPP 代码生成:OptimizeSpeed | OptimizeSize |
返回 SetBuildSettingsResult,包含 success、dryRun、applied(实际变更的字段映射)、skipped(提供的但值已一致的字段映射,视为无操作)与 message。未提供 settings 对象时直接失败;未 confirm 且非 dry run 时被拒绝。从实现看,每个字段通过 Plan 帮助方法比较请求值与当前值:不同才写入(记录到 applied),相同则记录到 skipped;il2CppCodeGeneration 通过 PlayerSettings.SetIl2CppCodeGeneration(NamedBuildTarget.FromBuildTargetGroup(group), ...) 写入并同样区分 applied/skipped。
list_build_profiles:列出 Build Profile 资产(Unity 6)
无参数,返回 BuildProfileInfo 列表(name、guid、platform、isActive);在 Unity 6 之前的编辑器上返回 { error, code = "feature_unavailable" }。实现通过 BuildProfiles 反射 shim(BuildConfigCommands.cs)访问 Unity 6 的 UnityEditor.Build.Profile.BuildProfile 类型,使程序集在旧版本编辑器上也能编译运行;用 AssetDatabase.FindAssets("t:BuildProfile") 扫描资产。该 shim 同时服务于 build 命令的 profileName 激活——激活失败只会告警,绝不导致构建失败。
recompile 与 recompile_status:强制脚本重编译
recompile 强制一次脚本重编译,在编辑器未聚焦/最小化时也能工作。无参数(源码中还有一个默认 false 的可选 focus 参数,为 true 时先把编辑器带到前台)。返回 object:
- 编译确实开始 →
{ status = "compiling", ... },随后轮询recompile_status。 - 无脚本需要重编译 →
{ status = "up_to_date", ... }。
recompile_status 无参数,返回 idle | triggered | compiling | completed | up_to_date。
源码揭示了两个关键实现细节(RecompileCommand.cs):
- 后台编译与前台聚焦:Unity 只在编辑器是活动 OS 应用时才执行脚本编译。服务器在未聚焦时仍让编辑器持续 tick,因此默认不抢占用户前台窗口也能完成编译;
focus=true才调用FocusEditorCommand.FocusEditor()抢占前台。 - 域重载下的完成通知:成功的编译必然触发域重载,这会销毁托管 AppDomain(HTTP 服务器、在途请求、静态字段全部重建),触发请求无法保持打开。因此状态通过
Temp/pipeline_recompile_status.json文件传递——CompilationPipeline.compilationStarted/assemblyCompilationFinished/compilationFinished三个回调分别写入compiling、累积错误、写入最终completed(含failed标志与错误数组)。compilationFinished在域重载之前写入,故轮询者在重载后仍能读到结果。客户端必须容忍域重载期间的连接错误。
测试命令:列出、运行、轮询与取消
list_tests:枚举可用测试(不执行)
列出 EditMode 和/或 PlayMode 下所有可用测试,不运行它们。
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
mode |
否 | all |
测试模式:all、editor、playmode |
返回 TestListResponse:success、command、mode(EditMode / PlayMode / All)、count、tests(每项含 fullName、mode、assembly、categories、explicit)、message、executedAt。实现通过 TestRunnerApi.RetrieveTestList 枚举测试树并只收集叶子测试(真实测试方法,而非套件/fixture),详见 TestCommands.cs。
run_tests:执行 Unity 测试
带过滤选项执行测试。默认同步(阻塞至完成),async_tests=true 时立即返回并轮询 test_status。
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
mode |
否 | all |
测试模式:all、editor、playmode |
filter |
否 | – |
测试名过滤模式(不区分大小写的部分匹配) |
filter_type |
否 | testName |
过滤类型:testName、assembly、category |
include_explicit |
否 | false |
包含标记了 [Explicit] 特性的测试 |
async_tests |
否 | false |
异步运行——立即返回,轮询 test_status 获取结果 |
timeout |
否 | 300 |
测试执行超时(秒),默认 300 |
返回 TestExecutionResponse。特别提醒:PlayMode 测试无法通过 HTTP 同步运行——进入播放模式会触发域重载从而丢弃在途请求,所以同步调用直接返回错误并引导改用 --mode playmode --async_tests 异步模式(PipelineTestRunner.cs)。mode=all 时,EditMode 部分同步执行并内联返回结果,PlayMode 部分转为异步启动并在响应中给出 StatusPath,最终结果仍通过 test_status 轮询。
test_status 与 cancel_tests
test_status:无参数,返回异步测试执行的状态(JSON 字符串);无运行中测试时返回{"status":"no_tests",...}。MainThreadRequired = false。cancel_tests:无参数,取消正在运行的测试执行,返回object。取消 PlayMode 测试且编辑器处于播放模式时,会调用EditorApplication.ExitPlaymode()退出播放模式。
测试引擎的健壮性设计(值得在自动化流水线中留意)从源码可见:异步模式把请求持久化到 Temp/pipeline_test_request.json(域重载幸存),完成结果写入 Temp/pipeline_test_status.json;[InitializeOnLoad] 的 TestReloader 在域重载后通过 CheckForPendingTests 检测在途请求,只重新挂接结果收集器(ReattachResultCollector)而非重新启动测试——因为 Unity Test Framework 的 TestJobDataHolder 会自动恢复播放模式域重载前的运行,若再次 api.Execute 会双重执行任务列表并触发"too many instant steps"保护。异步运行结束后还会执行 RestoreLiveServerIfDisrupted 自愈检查:若测试运行破坏了 live server(监听器死亡或描述符被清掉),则重启服务器,保证后续命令可用。
典型自动化工作流
把这组命令串起来,可以构成一条完整的无头构建 + 验证流水线(以 unity CLI 为例,具体调用语法见 connectivity.md):
# 1. 枚举目标,确认构建支持已安装
unity command list_build_targets
# 2. 读取当前构建配置
unity command get_build_settings
# 3. 需要时切换目标(破坏性,必须 confirm)
unity command switch_build_target --target StandaloneWindows64 --confirm true
# 轮询直到完成:
unity command switch_build_target_status
# 4. 按需调整配置(dry_run 预览,confirm 应用)
unity command set_build_settings --settings '{"developmentBuild":true}' --confirm true
# 5. 触发异步构建(validate 先行:dry_run 校验参数)
unity command build --target StandaloneWindows64 --confirm true
# 轮询直到 status == "completed",随后解析 BuildReportResult
unity command build_status
# 6. 强制重编译并轮询
unity command recompile
unity command recompile_status
# 7. 运行测试(异步模式),轮询结果
unity command run_tests --mode editor --filter "MySuite" --async_tests true
unity command test_status
整个过程中遵循的原则:任何变更先 dry_run 预览 → confirm 应用 → 轮询 *_status 收敛;build_status 返回的 result(Succeeded/Failed/Cancelled)与 errors/warnings 列表可直接作为 CI 判定依据;域重载(切换目标、重编译成功、PlayMode 测试)期间客户端需容忍瞬时连接错误并继续轮询。
延伸阅读
- creating-commands.md——
[CliCommand]/[CliArg]命令编写 API、MainThreadRequired/RuntimeOnly标志与响应封装模式 - connectivity.md——服务器回环绑定、端口区间、端口描述文件与 bearer token 鉴权
- safety-and-mutations.md——
confirm/dry_run门禁与 Undo 分组的统一约定 - index.md——全部命令索引与文档导航
- 实现源码:BuildCommand.cs、SwitchBuildTargetCommand.cs、BuildConfigCommands.cs、BuildModels.cs、RecompileCommand.cs、TestCommands.cs、PipelineTestRunner.cs
- 测试佐证:BuildConfigCommandsTests.cs——验证命令注册发现、
switch_build_target的 target/confirm 必填门禁、list_build_targets包含已安装的活动目标、get_build_settings报告目标与场景、set_build_settingsdry run 只报告计划不变更