Back to Details

unreal-packaging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unreal Packaging & Cooking

Unreal打包与内容烘焙

Turn a UE5 project into a runnable, distributable build: choose the right build configuration, cook content, set the launch map, and package — from the editor or the command line. Targets UE 5.4+.
将UE5项目转换为可运行、可分发的构建版本：选择合适的构建配置，烘焙内容，设置启动地图，并通过编辑器或命令行完成打包。适用于**UE 5.4+**版本。

When to use

使用场景

  • Use when producing a build (test or release), choosing Development vs Shipping, cooking content, configuring Packaging / Maps & Modes settings, or automating builds with 
    RunUAT BuildCookRun
    for CI.
  • Use when the project has a 
    *.uproject
    and 
    Config/Default*.ini
    , and the goal is a packaged player rather than running in-editor.
When not to use: storefront submission/release process → 
steam-publish
/ 
itch-publish
. Editor-time gameplay/iteration is not packaging.
  • 适用于生成构建版本（测试版或正式版）、选择Development与Shipping配置、烘焙内容、配置打包/地图与模式设置，或使用
    RunUAT BuildCookRun
    实现CI自动化构建时。
  • 适用于项目包含
    *.uproject
    和
    Config/Default*.ini
    文件，且目标是生成可独立运行的打包版本而非在编辑器中运行的场景。
不适用于： 应用商店提交/发布流程 → 请使用
steam-publish
/ 
itch-publish
。编辑器内的游戏玩法迭代不属于打包范畴。

Core workflow

核心工作流程

  1. Set the launch map. Project Settings → Maps & Modes → Game Default Map is what a packaged build loads first. Wrong/empty here is the most common "packaged game is black" cause.
  2. Pick the build configuration: Development (default; optimized but keeps logging/ stats/console for testing) vs Shipping (all optimizations, debugging tools stripped — for release). 
    DebugGame
    /
    Debug
    are for debugging engine/game code and aren't for distribution; 
    DebugGame
    isn't available for Blueprint-only projects.
  3. Understand cook vs package. Cooking converts assets to the target platform's format and packs them into 
    .pak
    files. Packaging bundles the compiled executable + cooked content into a standalone, distributable set of files. Packaging runs a cook as part of it.
  4. Package from the editor: the Platforms menu → choose the platform (e.g. Windows) → set the Binary Configuration → Package Project → pick an output folder.
  5. Or build from the command line with the Unreal Automation Tool (
    RunUAT BuildCookRun
    ) for repeatable/CI builds.
  6. Tune Packaging settings (Project Settings → Packaging): which maps/directories to cook, full-rebuild, compression, and whether to build all maps.
  7. Verify by running the packaged build, not just by a successful cook — launch the executable and confirm it loads the right map and runs.
  1. 设置启动地图：项目设置 → Maps & Modes → Game Default Map是打包版本启动时加载的首个地图。此处设置错误或为空是“打包游戏显示黑屏”最常见的原因。
  2. 选择构建配置：Development（默认选项；已优化但保留日志/统计数据/控制台，用于测试） vs Shipping（开启所有优化，移除调试工具——用于正式发布）。
    DebugGame
    /
    Debug
    用于调试引擎/游戏代码，不适合分发；纯蓝图项目无法使用
    DebugGame
    配置。
  3. 理解烘焙与打包的区别：**烘焙（Cooking）**将资源转换为目标平台的格式并打包到
    .pak
    文件中。**打包（Packaging）**将编译后的可执行文件与烘焙后的内容捆绑为独立的可分发文件集合。打包过程会自动执行烘焙步骤。
  4. 通过编辑器打包：点击Platforms菜单 → 选择目标平台（如Windows） → 设置Binary Configuration → Package Project → 选择输出文件夹。
  5. 或通过命令行构建：使用Unreal自动化工具（
    RunUAT BuildCookRun
    ）实现可重复的/CI构建。
  6. 调整打包设置（项目设置 → Packaging）：设置需要烘焙的地图/目录、是否完全重建、压缩方式，以及是否构建所有地图。
  7. 验证打包结果：需运行打包后的版本，而非仅确认烘焙成功——启动可执行文件，确认其加载正确的地图并正常运行。

Patterns

操作模式

1. Editor packaging (the menu path)

1. 编辑器打包（菜单路径）

text
Platforms (toolbar)
  -> Windows
     -> Binary Configuration -> Development | Shipping
     -> Content Management -> Package Project
  -> choose/confirm the staging output folder
text
Platforms（工具栏）
  -> Windows
     -> Binary Configuration -> Development | Shipping
     -> Content Management -> Package Project
  -> 选择/确认临时输出文件夹

2. Command-line build with UAT (CI-friendly)

2. 使用UAT进行命令行构建（适合CI）

bash
undefined
bash
undefined

Cook + build + stage + pak + archive a Shipping Windows build.

烘焙 + 构建 + 暂存 + 打包为pak + 归档Windows平台的Shipping版本。

RunUAT BuildCookRun
-project="C:/Path/MyGame.uproject"
-noP4 -platform=Win64 -clientconfig=Shipping
-cook -allmaps -build -stage -pak -archive
-archivedirectory="C:/Builds/MyGame"

`RunUAT` lives in `Engine/Build/BatchFiles/` (`RunUAT.bat` on Windows, `RunUAT.sh` on
macOS/Linux). Drop `-allmaps` and pass `-map=Map1+Map2` to cook a subset.
RunUAT BuildCookRun
-project="C:/Path/MyGame.uproject"
-noP4 -platform=Win64 -clientconfig=Shipping
-cook -allmaps -build -stage -pak -archive
-archivedirectory="C:/Builds/MyGame"

`RunUAT`位于`Engine/Build/BatchFiles/`目录下（Windows系统为`RunUAT.bat`，macOS/Linux系统为`RunUAT.sh`）。若无需烘焙所有地图，可去掉`-allmaps`并添加`-map=Map1+Map2`指定要烘焙的地图子集。

3. Cook only (no packaging), e.g. to refresh content

3. 仅烘焙内容（不打包），例如刷新内容

bash
RunUAT BuildCookRun -project="C:/Path/MyGame.uproject" -noP4 \
  -platform=Win64 -clientconfig=Development -cook -skipstage
bash
RunUAT BuildCookRun -project="C:/Path/MyGame.uproject" -noP4 \
  -platform=Win64 -clientconfig=Development -cook -skipstage

Pitfalls

常见问题

  • Packaged build loads a black/empty level — Game Default Map isn't set (or that map wasn't cooked). Set it in Maps & Modes and ensure it's included in the cook.
  • Shipping a Development build — Development keeps logging/console/stats and is slower; ship Shipping. Conversely, Shipping strips 
    UE_LOG
    /console, so debugging a Shipping-only issue needs Development or 
    Test
    .
  • A referenced map/asset is missing at runtime — it wasn't cooked. Add it to the Packaging settings' maps/directories to cook, or cook all maps.
  • Build fails on the platform — the platform SDK/toolchain isn't installed (Windows build tools, Android SDK/NDK, console SDKs). Install the platform's prerequisites.
  • Expecting Blueprint Nativization — it was removed in UE5; don't rely on it for performance. Profile and move hot logic to C++ (
    unreal-cpp-gameplay
    ) instead.
  • First cook is very slow — shaders and all assets cook from scratch; subsequent cooks are incremental. Don't mistake a slow first cook for a hang.
  • 打包版本加载黑屏/空关卡——未设置Game Default Map（或该地图未被烘焙）。在Maps & Modes中设置正确的地图，并确保其被包含在烘焙范围内。
  • 发布Development版本——Development版本保留日志/控制台/统计数据，运行速度较慢；正式发布应使用Shipping版本。反之，Shipping版本会移除
    UE_LOG
    /控制台，因此调试仅在Shipping版本中出现的问题需使用Development或
    Test
    版本。
  • 运行时缺少引用的地图/资源——该资源未被烘焙。将其添加到打包设置的需烘焙地图/目录中，或烘焙所有地图。
  • 平台构建失败——未安装平台SDK/工具链（Windows构建工具、Android SDK/NDK、主机平台SDK）。请安装对应平台的必备组件。
  • 依赖蓝图本地化（Blueprint Nativization）——该功能已在UE5中移除；不要依赖它提升性能。应分析性能瓶颈，将热点逻辑迁移到C++（
    unreal-cpp-gameplay
    ）。
  • 首次烘焙速度极慢——着色器和所有资源需从头开始烘焙；后续烘焙为增量式。不要将首次烘焙的慢速度误认为程序挂起。

References

参考资料

  • Primary docs: "Packaging Your Project" (
    https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project
    ) and the Build Configurations / 
    BuildCookRun
    references.
  • 官方主文档：“Packaging Your Project”（
    https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project
    ）以及构建配置/
    BuildCookRun
    相关文档。

Related skills

相关技能

  • steam-publish
    / 
    itch-publish
    — distributing the packaged build to a storefront.
  • unreal-cpp-gameplay
    — moving hot logic to C++ now that BP nativization is gone.
  • steam-publish
    / 
    itch-publish
    ——将打包好的版本分发到应用商店。
  • unreal-cpp-gameplay
    ——在蓝图本地化功能移除后，将热点逻辑迁移到C++。