Unreal Engine 跨平台构建完全指南

目录

1. 概述
2. 跨平台构建支持矩阵
3. Windows 平台打包指南
4. macOS 平台打包指南
5. Linux 平台打包指南
6. 最佳实践与建议
7. 常见问题与解决方案
8. 参考资源

---

概述

Unreal Engine 提供了强大的跨平台开发能力，允许开发者在一个平台上开发并打包到多个目标平台。本指南将详细介绍如何在不同开发平台上打包到各个目标平台，包括所需工具、配置步骤和注意事项。

什么是跨平台构建？

跨平台构建（Cross-compilation）是指在一个操作系统平台上编译和打包针对另一个操作系统平台的应用程序。这种能力极大地提高了开发效率，允许团队使用统一的开发环境输出多平台版本。

---

跨平台构建支持矩阵

下表展示了不同开发平台对目标平台的支持情况：

开发平台	目标：Windows	目标：macOS	目标：Linux
Windows	✅ 原生支持	⚠️ 可行但有限制	✅ 需要工具链
macOS	✅ 良好支持	✅ 原生支持	⚠️ 需要配置
Linux	⚠️ 困难	❌ 几乎不可行	✅ 原生支持

图例说明：

• ✅ 良好支持，推荐使用
• ⚠️ 技术上可行，但有限制或配置复杂
• ❌ 不推荐或不可行

---

Windows 平台打包指南

1. Windows → Windows（原生打包）

这是最简单直接的打包方式，无需额外配置。

操作步骤：

1. 打开 Unreal Engine 项目
2. 点击菜单栏：File → Package Project → Windows → Windows (64-bit)
3. 选择输出目录
4. 等待打包完成

项目设置（可选）：

• Edit → Project Settings → Platforms → Windows
• 配置最低和目标 Windows 版本
• 设置图标、启动画面等

📖 官方文档： Packaging Your Project

---

2. Windows → macOS（跨平台打包）

在 Windows 上打包 macOS 应用需要安装额外的工具链。

前置要求：

• Unreal Engine 4.14 或更高版本
• 足够的磁盘空间（工具链约 2-3 GB）

安装步骤：

方式一：通过 Epic Games Launcher

1. 打开 Epic Games Launcher
2. 导航到 Library → Engine Versions
3. 点击引擎版本旁的下拉菜单 → Options
4. 勾选 Mac Support 或 iOS Support（包含 Mac 工具链）
5. 点击 Apply 等待下载安装

方式二：手动下载

1. 访问 Unreal Engine Cross-Compile Toolchain 页面
2. 下载对应引擎版本的 macOS 工具链
3. 解压到引擎安装目录

打包步骤：

1. File → Package Project → Mac
2. 选择输出目录
3. 等待打包完成

⚠️ 重要限制：

无法进行代码签名和公证

• Windows 打包的 macOS 应用无法进行代码签名（Code Signing）
• 无法完成苹果公证（Notarization）流程
• 应用可能无法在现代 macOS 系统上正常运行（会被 Gatekeeper 拦截）

解决方案：

• 最终发布前必须在真实 Mac 上进行签名和公证
• 或使用云端 Mac 服务（如 MacStadium、AWS Mac instances）

📖 参考资料：

• Code signing and notarization for Mac
• Automating macOS Notarization for UE4

---

3. Windows → Linux（跨平台打包）

Windows 对 Linux 的交叉编译支持较为成熟。

安装 Linux 工具链：

步骤：

1. 访问官方工具链下载页面

2. 根据你的 Unreal Engine 版本选择对应的工具链：

   • UE 5.0-5.3: v20 (clang 13.0.1)
   • UE 5.4+: v22 或更高版本
   • UE 5.6: v25 工具链

3. 下载后解压到以下目录之一：

   • C:\UnrealToolchains\ （推荐）
   • 或引擎根目录下

4. 重启 Unreal Editor

验证安装：

打开项目后，检查 Edit → Project Settings → Platforms 是否显示 Linux 选项。

打包步骤：

1. File → Package Project → Linux → Linux
2. 选择输出目录
3. 等待打包完成

工具链版本对应表：

Unreal Engine 版本	推荐工具链版本	Clang 版本
5.0 - 5.3	v20	13.0.1
5.4 - 5.5	v22	15.0.1
5.6+	v25	17.0.6

⚠️ 注意： 工具链版本不匹配可能导致编译错误。

📖 官方文档：

• Cross-Compiling for Linux
• Building an Unreal Project for Linux on Windows

---

macOS 平台打包指南

1. macOS → macOS（原生打包）

这是 Mac 开发者的标准流程，支持完整的代码签名和公证。

操作步骤：

1. File → Package Project → Mac
2. 选择输出目录
3. 等待打包完成

代码签名和公证：

前置要求：

• Apple Developer 账号
• 有效的 Developer ID 证书
• 配置好的 Provisioning Profile

签名步骤：

# 1. 签名应用
codesign --force --deep --sign "Developer ID Application: Your Name" YourApp.app# 2. 创建 DMG（可选）
hdiutil create -volname "YourApp" -srcfolder YourApp.app -ov -format UDZO YourApp.dmg# 3. 提交公证
xcrun notarytool submit YourApp.dmg --apple-id "[e-mail]" --team-id "TEAM_ID" --password "app-specific-password" --wait# 4. 装订公证票据
xcrun stapler staple YourApp.app

📖 深度指南： Fixing code signing and notarization issues

---

2. macOS → Windows（跨平台打包）

Mac 打包 Windows 应用是官方良好支持的功能，无需额外工具链。

操作步骤：

1. File → Package Project → Windows → Windows (64-bit)
2. 选择输出目录
3. 等待打包完成

项目设置：

• Edit → Project Settings → Platforms → Windows
• 配置 Windows 特定设置（图标、版本号等）

✅ 优势：

• 无需额外配置，开箱即用
• 稳定性高，Epic 官方充分测试
• 支持所有 Windows 特性

⚠️ 注意事项：

• 务必在真实 Windows 设备上测试
• 检查 DirectX 相关功能
• 验证文件路径（Windows 使用反斜杠 \）

---

3. macOS → Linux（跨平台打包）

Mac 打包 Linux 需要手动配置工具链。

安装步骤：

1. 下载 Linux 工具链

   • 访问 Epic 官方下载页面
   • 选择对应 UE 版本的工具链

2. 安装工具链

   # 解压到用户目录
   cd ~/
   tar -xvf v20_clang-13.0.1-centos7.tar.gz# 或移动到标准位置
   sudo mv v20_clang-13.0.1-centos7 /opt/UnrealToolchains/
   

3. 配置环境变量（如需要）
   编辑 ~/.bash_profile 或 ~/.zshrc：

   export LINUX_MULTIARCH_ROOT=$HOME/UnrealToolchains/v20_clang-13.0.1-centos7
   

4. 重启 Unreal Editor

打包步骤：

1. File → Package Project → Linux
2. 选择输出目录
3. 等待打包完成

⚠️ 注意： Mac 对 Linux 的交叉编译支持不如 Windows，可能遇到更多兼容性问题。

---

Linux 平台打包指南

1. Linux → Linux（原生打包）

这是 Linux 开发者的标准流程。

前置要求：

• 已安装 Unreal Engine（源码编译或官方二进制）
• 必要的开发库（build-essential, clang 等）

操作步骤：

1. File → Package Project → Linux
2. 选择输出目录
3. 等待打包完成

---

2. Linux → Windows（不推荐）

虽然理论上可行，但实际操作极其复杂且不稳定。

为什么不推荐？

• Epic 官方不提供工具链支持
• 需要手动配置 MinGW-w64 或类似工具
• 兼容性问题多，调试困难
• 社区支持和文档极少

替代方案：

1. 使用虚拟机

   • 在 Linux 上运行 Windows 虚拟机
   • 使用 QEMU/KVM 或 VirtualBox

2. 使用 Wine

   • 运行 Windows 版 Unreal Editor
   • 不推荐用于生产环境

3. CI/CD 方案

   • 使用云服务的 Windows 构建节点
   • GitHub Actions、GitLab CI 等

---

3. Linux → macOS（几乎不可行）

这是最困难的组合，强烈不推荐。

技术障碍：

• 法律限制：Apple 许可协议禁止在非 Mac 硬件上使用 macOS SDK
• 工具链缺失：没有官方 Xcode for Linux
• 无法签名：即使能编译，也无法进行代码签名和公证

为什么不可行？

1. Xcode 和 macOS SDK 仅限 macOS

   • 苹果严格限制其开发工具的使用
   • 违反许可协议可能面临法律风险

2. 代码签名必需

   • 现代 macOS 要求所有应用签名和公证
   • 这些步骤只能在真实 Mac 上完成

唯一合法方案：

• 使用云端 Mac 服务（MacStadium、AWS Mac instances）
• 租用或购买物理 Mac 设备

---

最佳实践与建议

1. 为不同平台优化项目设置

Windows 特定设置：

Project Settings → Platforms → Windows
- Minimum OS Version: Windows 10
- Target RHI: DirectX 12
- Icon: 设置 .ico 文件

macOS 特定设置：

Project Settings → Platforms → Mac
- Minimum OS Version: macOS 12.0 (Monterey)
- Bundle Identifier: com.yourcompany.yourgame
- Category: 选择合适的应用类别

Linux 特定设置：

Project Settings → Platforms → Linux
- Target Architecture: x86_64-unknown-linux-gnu

---

2. 使用 CI/CD 实现自动化构建

推荐的自动化方案：

GitHub Actions 示例：

name: Multi-Platform Buildon:push:branches: [ main ]jobs:build-windows:runs-on: windows-lateststeps:- uses: actions/checkout@v3- name: Build Windowsrun: |# 构建 Windows 版本的命令build-mac:runs-on: macos-lateststeps:- uses: actions/checkout@v3- name: Build macOSrun: |# 构建 macOS 版本的命令build-linux:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Build Linuxrun: |# 构建 Linux 版本的命令

构建服务器方案：

• Jenkins: 私有部署，完全控制
• TeamCity: JetBrains 出品，对 Unreal 友好
• BuildBot: 开源、灵活、可定制

---

3. 多平台代码最佳实践

使用平台宏进行条件编译：

#if PLATFORM_WINDOWS// Windows 特定代码#include "Windows/WindowsPlatformProcess.h"
#elif PLATFORM_MAC// macOS 特定代码#include "Mac/MacPlatformProcess.h"
#elif PLATFORM_LINUX// Linux 特定代码#include "Linux/LinuxPlatformProcess.h"
#endif

文件路径处理：

// ❌ 错误：硬编码路径
FString Path = "C:\\MyGame\\Data\\config.ini";// ✅ 正确：使用 Unreal 的路径 API
FString Path = FPaths::ProjectConfigDir() / TEXT("config.ini");

避免平台特定 API：

// ❌ 错误：使用 Windows API
#include <Windows.h>
Sleep(1000);// ✅ 正确：使用 Unreal 的跨平台 API
#include "HAL/PlatformProcess.h"
FPlatformProcess::Sleep(1.0f);

---

4. 测试策略

必须在目标平台上测试：

即使使用交叉编译，也必须在真实设备上进行测试：

测试项目	Windows	macOS	Linux
基础功能	✅	✅	✅
输入设备	✅	✅	✅
图形渲染	✅	✅	✅
音频系统	✅	✅	✅
网络功能	✅	✅	✅
文件 I/O	✅	✅	✅
性能测试	✅	✅	✅

使用虚拟机进行初步测试：

• Windows: Parallels (Mac), QEMU/KVM (Linux)
• macOS: 无合法虚拟化方案（除非在 Mac 硬件上）
• Linux: VirtualBox, VMware, Hyper-V

---

5. 版本控制最佳实践

.gitignore 配置：

# Unreal Engine
Binaries/
Build/
DerivedDataCache/
Intermediate/
Saved/# 平台特定
*.sln
*.suo
*.xcworkspace
*.xcodeproj# 打包输出
Packaged/
Dist/

分支策略：

main              # 稳定版本
├── develop       # 开发分支
├── feature/*     # 功能分支
└── platform/*    # 平台特定修复├── platform/windows├── platform/mac└── platform/linux

---

常见问题与解决方案

问题 1: Windows → Linux 工具链版本不匹配

症状：

ERROR: Unable to find clang in toolchain
ERROR: Linux toolchain not found

解决方案：

1. 确认 Unreal Engine 版本
2. 下载对应的工具链版本（见工具链对应表）
3. 重新安装并重启编辑器

---

问题 2: macOS 代码签名失败

症状：

"YourApp.app" is damaged and can't be opened

解决方案：

1. 检查证书是否过期
2. 确保使用正确的签名命令：

   codesign --deep --force --verify --verbose --sign "Developer ID" YourApp.app
   

3. 完成公证流程
4. 使用 stapler 装订票据

📖 详细指南： Fixing code signing issues

---

问题 3: Linux 缺少依赖库

症状：

error while loading shared libraries: libXXX.so: cannot open shared object file

解决方案（Ubuntu/Debian）：

sudo apt-get update
sudo apt-get install -y \libxcb-xinerama0 \libxcb-cursor0 \libvulkan1 \libopenal1

---

问题 4: 跨平台打包后插件缺失

症状：
打包后应用无法启动，提示缺少插件。

解决方案：

1. 检查 .uproject 文件中的插件配置：

   "Plugins": [{"Name": "YourPlugin","Enabled": true,"SupportedTargetPlatforms": ["Win64","Mac","Linux"]}
   ]
   

2. 确保插件支持目标平台
3. 重新打包

---

问题 5: C++ 项目跨平台编译错误

症状：

error: use of undeclared identifier 'HWND'
error: unknown type name 'NSWindow'

解决方案：
使用平台宏隔离代码：

#if PLATFORM_WINDOWSHWND WindowHandle;
#elif PLATFORM_MACNSWindow* WindowHandle;
#elif PLATFORM_LINUX// Linux 实现
#endif

---

参考资源

官方文档

• Unreal Engine 多平台游戏开发
• 项目打包指南
• Linux 交叉编译
• iOS/macOS 签名和配置

社区资源

• Building an Unreal Project for Linux on Windows
• Fixing macOS code signing issues
• Automating macOS Notarization
• Unreal Engine Forums - Platform & Builds

工具和服务

云端构建服务：

• MacStadium - 云端 Mac 租用
• AWS EC2 Mac instances - Amazon 的 Mac 云服务
• GitHub Actions - 免费的 CI/CD 服务
• GitLab CI - 开源 CI/CD 平台

开发工具：

• Visual Studio - Windows 开发
• Xcode - macOS/iOS 开发
• CLion - 跨平台 C++ IDE

---

总结

Unreal Engine 的跨平台构建能力让开发者可以高效地为多个平台发布应用。主要要点：

1. Windows 和 macOS 互相打包支持最好，是最常用的跨平台组合
2. Linux 打包需要额外工具链，但 Windows 和 Mac 都能很好支持
3. macOS 必须在 Mac 上签名，这是发布的必要步骤
4. Linux 打包其他平台不推荐，应使用 CI/CD 或虚拟机方案
5. 始终在目标平台上测试，交叉编译不能替代真实设备测试

合理利用交叉编译和 CI/CD 自动化，可以极大提高多平台开发效率。

---

最后更新： 2025年10月
适用于： Unreal Engine 4.27 - 5.6+