Ubuntu 20.04下AirSim与UE4联合仿真环境搭建全攻略

1. 项目概述与环境准备在自动驾驶、无人机和机器人算法的研发领域仿真测试是验证算法鲁棒性、安全性和效率的关键环节它能将昂贵的物理测试成本和对现实世界的潜在风险降到最低。微软开源的AirSim作为一个基于游戏引擎的高保真物理仿真平台因其对传感器如摄像头、激光雷达、IMU的精细模拟和对PX4、ROS等生态的良好支持成为了研究者和工程师的首选工具之一。而Unreal Engine 4UE4则为其提供了令人惊叹的视觉渲染能力和灵活的场景构建工具。然而将AirSim与UE4在Ubuntu 20.04这个稳定的Linux发行版上成功“撮合”起来并开发属于自己的仿真场景这个过程本身就像一场充满技术细节的“探险”。我花了将近一周的时间踩遍了从驱动安装到编译错误的几乎所有“坑”才最终让无人机在自定义的城市上空稳定起飞。这篇文章就是这份“探险”笔记的完整复盘旨在为后来者铺平道路让你能绕过我踩过的那些坑高效地搭建起属于你自己的高逼真度仿真沙盒。这个环境主要面向几类朋友一是从事自动驾驶、无人机路径规划或计算机视觉算法的研究者需要一个可编程、可重复的测试环境二是机器人领域的工程师希望在实际部署前在仿真中验证控制逻辑和感知系统三是任何对高保真模拟感兴趣并愿意在Linux环境下折腾的技术爱好者。整个流程可以概括为三个核心阶段首先是打好地基即准备一个“干净”且驱动完备的Ubuntu 20.04系统其次是构建核心分别安装并配置UE4和AirSim最后是创造世界将自定义的3D场景导入UE4并与AirSim联动。我会在每个阶段都穿插我实际遇到的“坑”和解决技巧这些往往是官方文档不会详细提及的。注意整个安装过程对网络环境要求较高需要从GitHub、Epic Games等国外服务器拉取大量数据UE4引擎本身约30GBAirSim及依赖约5GB。请确保你的网络连接稳定并具备科学合理的访问外部开发资源的能力。同时你需要一台性能足够的机器我建议至少配备NVIDIA独立显卡GTX 1060 6G或以上、16GB内存和100GB以上的可用磁盘空间。1.1 系统基础与显卡驱动部署很多人搭建环境的第一步就栽在了显卡驱动上。Ubuntu 20.04自带的nouveau开源驱动虽然能点亮屏幕但性能孱弱完全无法满足UE4编辑器运行和实时渲染的需求。安装专有NVIDIA驱动是必须跨越的第一道坎。我强烈推荐使用Ubuntu官方仓库的ubuntu-drivers工具进行安装这是最稳定、与系统集成度最高的方法。首先更新软件包列表并安装工具sudo apt update sudo apt install ubuntu-drivers-common接着查看系统推荐的驱动版本ubuntu-drivers devices这个命令会列出所有可用的驱动版本并标记出推荐安装的版本通常后面会跟着[recommended]。例如输出可能显示nvidia-driver-550是推荐版本。直接使用apt安装它sudo apt install nvidia-driver-550安装完成后必须重启系统以使新驱动生效。重启后在终端输入nvidia-smi如果能看到显卡信息、驱动版本和CUDA版本即使你还没装CUDA Toolkit这里也会显示一个基础版本则说明驱动安装成功。这是后续所有图形工作的基石。实操心得我曾尝试过从NVIDIA官网下载.run文件手动安装虽然版本可能更新但极易与系统内核模块产生冲突导致开机黑屏或循环登录。一旦出现问题恢复起来非常麻烦。而通过仓库安装系统会自动处理好内核模块的编译和签名稳定性高得多。如果nvidia-smi命令报错或找不到大概率是驱动没有正确加载可以尝试sudo prime-select nvidia切换显卡模式并再次重启。1.2 核心依赖与工具链安装驱动就位后我们需要为编译UE4和AirSim准备“武器库”。这包括编译工具链、必要的库文件以及版本管理工具。安装基础编译工具和Python3UE4和AirSim的编译构建离不开它们。sudo apt install build-essential cmake clang-12 lld-12 python3 python3-pip这里指定clang-12和lld-12是因为UE4源码编译对Clang版本有特定要求12是一个经过验证的稳定版本。安装.NET Core SDKAirSim的构建脚本build.sh是基于.NET Core编写的因此需要安装它来运行构建命令。wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb sudo apt update sudo apt install -y dotnet-sdk-6.0 # 或更高版本以AirSim仓库要求为准安装Git和图形化依赖用于拉取代码和满足UE4编辑器的运行需求。sudo apt install git libxcb1-dev libx11-xcb-dev libglu1-mesa-dev freeglut3-dev mesa-common-dev libxi-dev libxcursor-dev libxrandr-dev libxinerama-dev完成上述步骤后你的系统基础环境就已经准备好了。可以运行gcc --version、cmake --version和dotnet --version来验证关键工具是否安装成功。2. Unreal Engine 4 源码获取与编译这是整个流程中耗时最长、也最容易出错的一步。UE4不像普通软件那样直接提供二进制安装包我们需要从Epic Games的GitHub仓库拉取完整的源代码进行编译。官方推荐使用git clone --depth 1来减少下载量但对于后续开发和切换版本来说浅克隆可能会带来麻烦。我的建议是如果你磁盘空间充足需要约80GB最好进行完整克隆。2.1 获取Epic Games账户并关联GitHub首先你需要一个Epic Games账户。前往 Epic Games官网 注册。注册完成后登录你的GitHub账户在设置中关联你的Epic Games账户。这是必须的一步因为UE4的Git仓库是私有的关联后GitHub账户会获得访问权限。2.2 克隆UE4源码仓库打开终端选择一个空间充足的目录如~/Development执行克隆命令。由于仓库巨大这个过程可能需要数小时请保持网络稳定。cd ~ mkdir Development cd Development git clone https://github.com/EpicGames/UnrealEngine.git -b 4.27这里我指定了-b 4.27分支因为AirSim对UE4版本有兼容性要求4.27是一个被广泛测试和支持的稳定版本。克隆完成后进入目录cd UnrealEngine2.3 运行安装脚本并开始编译UE4提供了一个自动化安装脚本它会下载剩余的二进制依赖组件如.NET、Visual Studio Code的调试工具等即使在Linux上也需要。./Setup.sh这个脚本运行时间较长它会检查系统环境并下载约数GB的依赖文件。完成后开始真正的编译./GenerateProjectFiles.sh makemake编译是整个过程的核心它会调用Clang编译器消耗大量的CPU和内存资源。在我的Ryzen 7 5800X8核16线程和32GB内存的机器上这个过程持续了大约2个半小时。期间CPU会持续满载风扇狂转这是正常现象。注意事项与排坑实录内存不足编译UE4是内存吞噬兽。如果内存不足例如只有8GB极有可能在编译到70%-80%时因virtual memory exhausted而失败。解决方案有两种一是增加物理内存或创建足够大的交换空间swap我建议交换空间至少16GB二是使用make -j N限制并行编译任务数N为你的CPU核心数甚至更少如make -j 4以减少内存峰值压力。磁盘空间不足确保目标分区有超过100GB的可用空间。编译过程中会产生大量的中间文件。网络超时./Setup.sh下载依赖时可能因网络问题失败。可以尝试多次运行或者寻找可靠的网络环境。有时失败后再次运行脚本会从中断处继续。编译错误如果遇到特定的编译错误通常与缺少某个系统库有关。仔细阅读错误信息根据提示使用apt安装对应的-dev包。一个常见的错误是关于libXcursor的确保你已经安装了libxcursor-dev。编译成功后你会在UnrealEngine目录下看到Engine文件夹里面包含了Binaries等子目录。你可以运行一个简单的测试来验证UE4编辑器是否能够启动cd ~/Development/UnrealEngine/Engine/Binaries/Linux ./UE4Editor首次启动会进行着色器编译等初始化工作可能需要几分钟。如果成功出现了UE4编辑器的启动画面和项目浏览器那么恭喜你最艰难的一步已经完成了。3. AirSim 源码编译与UE4插件集成AirSim本身是一个UE4插件。我们需要先获取AirSim源码将其编译成插件文件然后集成到UE4引擎或一个UE4项目中。3.1 克隆与准备AirSim源码在另一个目录例如~/Development下克隆AirSim仓库cd ~/Development git clone https://github.com/microsoft/AirSim.git cd AirSimAirSim的构建系统使用了自己编写的脚本。首先我们需要更新其子模块git submodule update --init --recursive3.2 编译AirSim插件AirSim提供了针对Linux的编译脚本。在AirSim根目录下直接运行./build.sh这个脚本会检查环境包括之前安装的.NET Core SDK和编译工具。使用cmake配置生成构建文件。调用make进行编译。编译过程比UE4快得多通常10-20分钟即可完成。编译成功后会在AirSim根目录下生成一个名为Unreal的文件夹如果不存在则创建并在其中生成插件所需的文件最关键的是AirSim.so动态链接库和AirSim.uplugin插件描述文件。3.3 将AirSim插件集成到UE4中有两种集成方式引擎级集成和项目级集成。引擎级集成会将插件安装到UE4引擎的全局插件目录这样所有基于该引擎创建的项目都能直接使用AirSim。项目级集成则是将插件文件复制到特定项目的Plugins文件夹下只对该项目生效。对于学习和开发自定义场景我推荐项目级集成因为它更干净不影响引擎本身。步骤一创建或打开一个UE4空白项目启动之前编译好的UE4编辑器 (./UE4Editor)。在项目浏览器中选择“Games” - “Blank”创建一个新的C空白项目必须是C项目蓝图项目无法直接集成源码插件。给项目起个名字比如MyAirSimProject选择保存路径。点击“Create”编辑器会为你生成项目文件并打开。步骤二复制插件文件关闭UE4编辑器。在文件管理器中导航到你的AirSim源码目录下的Unreal/Plugins文件夹。你应该能看到一个AirSim文件夹。将这个AirSim文件夹整个复制到你刚创建的UE4项目目录下。项目目录结构通常为MyAirSimProject/MyAirSimProject.uproject所在的同级目录。你需要创建一个Plugins文件夹如果不存在然后将AirSim粘贴进去。最终路径应类似于~/Development/MyAirSimProject/Plugins/AirSim/。步骤三重新生成项目文件并编译由于我们添加了一个C插件需要重新生成Visual Studio或Xcode项目文件在Linux下是Makefile。在项目根目录有.uproject文件的地方打开终端运行# 首先找到你编译的UE4引擎的GenerateProjectFiles脚本 # 假设引擎在 ~/Development/UnrealEngine ~/Development/UnrealEngine/GenerateProjectFiles.sh -project/path/to/your/MyAirSimProject/MyAirSimProject.uproject -game -engine或者更简单的方法是直接双击项目目录下的.uproject文件。系统可能会提示你“缺少模块”询问是否要重新编译。选择“是”。UE4会自动调用编译工具编译项目代码和集成的AirSim插件。编译完成后UE4编辑器会再次启动。此时在编辑器的菜单栏中你应该能看到“Settings” - “Plugins”。在插件列表中搜索“AirSim”它应该处于已启用Enabled状态。这表明AirSim插件已经成功集成到你的项目中了。4. 自定义场景开发与导入流程拥有了搭载AirSim插件的UE4项目我们终于可以着手创建自己的仿真世界了。场景来源主要有两种使用UE4内置工具从零搭建或者导入第三方制作的3D模型如FBX格式。对于机器人仿真我们更关注环境的几何结构和物理属性而非极致的美术效果因此导入现有模型是更高效的选择。4.1 准备3D模型资产你可以从许多在线资源库如Sketchfab、TurboSquid找到免费的或付费的3D场景模型通常以.fbx或.obj格式提供。这里以一个简单的.fbx格式的街区模型为例。在导入前有几点需要特别注意模型尺寸和单位许多3D建模软件如Blender、3ds Max的默认单位与UE4厘米可能不一致。在导出FBX时务必在导出设置中将单位调整为“厘米”Centimeters并勾选“应用缩放”Apply Scale。否则模型导入UE4后可能变得巨大或微小。模型复杂度过于精细的模型面数过高会严重影响仿真时的渲染性能。在可能的情况下在3D软件中进行适当的减面优化Decimation。材质和纹理确保模型附带的纹理图片如.jpg,.png也一并准备好并放在一个单独的文件夹里方便UE4导入时自动关联。4.2 在UE4中导入FBX场景在你的MyAirSimProject中在内容浏览器Content Browser里右键点击空白处选择“Import to /Game...”。在弹出的文件对话框中找到你的.fbx文件选中它。会弹出一个FBX导入选项对话框。这里有几个关键设置Import Content Type 保持默认的“Geometry and Materials”几何体和材质。Material Import Method 选择“Do Not Create Material”不创建材质。如果模型自带材质UE4会尝试导入如果选择创建UE4会生成默认材质球通常不是我们想要的。Transform 检查“Import Uniform Scale”是否为1.0。如果你的模型在导出时已正确处理单位这里保持默认即可。Mesh 勾选“Combine Meshes”合并网格体可以简化场景层级但有时为了单独控制某个物体如可移动的障碍物可能需要分开。点击“Import”。UE4会开始处理模型并在内容浏览器中生成对应的静态网格体Static Mesh和材质Material资产。实操心得我导入一个中等规模的FBX城市模型时遇到了“未发现平滑组”的警告。这通常意味着模型在导出时丢失了面的平滑信息导致在UE4中渲染时出现不自然的硬边。解决方法有两种一是在原始的3D建模软件中重新计算并导出平滑组二是在UE4中双击导入的静态网格体在网格体编辑器中选择所有面在“细节”面板中找到“法线”Normals部分点击“重新计算平滑组”Recompute Normals或“平均法线”Average Normals可以很大程度上改善外观。4.3 构建场景与设置玩家出生点放置场景从内容浏览器中将刚刚导入的静态网格体拖拽到视口Viewport中它就会成为你场景的一部分。你可以使用移动、旋转、缩放工具快捷键W/E/R来调整它的位置。添加地面和碰撞导入的模型可能没有物理碰撞体这意味着无人机或车辆会直接穿透它。你需要为场景添加碰撞。在静态网格体编辑器中可以点击“碰撞”Collision菜单选择“添加简化碰撞”Add Simplified Collision或“自动生成凸包碰撞”Auto Convex Collision。对于复杂地形使用“简化碰撞”生成一个包裹模型的大致形状的简单碰撞盒通常就足够了性能更好。设置玩家出生点在UE4中仿真智能体如无人机的初始位置是由“Player Start”演员决定的。在模式面板Modes Panel中搜索“Player Start”将其拖放到场景中你希望无人机初始出现的位置例如离地2米高的空中。添加光源默认场景可能是黑的。从模式面板拖拽一个“定向光源”Directional Light和“天空大气”Sky Atmosphere到场景中可以快速获得基本的日光照明效果。4.4 配置AirSim仿真参数场景搭建好后我们需要告诉AirSim在这个场景中模拟什么。这通过一个名为settings.json的配置文件来完成。这个文件需要放在你的项目可执行文件或项目内容目录旁边。在你的项目目录下与.uproject文件同级创建一个名为settings.json的文件。用文本编辑器打开输入基本的配置。以下是一个支持多旋翼无人机Multirotor的简单配置示例{ SeeDocsAt: https://github.com/Microsoft/AirSim/blob/master/docs/settings.md, SettingsVersion: 1.2, SimMode: Multirotor, // 仿真模式Multirotor无人机, Car车 Vehicles: { Drone1: { VehicleType: SimpleFlight, // 飞行控制器类型 DefaultVehicleState: Armed, AllowAPIAlways: true, EnableCollisionPassthrough: false, EnableCollisions: true, X: 0, Y: 0, Z: -2, // 初始位置偏移相对于Player StartZ-2表示在出生点下方2米UE4 Z轴向上 Pitch: 0, Roll: 0, Yaw: 0 // 初始姿态 } }, CameraDefaults: { CaptureSettings: [ { ImageType: 0, // 0: Scene场景图, 1: DepthPlanner深度图, 2: Segmentation语义分割图 Width: 640, Height: 480 } ] } }这个配置定义了一架名为“Drone1”的无人机使用内置的SimpleFlight飞控模型并启用了一台分辨率为640x480的前向场景摄像头。5. 运行联合仿真与基础API调用测试环境、插件、场景、配置都已就绪现在是见证成果的时刻。5.1 启动仿真在UE4编辑器中确保你的场景已经保存CtrlS。点击工具栏上的“Play”按钮或按F8旁边的下拉箭头选择“Standalone Game”模式。这会以独立游戏的方式运行你的项目而不是在编辑器视口中播放。点击“Play”。UE4会编译最后的着色器如果第一次运行此场景然后弹出一个独立的游戏窗口显示你的3D场景。无人机可能是一个默认的模型如四轴飞行器会出现在你设置的Player Start位置。此时AirSim仿真服务器已经在后台运行并监听API调用。5.2 使用Python API进行控制测试AirSim提供了多种语言的客户端APIPython是最方便进行快速测试的一种。打开一个新的终端。安装AirSim Python客户端库pip install msgpack-rpc-python airsim编写一个简单的测试脚本例如test_drone.pyimport airsim import time # 连接到AirSim仿真服务器 client airsim.MultirotorClient() client.confirmConnection() # 等待连接建立 # 解锁无人机Arm client.enableApiControl(True, vehicle_nameDrone1) client.armDisarm(True, vehicle_nameDrone1) # 起飞到5米高度 print(Taking off...) client.takeoffAsync(vehicle_nameDrone1).join() time.sleep(2) # 向前飞10米 print(Moving forward...) client.moveByVelocityBodyFrameAsync(3, 0, 0, 2, vehicle_nameDrone1).join() # vx3m/s, 持续2秒 time.sleep(1) # 悬停2秒 client.hoverAsync(vehicle_nameDrone1).join() time.sleep(2) # 降落 print(Landing...) client.landAsync(vehicle_nameDrone1).join() # 上锁并断开API控制 client.armDisarm(False, vehicle_nameDrone1) client.enableApiControl(False, vehicle_nameDrone1) print(Test completed.)在仿真运行的情况下在终端运行这个脚本python3 test_drone.py如果一切顺利你将看到游戏窗口中的无人机自动执行起飞、前飞、悬停和降落的动作。同时终端会打印出相应的状态信息。至此一个完整的Ubuntu 20.04下AirSim与UE4联合仿真环境以及自定义场景的开发流程就全部跑通了。6. 常见问题排查与性能优化技巧即便按照步骤操作你也可能会遇到一些棘手的问题。下面是我在搭建和调试过程中遇到的典型问题及其解决方案。6.1 编译与启动类问题问题现象可能原因解决方案./Setup.sh或./GenerateProjectFiles.sh失败1. 网络问题导致依赖下载失败。2. 系统缺少基础工具如curl,git。3. 磁盘空间不足。1. 检查网络重试脚本。对于Setup.sh可以尝试手动下载缺失的依赖文件查看脚本日志。2. 运行sudo apt install curl git等。3. 清理磁盘确保有 100GB 空间。make编译 UE4 时内存耗尽OOM Killer系统物理内存和交换空间不足。1.增加交换空间sudo fallocate -l 16G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile。可将其加入/etc/fstab永久生效。2.减少并行编译任务使用make -j 2或make -j 4大幅降低内存峰值。UE4编辑器启动崩溃或黑屏1. 显卡驱动问题。2. 编译不完整或有错误。3. 特定显卡兼容性问题。1. 用nvidia-smi确认驱动加载。尝试sudo prime-select nvidia并重启。2. 尝试完全清理后重新编译make clean然后make。3. 在编辑器启动命令后添加-opengl或-vulkan参数尝试不同的图形API。AirSim./build.sh失败提示 .NET 错误.NET SDK 未安装或版本不对。确认已安装正确的 .NET SDK 版本如6.0或7.0。运行dotnet --list-sdks查看。根据AirSim仓库README要求安装指定版本。项目打开时提示“Missing AirSim Module”插件未正确集成或项目文件未更新。1. 确认Plugins/AirSim文件夹已正确复制到项目目录。2. 右键点击.uproject文件选择“Generate Visual Studio project files”在Linux下通过引擎目录的脚本。3. 删除项目目录下的Binaries和Intermediate文件夹然后重新生成。6.2 运行时与API连接问题问题现象可能原因解决方案Python脚本连接超时 (airsim.exceptions.TimeoutError)1. AirSim仿真未启动。2. 防火墙或端口冲突。3.settings.json配置错误。1. 确保已通过UE4以“Standalone Game”模式启动项目并看到游戏窗口。2. AirSim默认使用41451端口。检查是否有其他程序占用netstat -tulpn | grep 41451。3. 检查settings.json中AllowAPIAlways: true是否设置。无人机在场景中“抽搐”或物理异常1. 场景碰撞体设置不当。2. 仿真帧率过低。3.SimpleFlight模型参数不适配当前场景重力或尺度。1. 检查场景静态网格体的碰撞是否已正确生成在UE4编辑器中显示碰撞视图查看。2. 在游戏窗口按反引号打开控制台输入stat fps查看帧率。低于30帧可能导致物理更新不稳定。需要优化场景或降低图形设置。3. 尝试在settings.json的车辆配置中调整Gravity参数或使用更高级的VehicleType: PX4并连接PX4软件在环仿真。摄像头图像获取为全黑或全白1. 场景光源问题。2. 相机曝光参数设置不当。3. API调用图像类型错误。1. 在UE4场景中确保有有效光源Directional Light, Sky Atmosphere。2. 在settings.json的CaptureSettings中调整FOV_Degrees、AutoExposureSpeed等参数。3. 确认Python API中请求的图像类型如Scene与settings.json中配置的ImageType匹配。无法通过API控制无人机1. API控制未启用。2. 无人机未解锁Arm。3. 车辆名称不匹配。1. 确保脚本中调用了client.enableApiControl(True)。2. 确保脚本中调用了client.armDisarm(True)。3. 检查脚本中vehicle_name参数与settings.json中定义的车辆键名如Drone1完全一致。6.3 性能优化与开发建议场景优化是性能关键仿真帧率FPS直接影响控制的实时性和物理模拟的准确性。对于大型自定义场景使用LOD层次细节在UE4中为复杂静态网格体设置LOD让远处的模型用更少的面数渲染。合并网格体将大量小物体如一堆石头、草丛合并成一个大的静态网格体可以减少绘制调用Draw Calls。谨慎使用动态光源和阴影实时阴影非常消耗性能。尽量使用烘焙光照Lightmass或静态光源。在AirSim中关闭不必要的传感器在settings.json中只启用你实验必需的传感器如摄像头、激光雷达。每个传感器都会增加每帧的计算开销。使用tmux或screen管理长时间任务编译UE4、运行仿真服务器都是长时间进程。在远程服务器或防止终端关闭导致任务中断时使用tmux new -s ue4_build创建一个会话在其中运行编译命令即使断开SSH连接编译也会继续。版本控制与备份UE4项目目录尤其是Content和Config文件夹和AirSim的settings.json文件应该纳入Git版本控制。但注意不要提交Binaries、Intermediate、DerivedDataCache等编译生成的大型文件夹将它们添加到.gitignore中。调试与日志当出现诡异问题时查看日志是首要任务。AirSim的日志默认输出到~/.ros/log或项目目录下的airsim.log文件取决于设置。UE4编辑器的日志可以在启动时添加-log参数或查看~/.config/Epic/UnrealEngine/4.27/下的日志文件。仔细阅读错误信息往往能快速定位问题根源。搭建这个环境的过程就像在组装一台精密的仪器每一个环节的严丝合缝都至关重要。从驱动到编译从导入到配置每一步的疏忽都可能导致后续的失败。但一旦成功你所获得的将是一个功能强大、高度可控的虚拟试验场无论是测试一个新颖的SLAM算法还是验证一套复杂的无人机编队协议它都能提供接近真实的反馈。我个人的体会是前期在系统环境和编译上多花些时间确保基础稳固远比在后期调试各种古怪问题时反复折腾要高效得多。最后一个小技巧将成功的环境状态包括特定的驱动版本、UE4提交哈希、AirSim分支记录下来形成你自己的“已知稳定配置”这在未来升级或复现时能节省大量时间。