Ubuntu 20.04下从源码编译UE4并集成AirSim仿真环境的完整指南

1. 项目概述当UE4遇见Ubuntu一场技术与耐心的较量如果你是一名从事无人机、自动驾驶或者机器人仿真的开发者那么AirSim这个由微软开源的仿真平台大概率是你绕不开的一个选择。它基于虚幻引擎4UE4构建提供了极其逼真的物理和视觉环境是算法验证的绝佳沙盒。然而当这份“绝佳”从熟悉的Windows平台迁移到以稳定和高效著称的Linux发行版Ubuntu上时故事的开头往往就充满了挑战。我最近就在Ubuntu 20.04 LTS上完整地走了一遍从源码编译UE4到成功运行AirSim仿真的全过程毫不夸张地说这更像是一场对系统知识、编译原理和耐心的综合考验。网上零散的教程很多但大多只告诉你“怎么做”却很少深入解释“为什么这么做”以及“做错了怎么办”。今天我就把自己踩过的坑、理清的思路和最终验证可行的步骤系统地分享出来。无论你是刚接触这个领域的新手还是被某个编译错误卡住的老手希望这篇详尽的记录都能帮你更顺畅地搭建起属于你的AirSim仿真世界。2. UE4引擎在Ubuntu下的编译从源码到可执行文件的漫长征途在Windows上我们通常直接下载Epic Games启动器安装UE4过程近乎傻瓜式。但在Ubuntu上我们必须从源码开始编译。这不仅仅是多敲几个命令更是对系统环境、依赖库和编译工具链的一次深度体检。2.1 环境准备打好地基避免“空中楼阁”编译UE4这样的庞然大物源码超过百万行一个纯净、规范且依赖齐全的初始环境至关重要。许多后续的诡异错误根源都在这一步。2.1.1 系统与硬件要求首先确认你的Ubuntu版本。官方推荐18.04或20.04 LTS。我强烈建议使用20.04 LTS它在软件包可用性和社区支持上达到了一个很好的平衡。至于22.04虽然更新但一些较老的依赖库可能发生变化无形中增加了不确定性。硬件方面这是真正的资源吞噬者。我建议的最低配置是CPU: 6核12线程以上。编译过程高度并行核心越多编译速度越快。我的12核机器完整编译耗时约2.5小时。内存: 32GB。这是硬性门槛。16GB内存会在编译链接阶段频繁触发交换分区导致编译速度极慢甚至因内存不足OOM而崩溃。硬盘: 至少150GB的SSD剩余空间。UE4源码、中间文件和编译输出会占用巨大空间机械硬盘的IO速度会成为无法忍受的瓶颈。显卡: 支持Vulkan或OpenGL 4.3的独立显卡。虽然编译阶段不强制但后续运行编辑器需要。NVIDIA显卡在Linux下的驱动支持相对更好。2.1.2 安装核心依赖与工具链接下来的步骤请严格按照顺序在终端中执行。这些命令为编译UE4提供了必要的编译器、库和工具。# 1. 更新软件包列表并升级现有软件 sudo apt update sudo apt upgrade -y # 2. 安装编译所需的基础工具 sudo apt install -y build-essential cmake git # 3. 安装UE4编译所需的特定依赖库 # 这个列表是官方文档和社区经验的总结涵盖了从图形、音频到网络的各种库 sudo apt install -y \ mono-devel \ libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev \ libxss-dev libgl1-mesa-dev libglu1-mesa-dev \ freeglut3-dev libopenal-dev libpulse-dev \ libudev-dev libxi-dev libxxf86vm-dev \ libogg-dev libvorbis-dev libvorbisfile3 libvorbisenc2 \ libfreetype6-dev libgtk-3-dev libgtk2.0-dev \ libasound2-dev libcairo2-dev libdbus-1-dev \ libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ libjpeg-dev libtiff5-dev libwebp-dev \ libsdl2-dev libsmpeg-dev libtheora-dev \ libopenexr-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev \ liblz4-dev libbz2-dev zlib1g-dev \ libncurses5-dev libssl-dev \ libflac-dev libmodplug-dev \ libpng-dev libusb-1.0-0-dev注意安装过程中如果遇到“无法定位软件包”的错误通常是包名在Ubuntu版本间发生了变化。例如libtiff5-dev在更早版本中可能是libtiff4-dev。此时可以尝试使用apt search libtiff来查找正确的包名。2.1.3 获取UE4源码并关联GitHub账户UE4的源码托管在GitHub上但访问需要Epic Games的账户授权。# 1. 克隆UE4的Git仓库这是一个“空”仓库用于管理子模块 git clone https://github.com/EpicGames/UnrealEngine.git cd UnrealEngine # 2. 检查out并切换到稳定的发布分支例如4.27AirSim对特定版本有要求请查阅其文档 git checkout 4.27接下来是关键一步运行设置脚本。这个脚本会下载数十GB的子模块代码并验证你的GitHub账户是否关联了Epic Games账户。./Setup.sh脚本运行中它会提示你打开一个网页链接通常是https://www.unrealengine.com/github并用你的Epic Games账户登录进行授权。授权成功后脚本才会继续下载。这个过程耗时很长且网络必须稳定。如果中途失败可以重复运行./Setup.sh它会尝试续传。2.2 编译过程详解与“陷阱”的正面交锋当Setup.sh成功运行完毕后真正的编译才开始。这里有几个关键的决策点和陷阱。2.2.1 生成项目文件UE4使用它自己的构建系统但需要通过一个生成步骤来创建Makefile或Ninja构建文件。./GenerateProjectFiles.sh这个脚本会检测你的系统环境并生成相应的构建文件。如果一切正常你会在目录下看到UE4.sln如果安装了mono和一系列.make文件。2.2.2 执行编译选择构建目标最常用的编译命令是make或者如果你希望看到更详细的输出可以使用make -j $(nproc) 21 | tee build.log-j $(nproc)使用你CPU的所有核心进行并行编译极大加速过程。21 | tee build.log将标准输出和错误输出都重定向到build.log文件同时也在终端显示。这至关重要因为编译日志是排查错误的唯一依据。陷阱一内存不足OOM Killer这是最常见的问题。即便你有32GB内存在链接最终的可执行文件如UnrealEditor时单个链接进程可能试图分配超过20GB的内存。如果系统物理内存不足Linux的OOM Killer会无情地终止这个进程导致编译失败错误信息可能很模糊比如“Killed”或“段错误”。解决方案增加交换空间Swap。虽然慢但可以预防OOM。建议设置一个20-30GB的交换文件。sudo fallocate -l 30G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 为了永久生效需要将 /swapfile none swap sw 0 0 添加到 /etc/fstab限制并行编译任务数。使用make -j 8或更小的数字减少同时进行的内存密集型任务。最根本的升级物理内存至64GB。陷阱二依赖库版本冲突系统可能安装了多个版本的同一个库如OpenSSL或者安装了不兼容的版本。错误信息通常包含“找不到 -lxxx”或“对‘xxx’未定义的引用”。解决方案使用ldconfig -p | grep xxx查找库文件。确认已安装2.1.2节中所有-dev包开发包它们提供了头文件和链接库。有时需要手动创建符号链接。例如如果找不到libvorbisfile.so但存在libvorbisfile.so.3可以sudo ln -s /usr/lib/x86_64-linux-gnu/libvorbisfile.so.3 /usr/lib/x86_64-linux-gnu/libvorbisfile.so陷阱三磁盘空间不足编译中途因磁盘满而失败。除了确保初始空间还要注意UE4的中间文件目录Engine/Intermediate/也会占用大量空间。编译前可用df -h检查。2.2.3 验证编译成功编译成功完成后在Engine/Binaries/Linux/目录下你应该能找到UnrealEditor这个可执行文件。尝试运行它cd Engine/Binaries/Linux/ ./UnrealEditor如果UE4编辑器能够正常启动会出现一个项目浏览器窗口那么恭喜你最艰难的一关已经过了。3. AirSim仿真环境的搭建与集成有了可用的UE4引擎搭建AirSim就相对清晰了。AirSim本质上是一个UE4插件或一个独立项目我们需要将其集成到UE4中。3.1 获取与准备AirSim源码AirSim的源码同样在GitHub上。我们需要克隆它并进行一些前置编译。# 1. 回到你的工作目录例如 ~/Projects cd ~/Projects # 2. 克隆AirSim仓库 git clone https://github.com/microsoft/AirSim.git cd AirSim # 3. 更新子模块 git submodule update --init --recursive3.2 编译AirSim的依赖与插件AirSim包含两部分1) 一个用C编写的UE4插件提供仿真核心功能2) 一个Python/ C 的客户端库用于外部控制。在Linux下我们需要先编译一些外部依赖。3.2.1 编译rpclib和MavLinkComAirSim使用rpclib进行RPC通信。我们需要先编译它。# 在AirSim根目录下 ./setup.sh这个脚本会自动下载并编译rpclib、MavLinkCom等依赖。如果脚本执行顺利依赖就准备好了。如果失败通常需要手动检查build.sh或setup.sh脚本中的路径和命令确保它们指向你刚刚编译的UE4目录。3.2.2 关键配置指向你的UE4安装这是整合的核心。AirSim需要知道你的UE4引擎在哪里。我们需要修改AirSim的构建配置文件。找到AirSim/Unreal/Environments/目录下的任何.uproject文件例如Blocks.uproject用文本编辑器打开它。你需要添加一个EngineAssociation字段或者修改已有的字段使其指向你编译的UE4版本。更可靠的方法是使用符号链接或环境变量。通常编译AirSim插件时它会查找一个名为UE4_ROOT的环境变量。# 假设你的UE4编译在 ~/UnrealEngine export UE4_ROOT~/UnrealEngine然后进入插件目录进行编译cd AirSim/Unreal/Plugins/AirSim # 使用UE4自带的构建工具进行编译 $UE4_ROOT/Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project$PWD/../../Environments/Blocks/Blocks.uproject -TargetAirSim这个命令会调用UE4的构建系统针对Blocks项目编译AirSim插件。编译成功后插件文件.so等会被输出到Blocks项目的Plugins目录下。3.3 运行第一个仿真Blocks环境现在我们可以启动一个内置的仿真环境进行测试。cd AirSim/Unreal/Environments/Blocks # 确保使用我们编译的UE4编辑器来打开这个项目 ~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor Blocks.uprojectUE4编辑器会启动并加载Blocks项目。首次加载可能会需要编译着色器稍等片刻。加载完成后你应该能看到一个简单的有积木块的城市环境。在编辑器内运行仿真点击编辑器工具栏上的“播放”Play按钮。视图会切换到游戏模式。此时AirSim仿真服务器已经在运行并默认监听localhost:41451。你可以使用AirSim提供的Python API客户端来连接并控制。打开另一个终端# 安装AirSim Python客户端 pip install msgpack-rpc-python airsim # 运行一个简单的测试脚本 cd ~/Projects/AirSim/PythonClient python hello_drone.py如果一切正常脚本会连接到仿真器生成一个无人机并打印其初始状态。你也能在UE4编辑器窗口中看到无人机的模型。4. 常见问题排查与性能优化实录即便按照步骤操作也难免遇到问题。这里记录了我遇到的一些典型问题及其解决方法。4.1 编译阶段问题速查表问题现象可能原因排查与解决思路./Setup.sh卡在克隆某个子模块网络连接问题特别是对GitHub的访问不稳定。1. 配置Git代理如果条件允许且合规。2. 多次重试脚本它会尝试续传。3. 手动到Engine/Source/ThirdParty/下查找未完成的仓库单独克隆。make编译失败提示‘FPlatformMisc::NumberOfCores’相关错误通常是由于clang或libc版本不匹配。UE4对编译器工具链版本敏感。1. 确认使用的是系统默认的GCCg-9或g-10。2. 检查是否有残留的旧版本clang环境变量干扰。确保CC和CXX环境变量未设置或指向正确的GCC。链接错误undefined reference to ‘uuid_generate’缺少libuuid库。安装开发包sudo apt install libuuid1 uuid-dev编辑器能启动但打开项目时崩溃显卡驱动问题或OpenGL/Vulkan兼容性问题。1. 安装专有NVIDIA驱动sudo ubuntu-drivers autoinstall然后重启。2. 尝试以-opengl4或-vulkan参数启动编辑器./UnrealEditor -opengl4AirSim Python客户端连接超时UE4中的AirSim插件未正确加载或仿真未运行。1. 确保在UE4编辑器中点击了“播放”按钮进入仿真模式。2. 检查settings.json文件中的ApiServerPort是否为41451。3. 在终端用 netstat -tulnp4.2 运行阶段性能调优在Ubuntu下流畅运行UE4AirSim需要一些调优。4.2.1 图形性能优化使用Vulkan后端如果显卡支持在启动编辑器时加上-vulkan参数通常能获得比OpenGL更好的性能和稳定性。在项目设置中也可以强制指定。调整UE4渲染设置在编辑器内打开“项目设置” - “引擎 - 渲染”可以酌情关闭一些耗费资源的效果如动态全局光照Lumen如果版本支持、高精度阴影等特别是在运行大规模场景时。确保使用独立显卡在笔记本或双显卡系统上确保UE4编辑器进程使用的是高性能独立显卡。可以通过nvidia-smi命令在运行时查看。4.2.2 仿真性能优化降低渲染分辨率在非视觉算法测试时可以在UE4编辑器游戏视图的设置中降低分辨率显著提升帧率。调整AirSim物理频率在settings.json中ClockSpeed参数可以加快或减慢仿真时间。对于不需要实时性的测试可以适当提高此值以更快地收集数据。使用无头模式Headless如果完全不需要图形界面例如只做算法验证可以编译并运行UE4的无头模式服务器这将节省大量GPU资源。AirSim支持连接到无头服务器。4.3 项目迁移与资产路径问题一个常见的困扰是从Windows迁移到Ubuntu后项目中的资产如FBX模型、纹理引用丢失。这是因为UE4内部使用绝对路径或依赖于特定盘符。解决方案在Ubuntu上重新打开.uproject文件后UE4通常会尝试自动查找丢失的资产。如果失败需要在“内容浏览器”中右键点击有黄色感叹号的文件夹或资产选择“重新定位目录”然后指向资产在Linux系统中的新位置。更好的做法是在项目开发初期就使用相对于项目目录的路径并将所有外部资产放在项目目录内。5. 从仿真到现实AirSim的高级应用与扩展成功搭建环境只是第一步。要让AirSim真正服务于你的研发还需要掌握一些进阶用法。5.1 自定义环境搭建你不可能永远满足于Blocks环境。创建或导入自己的3D场景是必然。5.1.1 从3D建模软件导入如Blender将你的场景导出为FBX格式。确保单位比例正确通常米制。在UE4编辑器中在“内容浏览器”右键选择“导入到 /Game”选择你的FBX文件。导入后你需要处理材质和碰撞体。UE4可能会为导入的网格体生成简单的碰撞但对于无人机仿真你可能需要自定义更精确的碰撞体在静态网格体编辑器中设置。将导入的静态网格体拖入关卡视口调整位置和缩放。别忘了添加一个“玩家出生点”Player Start或通过AirSim的API来指定无人机的初始位置。5.1.2 使用Landscape工具创建地形对于无人机户外仿真UE4强大的地形系统非常有用。你可以使用真实世界的高度图数据来生成地形并绘制上不同的材质草地、岩石、雪地。5.2 传感器配置与数据获取AirSim的强大之处在于其可配置的多传感器模拟。在settings.json文件中你可以详细定义相机、激光雷达、IMU、GPS等传感器。{ SettingsVersion: 1.2, SimMode: Multirotor, Vehicles: { Drone1: { VehicleType: SimpleFlight, Sensors: { LidarSensor1: { SensorType: 6, Enabled: true, NumberOfChannels: 16, Range: 100.0, PointsPerSecond: 100000 }, MyCamera: { SensorType: 0, Enabled: true, CaptureSettings: [ { ImageType: 0, Width: 640, Height: 480 } ] } } } } }通过Python API你可以同步或异步地获取这些传感器的数据流用于训练感知模型或进行SLAM算法测试。import airsim client airsim.MultirotorClient() responses client.simGetImages([airsim.ImageRequest(MyCamera, airsim.ImageType.Scene)]) # 处理 responses[0].image_data_uint8 或 image_data_float5.3 与ROS机器人操作系统集成这是将仿真算法迁移到真实机器人的桥梁。AirSim提供了ROS包airsim_ros_pkgs。在你的ROS工作空间如~/catkin_ws/src中克隆ROS包。修改ROS包中的设置使其IP地址指向运行AirSim的机器如果是本机就是localhost。编译ROS包 (catkin_make)。启动AirSim仿真环境UE4。启动ROS节点roslaunch airsim_ros_pkgs airsim_node.launch。此时无人机状态、传感器数据如图像、激光雷达点云会以ROS话题的形式发布你可以用标准的ROS工具如rviz进行可视化或用ROS节点发送控制指令。这个过程会涉及网络配置如果ROS和AirSim不在同一台机器、坐标变换TF设置等细节是另一个需要耐心调试的环节但它打通了仿真与现实的闭环。整个UE4AirSim在Ubuntu下的搭建之旅就像在组装一台精密的钟表每一个零件都必须严丝合缝。它考验的不仅仅是你的技术知识更是系统性的问题解决能力。从内存不足的恐慌到依赖库缺失的迷茫再到最终看到无人机在自建场景中平稳起飞的那一刻所有的折腾都变得值得。这个环境一旦搭建稳定就会成为一个无比强大的研发工具让你在虚拟世界中安全、高效、低成本地迭代和验证你的算法。记住遇到问题多查日志build.log、编辑器输出日志善用搜索引擎和社区如AirSim的GitHub Issues你遇到的大部分坑前人都很可能已经踩过并留下了宝贵的解决方案。