BuildCookRun 参数全详解

November 17, 2024About 9 min

BuildCookRun 参数全详解

BuildCookRun 是 UAT(Unreal Automation Tool)里最常用的命令,一条命令把 Build / Cook / Stage / Package / Deploy / Run 这几步串起来。编辑器里的 "Package Project"、Project Launcher、UnrealFrontend 打包,底层走的都是它。

跑命令的入口:

Engine\Build\BatchFiles\RunUAT.bat BuildCookRun -Help

-Help 输出里参数没有排序,而且部分参数(比如 -numclients)早就废弃了什么都不做,加上 BuildCookRun 是从其它 UAT 命令继承来的,help 开头还会刷一堆 Duplicated help parameter 警告。所以下面我把参数按用途分组整理,常用的几个单独拎出来说。

帮助里对命令本身的描述:

Builds/Cooks/Runs a project. 对非 uproject 工程,target 通过编译工程目录下的 target rule 文件来发现。如果没指定 -map,命令会去工程的 DefaultEngine.ini 找 DefaultMap,找不到再去 BaseEngine.ini,再找不到就回退到 /Engine/Maps/Entry。

最该先记住的几个参数

平时手写打包命令,真正天天用到的就这几个:

参数	作用
`-project=Path`	工程路径(必填),如 `-project=D:\Projects\MyProject.uproject`
`-platform=PlatformName`	目标平台,Windows 一般填 `Win64`(等价 `-targetplatform`)
`-clientconfig=` / `-configuration=`	构建配置:Development / Test / Shipping(源码版还有 Debug)
`-build`	执行编译步骤(C++ 工程需要,蓝图工程可省)
`-cook`	Cook 内容。去掉 uasset 里只有编辑器才需要的数据,顺带编译过期 shader
`-stage`	把 Cook 后的内容拷到 staging 目录,加上可执行文件、可选的 Prereq 安装器
`-pak`	把 Cook 后的内容塞进 `.pak`,可压缩、可加密
`-archive` + `-archivedirectory=Path`	把 staging 结果再拷一份到指定归档目录
`-clean`	编译前清掉中间文件 + 上一次 Cook/Stage 结果

调试时的一个小技巧:临时去掉 -pak,Stage 出来的资源会以"散文件"形式按 Content 目录结构铺开,方便你确认哪些资源被 Cook/Stage 了、哪些漏了。

一条典型的 Win64 打包命令长这样:

RunUAT.bat BuildCookRun -project="D:\Projects\MyProject.uproject" -platform=Win64 -clientconfig=Development -cook -build -stage -pak -archive -archivedirectory="D:\Archive"

关于 Cook 什么:编辑器菜单的 "Package Project" 会把工程里所有内容都 Cook 进去,不管用没用到,包会变得很大。用 -map= 指定要 Cook 的关卡,Cooker 会从关卡引用的资源开始一路"spider out",只 Cook 真正被引用到的东西。代价是运行时动态加载、没有硬引用的资源(比如换肤用的 skin)不会被 Cook——这种要在 DefaultGame.ini 的 [/Script/UnrealEd.ProjectPackagingSettings] 里用 +DirectoriesToAlwaysCook= 把目录加进强制 Cook 列表。

工程与平台

参数	说明
`-project=Path`	工程路径(必填),`-project=QAGame` / `-project=Samples\BlackJack\BlackJack.uproject` / 绝对路径均可
`-destsample`	目标 Sample 名
`-foreigndest`	Foreign 目标路径
`-targetplatform=PlatformName`	Build/Cook/Deploy 的目标平台(也写作 `-Platform`)
`-servertargetplatform=PlatformName`	专用服务器的目标平台(也写作 `-ServerPlatform`)
`-foreign`	从 blankproject 生成一个 foreign uproject 并使用它
`-foreigncode`	从 platformergame 生成一个 foreign code uproject 并使用它
`-CrashReporter`	是否一并编译 CrashReporter
`-SpecifiedArchitecture`	指定一个最低 OS / 架构
`-Licensee`	标记此构建由 licensee 编译

编译(Build)

参数	说明
`-build`	执行编译步骤
`-noxge`	不使用 XGE 做分布式编译
`-ForceMonolithic`	把结果合并成单个可执行文件
`-ForceDebugInfo`	即使 Development 也强制生成 debug info
`-ForceNonUnity`	关闭 unity build
`-ForceUnity`	强制开启 unity build
`-nodebuginfo`	不把 debug 文件拷到 stage
`-separatedebuginfo`	debug info 输出到单独目录
`-MapFile`	生成 `*.map` 文件
`-UbtArgs`	透传给 UBT 的额外参数
`-NoSign`	跳过 code/content 文件签名

Cook

参数	说明
`-cook` / `-cookonthefly`	决定构建是否使用 cooked 数据;`-cookonthefly` 让客户端用 cook-on-the-fly 服务器提供的数据运行
`-skipcook`	用 cooked 构建,但假设 cooked 数据已最新且就位(隐含 `-cook`)
`-skipcookonthefly`	cookonthefly 构建里,仅用于把信息传给 package 步骤
`-Cookontheflystreaming`	流式 cook-on-the-fly,不本地缓存,每次加载都从服务器重取
`-iterativecooking` / `-iterate`	增量 Cook
`-CookPartialgc`	Cook 时随用随清包,而不是空间不够时才一次性清
`-CookInEditor`	是否在编辑器里 Cook 而非 UAT 里
`-IgnoreCookErrors`	忽略 Cook 错误继续打包
`-CookMapsOnly`	只 Cook 地图(仅影响 `-cookall` 的行为)
`-CookAll`	Cook 工程 Content 目录下所有内容
`-SkipCookingEditorContent`	跳过 `/Engine/Editor` 下的内容
`-FastCook`	目标平台支持的话走 fast cook 路径
`-IgnoreVerCheck`	忽略版本检查
`-IgnoreLightMapErrors`	是否把 Light Map 错误当致命错误
`-MapsToRebuildLightMaps`	需要重建光照贴图的地图列表
`-MapsToRebuildHLODMaps`	需要重建 HLOD 的地图列表

Pak 与 IoStore

参数	说明
`-pak`	生成 pak 文件
`-iostore`	生成 I/O store 容器文件
`-skippak`	用 pak,但假设已构建好(隐含 `-pak`)
`-skipiostore`	覆盖 `-iostore`,不执行
`-prepak`	尽量不 Cook,改从网络拉 pak(隐含 `-pak` 和 `-skipcook`)
`-signpak=keys`	用指定 key 给 pak 签名,如 `-signpak=C:\Encryption.keys`(隐含 `-signedpak`)
`-signed`	游戏预期使用签名 pak
`-PakAlignForMemoryMapping`	为 bulk data 内存映射做对齐

Stage / Package / Archive / Deploy

参数	说明
`-stage`	放入 stage 目录
`-skipstage`	用 stage 目录,但假设东西都在(隐含 `-stage`)
`-nocleanstage`	不清理 stage 目录
`-stagingdirectory=Path`	构建拷贝目录,如 `-stagingdirectory=C:\Stage`
`-package`	为目标平台打包
`-skippackage`	跳过打包
`-distribution`	打发行版本
`-prereqs`	把前置依赖一起 stage
`-applocaldir`	applocal 部署的前置依赖位置
`-Prebuilt`	这是一个预构建的 cooked & packaged 版本
`-AdditionalPackageOptions`	传给平台 packager 的额外选项
`-archive`	放入 archive 目录
`-archivedirectory=Path`	归档目录,如 `-archivedirectory=C:\Archive`
`-archivemetadata`	归档时额外带上元数据文件(如 build.properties)
`-createappbundle`	Mac 归档时打成 `.app` 而不是散文件
`-manifests`	Cook 时生成 streaming install manifest
`-createchunkinstall`	从 manifest 生成 streaming install 数据(需 `-stage` & `-manifests`)
`-deploy`	部署到目标平台
`-getfile`	运行成功后从目标设备下载文件
`-bundlename`	部署到移动设备时用的 bundle 名

运行(Run)与测试

参数	说明
`-run`	构建完后运行游戏(有 `-server` 时连服务器一起)
`-fileserver`	客户端用 UnrealFileServer 提供的 cooked 数据运行
`-dedicatedserver` / `-server`	Build/Cook/Run 客户端 + 服务器
`-client`	Build/Cook/Run 客户端 + 服务器,用 client target 配置
`-noclient`	不跑客户端,只跑服务器
`-skipserver`	跳过启动服务器
`-logwindow`	给客户端开日志窗口
`-map`	运行用的地图
`-AdditionalServerMapParams`	额外的 server map 参数,如 `?param=value`
`-device` / `-serverdevice`	运行游戏 / 服务器的设备
`-numclients=n`	多开客户端,n >= 2(注:已废弃)
`-addcmdline` / `-servercmdline` / `-clientcmdline`	追加 / 覆盖命令行参数
`-nullrhi`	给客户端命令行加 `-nullrhi`
`-fakeclient`	给 server URL 加 `?fake`
`-editortest`	不跑客户端,改跑编辑器
`-RunAutomationTests`	跑 `-editortest` 或客户端时跑全部 automation test(与 `-server` 不兼容)
`-Crash=index`	按 index 注入 debug crash / rendercrash 等命令
`-deviceuser` / `-devicepass`	Linux 无人值守的用户名 / 密码
`-RunTimeoutSeconds`	启动游戏后的等待超时

其它

参数	说明
`-unattended`	假设无人值守,绝不卡住等待
`-cmdline`	写进 stage 内 `UE4CommandLine.txt` 的命令行
`-ue4exe=ExecutableName`	UE 编辑器可执行文件名,如 `-ue4exe=UE4Editor.exe`

打包时各阶段产物落在哪

把 BuildCookRun 跑通后,大致流程和落盘位置:

编译源码:Development / Test / Shipping 可执行文件落在工程 Binaries/<平台> 下(Win64 是 Binaries/Win64),之后会被拷进 staged 目录。
Cook 内容:落在工程 Saved/Cooked/<平台>。非源码版只能选 "no editor" 类型,Windows 对应 Saved/Cooked/WindowsNoEditor;源码版还能 Cook dedicated server(WindowsServer)/ dedicated client(WindowsClient)。
Stage:把 cooked 文件拷进 Saved/StagedBuilds/WindowsNoEditor,可选打进 .pak。staged 根目录会有一堆 Manifest .txt(运行不需要,可删),还有 bootstrap 可执行文件——它只是个方便的启动器,会自动装 Prereq(DirectX、C 运行库)。
Archive:-archive + -archivedirectory= 把 staged 目录整份再拷一份到你指定的位置,方便保留多个版本。

ExitCode 这个细节值得记一下:UAT 总会带一个 ExitCode 退出,0 是 Success。BuildCookRun 跑 BuildGame 时底层调 UBT,编译失败 UBT 返回非 0,UAT 也跟着返回非 0——批处理 / CI 就靠这个判断构建成败。

加速 Cook 参数(Speed Up Cook)

下面三个 -Sqex* 参数是定制引擎里加的加速 Cook 开关,核心思路都是"用稳定性换速度",适合开发期快速迭代,临近发版要谨慎。

-SqexNeverGC

在 Cook 阶段禁用垃圾回收(GC)。正常情况下 GC 自动回收不再用的内存防止泄漏,但 Cook 大量数据 / 复杂资源时,频繁 GC 会拖慢速度。关掉 GC 能加快 Cook,代价是内存占用显著上涨——内存紧张的机器上反而可能更糟,用之前先看机器内存够不够。

-SqexQuickExit

让引擎 Cook 完之后快速退出,跳过正常的清理和关闭流程(释放内存、保存状态等)。自动化 / 批处理任务里这些收尾常常没必要,省下来就是时间。风险是出错或异常终止时某些资源可能没被正确清理,常规开发测试里慎用。

-SqexSkipVerifyEDL

EDL(Editor Dependency List,编辑器依赖列表)是 UE 用来追踪资源间依赖关系的机制。Cook 时引擎默认会校验 EDL,确保该打进包的资源都正确处理了,防止运行时缺资源 / 报错——但这个校验本身耗时。-SqexSkipVerifyEDL 就是跳过这步校验,换来更快的 Cook,代价是可能漏掉关键依赖,导致运行时报错或崩溃。开发初期、快速迭代可以用;准备最终发版时建议不要用,确保依赖关系都处理到位。

Cook 命令拆解:Shader 与 Blueprint

打包里 Cook 这一步内部其实是引擎跑特定 commandlet。把它拆成单独命令手动跑,既能定位问题,也方便预热 shader / 蓝图。下面用 <workspace> 代表引擎根目录占位符。

命令

Cook Shader:

<workspace>\Engine\Binaries\Win64\UE4Editor-Cmd.exe <workspace>\Game\Game.uproject -run=CookGlobalShaders -platform=Windows -utf8output

Cook Blueprint:

<workspace>\Engine\Binaries\Win64\UE4Editor-Cmd.exe <workspace>\Game\Game.uproject -run=CompileAllBlueprints -utf8output

日志分析

Cook Shader:这条命令会编译 LogTargetPlatformManager、LogClass、LogAutomationTest、LogInit、LogShaderCompilers。在 MyProject 工程里平均耗时约 1~5 分钟。

Cook Blueprint:内容会包含 Shader 那部分,外加 LogCompileAllBlueprintsCommandlet、LogBlueprint、LogAudioDerivedData、LogSkeletalMesh,而且会编译那些 Cook 里实际不用的资源。MyProject 工程里平均耗时约 30~50 分钟,明显比 Shader 慢很多。

CompileAllBlueprints 是怎么找出来的

-run=CompileAllBlueprints 这个名字不是凭空来的,可以从引擎源码里反推:

全局搜 commandlet,定位到 Engine\Source\Editor\UnrealEd\Private\Commandlets\CookCommandlet.cpp。
顺着里面的定义,找到 Engine\Source\Editor\UnrealEd\Private\Commandlets\CompileAllBlueprintsCommandlet.cpp。
该 cpp 里的 commandlet 定义,对应的 -run 名就是 CompileAllBlueprints。

记住这个套路:任何 -run=XXX commandlet,都能在 UnrealEd/Private/Commandlets/ 下找到对应的 *Commandlet.cpp 确认它干了什么。