当前位置：首页 > news >正文

【UE5】- LinuxArm64打包实战：从像素流插件依赖到预编译配置的完整排错指南

news 2026/5/26 14:59:02

1. LinuxArm64打包前的环境准备

最近在给云游戏项目做LinuxArm64平台打包时，踩了不少坑。这里分享下从像素流插件依赖到预编译配置的完整解决方案。首先得确保开发环境配置正确，否则后续所有操作都可能白费功夫。

我用的是一台搭载Arm架构CPU的物理服务器，操作系统是Ubuntu 22.04 LTS。建议至少准备16GB内存和100GB磁盘空间，因为UE5的编译过程相当吃资源。安装基础依赖项时，这几个包必不可少：

sudo apt-get install -y build-essential clang cmake python3-dev libx11-dev libgl1-mesa-dev libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev libssl-dev libsdl2-dev

特别提醒，一定要检查gcc和clang版本。我遇到过因为编译器版本不匹配导致的奇怪编译错误，最后发现是系统自带的gcc太老了。建议使用以下版本：

gcc 9.4.0或更高
clang 12或更高

安装完基础环境后，需要配置UE5源码。这里有个细节容易被忽略：必须使用-LinuxArm64后缀的构建目标。我第一次构建时直接用了默认参数，结果生成的二进制文件完全无法在Arm架构上运行。

2. 解决像素流插件平台支持问题

当尝试打包带有像素流功能的项目时，最常遇到的就是这个错误：

AVCodecsCore.uplugin is referenced via XXXX.uproject -> PixelStreaming.uplugin with a mismatched 'SupportedTargetPlatforms' field.

这个报错的核心原因是像素流依赖的编解码插件没有声明支持LinuxArm64平台。具体来说，需要修改三个插件的.uplugin文件：

Engine/Plugins/Experimental/AVCodecs/AVCodecsCore/AVCodecsCore.uplugin
Engine/Plugins/Experimental/AVCodecs/NVCodecs/NVCodecs.uplugin
Engine/Plugins/Experimental/AVCodecs/AMFCodecs/AMFCodecs.uplugin

打开这些文件后，找到SupportedTargetPlatforms数组，添加LinuxArm64。修改后的配置应该类似这样：

"SupportedTargetPlatforms": [ "Win64", "Linux", "LinuxArm64", "Mac" ]

这里有个坑要注意：修改完.uplugin文件后，必须重新生成项目文件。我试过直接打包，结果修改没生效。正确做法是：

删除项目目录下的Binaries和Intermediate文件夹
运行GenerateProjectFiles.sh
重新打开UE5编辑器

3. 修复预编译配置错误

解决了平台支持问题后，接下来可能会遇到预编译相关的错误：

Missing precompiled manifest for 'AVCodecsCore'

这个错误表明相关模块没有被正确标记为预编译模块。解决方法是在对应模块的.build.cs文件中添加预编译设置。以AVCodecsCore模块为例：

打开Engine/Plugins/Experimental/AVCodecs/AVCodecsCore/Source/AVCodecsCore/AVCodecsCore.build.cs
在构造函数中添加：

PrecompileForTargets = PrecompileTargetsType.Any;

同样的修改也需要应用到NVCodecs模块：

// NVCodecs.build.cs PublicDependencyModuleNames.AddRange(new string[] { "Core", "Engine", "AVCodecsCore" }); PrecompileForTargets = PrecompileTargetsType.Any;

修改后必须执行完整重建，否则可能遇到奇怪的链接错误。我建议的完整步骤是：

清理所有中间文件：rm -rf Engine/Intermediate
重新生成Makefile：./GenerateProjectFiles.sh
执行完整构建：make MyProject LinuxArm64 Development -j$(nproc)

4. 其他常见问题排查

除了上述两个主要问题外，在LinuxArm64打包过程中还可能遇到：

4.1 动态库链接错误

这类错误通常表现为运行时找不到.so文件。解决方法是在打包设置中正确配置动态库搜索路径。在项目的Config/LinuxArm64/Game.ini中添加：

[Core.System] Paths=../../../Engine/Binaries/LinuxArm64/ Paths=../../../MyProject/Binaries/LinuxArm64/

4.2 内存不足导致编译失败

在资源有限的机器上，可能会遇到编译器被OOM killer终止的情况。解决方法有：

增加swap空间：sudo fallocate -l 8G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
限制并行编译任务数：make -j4而不是make -j$(nproc)

4.3 纹理格式不支持

某些平台特定的纹理格式在Arm架构上可能不可用。可以在项目设置的DefaultEngine.ini中禁用：

[TextureLODSettings] DisablePlatformSpecificTextureFormats=True

5. 打包后的部署注意事项

成功生成LinuxArm64版本的打包文件后，部署时还需要注意：

确保目标机器有正确的glibc版本。我遇到过因为开发机glibc版本比生产环境高导致的兼容性问题。
像素流服务需要额外的端口配置。除了常规的HTTP端口外，还需要开放：
- 8888端口用于信令服务
- 8000-8100端口范围用于WebRTC流
性能调优建议：
- 设置r.VSync=0禁用垂直同步
- 调整r.ScreenPercentage降低渲染分辨率
- 启用r.AllowOcclusionQueries=0减少CPU开销

最后分享一个实用技巧：在服务器上运行UE5应用时，建议使用nohup配合disown让进程在后台稳定运行：