返回技能市场
开发运维 安全

unreal-packaging

@admin/unreal-packaging

打包和发布 Unreal Engine 5 项目，配置构建模式、内容烘焙、默认地图及命令行自动构建。

admin 热度 287v0.0.1

Unreal 打包与烹饪

将 UE5 项目转换为可运行、可分发的构建：选择正确的构建配置、烹饪内容、设置启动地图，并从编辑器或命令行进行打包。目标为 UE 5.8。

何时使用

  • 在产出构建（测试或发布）、选择 Development 与 Shipping、烹饪内容、配置 Packaging / Maps & Modes 设置，或使用 RunUAT BuildCookRun 为 CI 自动化构建时使用。
  • 当项目包含 *.uproject 和 Config/Default*.ini，且目标是打包后的玩家（而非在编辑器内运行）时使用。

**何时*不*使用：** 商店提交/发布流程 → steam-publish / itch-publish。编辑器内的玩法/迭代不是打包。

核心工作流

  1. 设置启动地图。 Project Settings → Maps & Modes → Game Default Map 是打包构建首先加载的内容。此处错误/为空是“打包后游戏黑屏”的最常见原因。
  2. 选择构建配置： Development（默认；已优化，但保留日志/统计/控制台用于测试）与 Shipping（全部优化，移除调试工具——用于发布）。DebugGame/Debug 用于调试引擎/游戏代码，不用于分发；DebugGame 不适用于纯 Blueprint 项目。
  3. 理解烹饪与打包的区别。 Cooking 将资源转换为目标平台格式，并打包进 .pak 文件。Packaging 将编译后的可执行文件与已烹饪内容捆绑为独立、可分发的一组文件。打包过程会包含一次烹饪。
  4. 从编辑器打包： Platforms 菜单 → 选择平台（例如 Windows）→ 设置 Binary Configuration → Package Project → 选择输出文件夹。
  5. 或从命令行构建，使用 Unreal Automation Tool（RunUAT BuildCookRun）进行可重复/CI 构建。
  6. 调整 Packaging 设置（Project Settings → Packaging）：要烹饪哪些地图/目录、完全重建、压缩，以及是否构建所有地图。
  7. 验证 时 *运行打包后的构建*，而不仅凭烹饪成功——启动可执行文件并确认它加载了正确地图且能运行。

模式

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

Platforms (toolbar)
  -> Windows
     -> Binary Configuration -> Development | Shipping
     -> Content Management -> Package Project
  -> choose/confirm the staging output folder

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

# Cook + build + stage + pak + archive a Shipping Windows build.
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. 仅烹饪（不打包），例如刷新内容

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

常见陷阱

  • 打包构建加载黑屏/空关卡 — 未设置 Game Default Map（或该地图未被烹饪）。在 Maps & Modes 中设置它，并确保它被包含在烹饪中。
  • 发行 Development 构建 — Development 保留日志/控制台/统计且更慢；应发行 Shipping。反过来，Shipping 会移除 UE_LOG/控制台，因此调试仅 Shipping 出现的问题需要 Development 或 Test。
  • 运行时引用的地图/资源缺失 — 它未被烹饪。将其添加到 Packaging 设置中要烹饪的地图/目录，或烹饪所有地图。
  • 平台构建失败 — 平台 SDK/工具链未安装（Windows build tools、Android SDK/NDK、console SDKs）。安装该平台的先决条件。
  • 期待 Blueprint Nativization — 它在 UE5 中已移除；不要依赖它提升性能。改为进行性能分析并将热点逻辑移至 C++（unreal-cpp-gameplay）。
  • 首次烹饪非常慢 — 着色器和所有资源都从头烹饪；后续烹饪是增量的。不要把缓慢的首次烹饪误认为卡死。

参考资料

  • 主要文档：“Packaging Your Project”

    • (https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project) 以及 Build Configurations / BuildCookRun 参考资料。

相关技能

  • steam-publish / itch-publish — 将打包构建分发到商店。
  • unreal-cpp-gameplay — 由于 BP nativization 已移除，将热点逻辑移至 C++。
qianwen skills install @admin/unreal-packaging