TEngine 集成指南:Unity Pipeline 构建 / 编译 / 测试命令全解析

原创2026-10-13 12:10:562,317 阅读
文章标签:游戏开发

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

阅读之前,先建立三个关键认知,它们贯穿全部命令:

  1. 触发—轮询(trigger-then-poll)异步模式:build、switch_build_target、recompile、run_tests(异步模式)等命令会立即返回一个瞬时状态(如 queued / switching / compiling / running),真正的耗时操作随后在编辑器的 EditorApplication.update 回调中执行。客户端必须轮询对应的 *_status 命令,直到状态变为 completed。原因很直接:BuildPipeline.BuildPlayer、SwitchActiveBuildTarget 等 API 是同步阻塞的,会长时间占用主线程,如果命令内联执行,会卡死服务器串行请求循环,调用永远无法返回。
  2. MainThreadRequired = false 的状态命令:build_status、switch_build_target_status、recompile_status、test_status 都标记为 MainThreadRequired = false,它们在后台线程直接读取 Temp 目录下的 JSON 状态文件,因此即使构建/切换正在霸占主线程,轮询依然能持续应答;状态文件还能在域重载(domain reload)后幸存,保证最后的状态可被恢复。
  3. 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 读取。典型交互流程:

  1. 不带 confirm 调用 → 返回 { status = "error", success = false, message = "Refused: ... Pass confirm=true to build, or dry_run=true to validate without building." },调用被拒绝且不入队。
  2. 带 dry_run=true → 返回 { status = "dry_run", valid, validationErrors },只校验不构建。
  3. 校验失败(如未知 target、未安装的构建支持、不存在的场景路径、无父目录的输出路径)→ 返回 { status = "error", success = false, validationErrors, message = "Build configuration is invalid; nothing was queued." },同样不入队。
  4. 带 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):

  1. 后台编译与前台聚焦:Unity 只在编辑器是活动 OS 应用时才执行脚本编译。服务器在未聚焦时仍让编辑器持续 tick,因此默认不抢占用户前台窗口也能完成编译;focus=true 才调用 FocusEditorCommand.FocusEditor() 抢占前台。
  2. 域重载下的完成通知:成功的编译必然触发域重载,这会销毁托管 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 测试)期间客户端需容忍瞬时连接错误并继续轮询。

延伸阅读

登录后查看全文
TEngine