每年都有不少做无人机、自动驾驶、机器人导航的同学问我想在Linux下跑AirSim仿真到底怎么把这套环境搭起来。说实话我自己第一次折腾Ubuntu 20.04 UE4 AirSim的时候也踩了不少坑——有人在Setup.sh就卡了两天有人编译UE4到一半内存不够直接崩了还有人装好之后发现显卡驱动不对编辑器一打开就闪退。这套东西并不是装个包那么简单它的本质是用UE4做高保真渲染引擎、用AirSim做物理和传感器仿真整个链路涉及系统显卡驱动、UE4源码编译、C插件构建三大部分。这篇文章把我从零到能跑通的完整步骤、参数选择、踩坑记录都写清楚适合准备用AirSim做无人机避障、视觉导航、自动驾驶算法验证的开发者参考。1. 项目概述与环境准备1.1 这套环境能做什么为什么值得折腾先说结论Ubuntu 20.04 UE4 AirSim 是目前学术圈和开源社区里做无人机和自动驾驶视觉仿真非常主流的一套组合。AirSim是微软开源的仿真平台提供无人机、汽车的动力学模型以及相机、激光雷达、IMU、GPS等传感器仿真UE4负责把场景渲染出来画面质量比一般的轻量级仿真器高不少。两者一组合就能在完全虚拟的环境里跑目标检测、避障算法、SLAM、端到端强化学习不用真机也能完成大部分前期验证。为什么选Ubuntu 20.04而不是18.04或者22.04主要原因是生态。20.04是很多机器人框架比如ROS Noetic的主战场教程最多、兼容性最好而且UE4 4.26/4.27在20.04上编译运行非常成熟。22.04我也试过一来LibreOffice这类的系统组件倒无所谓关键是内核和显卡驱动的兼容磨合差一点AirSim某些老版本在22.04上会有编译告警二来很多实验室已有的代码和文档都是按20.04写的跟着走不容易翻车。这套环境的本质其实可以拆成三个独立环节NVIDIA显卡驱动负责底层渲染加速UE4编辑器和AirSim的实时画面都靠它。UE4引擎开源的Unreal Engine 4.27 LTS版本负责场景、光照、材质、物理渲染。AirSim插件一个C插件编译后挂到UE4项目里提供无人机的飞行控制、传感器数据和动力学模型。很多人一上来就想直接跑结果发现缺了某个环节就报错。我的经验是把这三个环节分开处理全部验证通过后再组合排错会轻松非常多。1.2 硬件配置与系统要求先泼一盆冷水如果你的机器只有8GB内存、没有独立显卡那劝你暂时放弃这条路。UE4源码编译本身对资源消耗极大过程中要同时启动几个核心编译任务内存不够很容易 OOM内存耗尽被杀。我实际测试下来一套合理的底线配置是硬件项最低要求推荐配置CPU4核8核16线程及以上内存16GB32GB显卡NVIDIA GTX 1050NVIDIA RTX 3060及以上硬盘60GB剩余空间NVMe SSD剩余100GB以上系统Ubuntu 20.04Ubuntu 20.04.6 LTS这里硬盘空间要特别强调很多人只算了安装包的体积结果编译到一半发现磁盘满了。UE4从源码编译Build目录、Intermediate缓存目录、引擎安装目录加一起轻轻松松占用60~80GB。再算上AirSim源码和示例项目预留100GB是最稳妥的。如果你手头的机器内存确实不够有个投机取巧的办法加一个swap交换文件。虽然编译速度会打折但至少不会中途崩。我自己在16GB机器上就是靠8GB swap撑过来的。创建swap的命令如下sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile要想永久生效还要把这行加到/etc/fstab/swapfile none swap sw 0 0另外要注意UE4的Linux版本英伟达驱动建议使用官方驱动源或者Ubuntu的专有驱动源。用开源驱动nouveau是跑不起来的编辑器能启动但是渲染性能极其拉胯AirSim里的相机图像也会异常。1.3 安装NVIDIA显卡驱动显卡驱动是整套环境的第一个门槛。Ubuntu安装完系统后默认用的是nouveau开源驱动必须先换到NVIDIA闭源驱动。最省事的方式是直接用Ubuntu软件源里的专有驱动以535版本为例sudo apt update sudo apt install nvidia-driver-535 sudo reboot重启之后打开终端验证nvidia-smi只要能看到类似下面的输出就说明驱动装好了----------------------------------------------------------------------------- | NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 | |--------------------------------------------------------------------------- | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Van Gogh System shared Memory | | | ---------------------------------------------------------------------------注意如果nvidia-smi提示 command not found先不要急着换驱动版本检查一下Secure Boot是否启用。很多机器在安装NVIDIA闭源驱动时会要求给驱动签名Secure Boot开启状态下签名不对驱动模块无法加载自然找不到命令。最简单的方式是在BIOS里关闭Secure Boot装完驱动再决定要不要开回来。还有一种情况就是你本身已经装了CUDA Toolkit里面自带驱动。这种情况下nvidia-smi理论上也是可用的但如果版本和内核不匹配UE4编译的时候可能会崩溃。建议穿梭到稳妥的方案先卸载旧驱动再装系统源里的驱动。sudo apt purge nvidia-* sudo apt autoremove sudo apt install nvidia-driver-535 sudo reboot另外装完驱动之后最好装一下后续UE4编译需要的Vulkan开发库和基础编译工具。Vulkan是UE4在Linux上的渲染后端之一AirSim的相机仿真也依赖Vulkan的算力支持。这些依赖一起装sudo apt install build-essential cmake git libgl1-mesa-dev libglu1-mesa-dev libvulkan-dev vulkan-utils libx11-dev libxrandr-dev libxi-dev libssl-dev libncurses5-dev装完之后可以用vulkaninfo --summary看一眼Vulkan能不能正常识别显卡。如果这一步报错后面UE4大概率也没法正常渲染。2. UE4源码获取与编译部署2.1 Epic账号授权与仓库拉取UE4的源码虽然开源但并不是直接公开挂在GitHub上的需要先关联Epic Games账号。如果你还没做过这一步流程是这样的到 Epic Games 官网注册一个账号就是平时用来登录联机游戏的Epic账号。在账号管理的「应用和账号」或「连接」里选择关联GitHub账号。关联成功后Epic官方会把你的GitHub账号加入UnrealEngine仓库的协作者列表然后你的GitHub就能看到EpicGames/UnrealEngine这个私有仓库了。这一步可以理解为“实名认证”本质是Epic要确认你同意了UE的许可协议。授权一般几分钟内生效有时候会慢最长不超过一天。授权完成后拉取源码。这里强烈建议直接拉编译好的4.27 LTS分支别拉最新master。原因有两个一是4.27是UE4的长期支持版本稳定性最好二是AirSim很多功能在4.27上测试得最充分。cd ~ git clone -b 4.27 https://github.com/EpicGames/UnrealEngine.git UnrealEngine_4.27注意这个仓库非常大大概1GB左右的元数据所以请确保网络稳定。下载完后可以看一眼有没有Engine/Source/Programs/UnrealBuildTool这个目录如果存在说明代码基本完整。心得拉UE4源码时不要用--depth 1做浅克隆虽然省空间但后续Setup.sh可能会需要完整历史记录获取一些子模块引用浅克隆容易翻车。2.2 安装编译依赖与初始化源码拉下来之后还不能直接编译。UE4在Linux平台有一堆系统依赖其中最关键的是代码生成工具和编译工具链。进入源码目录先执行初始化脚本cd ~/UnrealEngine_4.27 ./Setup.sh这个脚本会干三件事安装额外的Git依赖、下载预编译的二进制工具如clang编译器、ICU库等、校验依赖完整性。过程很快但期间需要联网下载如果网络质量不好会卡在某个文件反复重试。遇到这种情况不用慌重新执行一遍./Setup.sh它具备断点续传能力。注意UE4在Linux上强制要求使用自带的一套clang工具链而不是系统默认的gcc。这是因为UE4的代码生成工具与LLVM深度绑定用gcc会有各种ABI不兼容的问题。所以你在Setup.sh里看到它下载aarch64和x86_64的clang的时候不要觉得奇怪。Setup完成之后紧接着生成编译工程文件./GenerateProjectFiles.sh生成项目文件这一步其实是把UE4的源码组织成一套可供make理解的Makefile体系。执行完之后终端会出现一堆包含Engine路径的输出。如果你在这一步看到红色报错十有八九是缺了某个系统依赖。把上一节提到的libx11-dev、libxrandr-dev、libglu1-mesa-dev这些装全重新跑一遍脚本就好。2.3 生成工程文件并开始编译编译是整个环境搭建中最耗时的一步。打开终端进入源码目录执行cd ~/UnrealEngine_4.27 make -j$(nproc)-j$(nproc)表示使用机器的全部核心进行并行编译。8核16线程的CPU大概需要1.5到2.5个小时16核以上会快一些但也会受散热和内存带宽影响。如果内存只有16GB建议把并发数调低一点比如make -j4这样编译速度会慢但不容易因为内存不足被系统杀掉。你可以在另一个终端用htop时刻关注内存占用一旦看到内存接近上限就马上CtrlC手动停掉改用更低的并发数。编译完成之后验证引擎是否可用cd ~/UnrealEngine_4.27/Engine/Binaries/Linux/ ./UE4Editor --version如果能输出版本信息说明引擎本体编译成功。还有一个更直观的验证方式用引擎工程文件生成工具测试一下cd ~/UnrealEngine_4.27/Engine/Binaries/Linux/ ./UnrealEditor正常情况下会启动UE4启动器虽然还没有任何项目但能走到这儿说明引擎已经能正常工作了。第一次启动会加载很多shader编译任务界面可能卡一会儿这是正常的不是在死机。3. AirSim插件编译与UE4项目集成3.1 拉取AirSim源码与依赖构建到了这一节你的UE4引擎应该已经编译好并且能启动了。接下来开始搞AirSim。AirSim虽然名字上是个“模拟器”但它本身不是一个独立的可执行程序而是一个C库加一个UE4插件。下载源码cd ~ git clone https://github.com/microsoft/AirSim.git cd AirSimAirSim的master分支通常和UE4 4.27兼容良好。不过如果你担心版本差异也可以切到发布标签git checkout v1.8.1心得AirSim v1.8.1是我在Ubuntu 20.04 UE4.27组合下用得最稳的一个版本后面的v1.8.x虽然在继续更新但偶尔会有编译器告警和一些小问题如果你的目标是稳定跑通不要盲目追新。拉完代码后运行AirSim的初始化脚本./setup.sh这个脚本会安装Python库、下载一些基础依赖并检查编译环境。接着执行./build.sh这里要解释一下build.sh在干嘛。它会编译AirSim的核心库AirLibAirLib是独立于UE4的一套C库包含无人机动力学模型、电机模型、传感器模型等。编译完成之后会在AirSim/AirLib目录下生成编译产物同时在AirSim/output目录生成一个名为AirSim的可执行单元测试程序。如果你只想要Python API不打算在UE4里跑画面执行到这一步其实已经够了。但绝大多数人需要的是可视化仿真所以必须继续编译UE4插件。3.2 编译UE4版AirSim插件AirSim的UE4插件源码位于AirSim/Unreal/Plugins目录。编译这个插件需要指定UE4引擎的路径。在AirSim的Unreal插件目录下执行cd ~/AirSim/Unreal/Plugins ./build.sh --ue4-engine~/UnrealEngine_4.27--ue4-engine参数指向你编译好的UE4引擎根目录。这个脚本会调用UE4的UnrealBuildTool将AirSim插件编译成.so文件。编译过程通常会报一些GCC/Clang的告警但只要最终能看到Build succeeded或者OK字样就不用管。编译成功后插件文件就待在AirSim/Unreal/Plugins/AirSim目录里。这个目录包含了插件的源文件、配置文件和编译出的二进制。后面我们要把它挂到UE4项目里。3.3 创建UE4项目并挂载插件AirSim官方为我们准备了一个叫Blocks的示例环境它是一个已经预置了地形、建筑、街道的仿真场景非常适合第一次跑通AirSim。官方示例项目在AirSim/Unreal/Environments/Blocks目录下。在挂载插件之前要先把这个示例项目里的.uproject文件所在目录和UE4关联起来方法有两种方法一推荐直接用UE4编辑器打开示例工程。进入示例项目目录更新工程文件如果你是第一次从Git拉下AirSim示例工程里的中间文件可能不完整cd ~/AirSim/Unreal/Environments/Blocks ./UpdateProjectFiles.sh这个脚本会自动生成Blocks.sln工程文件并把AirSim插件链接到UE4引擎。脚本运行完后用编辑器打开~/UnrealEngine_4.27/Engine/Binaries/Linux/UE4Editor ~/AirSim/Unreal/Environments/Blocks/Blocks.uproject首次打开会弹出一个提示框问是否重建缺失的模块选择“是”。引擎会编译Blocks项目的C代码和AirSim插件编译通过后进入编辑器界面。方法二自建项目手动挂载AirSim插件。如果你不想用官方示例可以先用UE4编辑器新建一个C项目选择“Blank”模板然后把AirSim插件目录复制到项目的Plugins/AirSim路径下再在编辑器中启用插件。步骤稍多但对理解插件机制有帮助。我个人的建议是第一次跑直接用Blocks示例项目。等你明白了整个插件挂载逻辑再考虑自建项目或导入自己做的地图。4. 环境验证与仿真实测4.1 启动编辑器并加载AirSim场景接上一节双击打开Blocks.uproject后UE4编辑器应该能正常进入关卡编辑器。你在左侧的场景面板里能看到一个名为PlayerStart的角色起点以及一个AirSimGlobal的Actor。后者就是AirSim插件的运行时入口。如果场景里没有AirSimGlobal手动从左侧面板的“Place Actors”面板搜索“AirSim”拖拽到场景中也可以。进入编辑器后建议先不做任何修改直接点工具栏上的“Play”按钮测试。第一次Play会经历一段“Compile Shaders”的过程这个过程视显卡性能而定大概几秒到半分钟。等待时会出画面锯齿或者黑屏不用管。等画面正式出来你看到的应该是一个第三视角或第一视角的无人机背景是一片方块建筑场景。AirSim默认激活的是无人机模式所以场景里会有一架多旋翼无人机。如果啥都没有大概率是AirSim插件没有正确加载检查编辑器左下角的输出日志里有没有类似 “AirSim plugin loaded” 的字样。4.2 运行无人机仿真并验证传感器无人机起飞之前需要先把控制模式搞清楚。AirSim在无人机的键盘控制中默认使用“游戏手柄模式”键盘上的映射规则如下按键操作W / A / S / D前后左右平移方向键俯仰和横滚左Shift / 左Ctrl上升 / 下降空格悬停/停止F1打开控制帮助窗口先在场景里按一下空格让无人机进入可控状态然后按左Shift让无人机起飞到两米左右高度再用WASD控制它在场景里飞行。如果无人机能正常响应指令说明AirSim的动力学模型和UE4渲染引擎已经打通了。除了无人机本身AirSim的传感器数据也可以直接在Python里获取。打开另一个终端进入AirSim的Python例子目录cd ~/AirSim/PythonClient/multirotor pip install airsim python hello_drone.py如果终端输出起飞、移动、降落的过程同时UE4里的无人机也跟着动作那就说明环境搭建完全成功。这套Python API是后续做视觉导航、目标检测、强化学习算法的重要入口很多人就是冲着这个API来搭环境的。4.3 高频问题与排查实录虽然我把顺利的路径写完了但实操中99%的人会遇到下面这些问题。下面是我自己在多次搭建中总结出来的排查清单建议收藏。问题现象可能原因解决办法nvidia-smi不存在驱动未正确加载确认Secure Boot关闭重装驱动并重启UE4编译时报LLVM/Clang相关错误系统没有安装UE4指定的clang重新执行Setup.sh它会自动下载匹配的clangSetup.sh卡住不动网络不稳定多执行几次脚本支持断点续传make过程中被OOM杀掉内存不足加swap或用make -j4降低并行度AirSim build.sh报找不到UE4路径参数没传对确认--ue4-engine/绝对路径指向引擎根目录UE4编辑器打开项目提示插件不兼容UE4版本与AirSim不匹配统一使用UE4.27 AirSim v1.8.1Play之后场景全黑shader还在编译等待着色器编译完成或降低画面质量无人机不受键盘控制没先按空格激活先按空格键让无人机进入控制状态画面帧率极低显卡驱动没装好或Vulkan不可用用vulkaninfo --summary检查重装驱动AirSim Python API连接超时仿真器没有启动或端口被占用确保UE4里正在Play且RpcPort没被修改注意我见过最离谱的一个问题是有人把UE4源码和AirSim装在了NTFS或FAT32挂载的磁盘分区上导致编译时文件锁失效各种“Permission denied”和“No such file or directory”。Linux下的UE4编译请务必把源码放在ext4或者其他Linux原生文件系统分区里不要图方便放在双系统共享的数据盘上。还有一个小细节AirSim默认的仿真端口是41451如果本机有其他程序占用了这个端口也会导致Python API连不上。检查端口占用netstat -tulpn | grep 41451如果被占用就要改AirSim的settings.json或者结束占用进程。4.4 针对Ubuntu 20.04环境的扩展与后续规划环境跑通之后你会发现这套组合的潜力远不止“让无人机飞起来”。我自己实际用下来的经验是AirSim UE4 非常适合做这几类事情视觉算法开发直接调用AirSim的RGB相机、深度相机、分割相机API批量生成带标签的训练数据。强化学习用Python控制无人机在场景里反复尝试飞行配合AirSim提供的碰撞检测和奖励反馈训练端到端策略。多机协同在一个场景里初始化多架无人机测试避碰算法和编队算法。与ROS集成很多人会在同一台机器上装好ROS Noetic然后写一个ROS节点桥接AirSim的传感器数据让运行在ROS里的导航算法直接在AirSim世界里跑。如果你是做SLAM研究的AirSim的深度相机和IMU数据比很多平面仿真器真实得多能省掉不少外设标定的时间。5. 写在最后的一些建议最后分享几个我自己在实际操作中的体会吧。第一这个环境搭建最核心的耐心考验点在UE4编译和shader预热这两步都极其考验机器性能但熬过去之后一切都会顺畅起来。我见过很多人在第一步就放弃其实没必要按照本文的顺序每完成一个节点就验证一次很快就能定位到具体问题。第二尽可能保持软件版本的一致性。Ubuntu 20.04、UE4.27、AirSim v1.8.1这一套组合是我反复踩坑后确定的稳定搭配。如果你自己乱换版本比如用UE5去装AirSim的旧插件或者用Ubuntu 22.04去编译老版本UE4大概率会遇到一堆莫名其妙的兼容性问题而且网上解决案例少排查成本极高。第三环境搭好之后记得对你的settings.json做一次个性化配置。文件位置在~/Documents/AirSim/settings.json你可以通过它设置无人机的最大飞行速度、改变传感器参数、设置天气模式等。比如想让无人机飞得稳一点可以把SettingsJson里的DefaultVehicleConfig换成SimpleFlight模式这个模式的动力学更稳定调试算法时不容易因为飞机飘而干扰判断。把环境里的每一环都当成独立的子系统去理解而不是黑盒才是长期使用的正确心态。祝大家都能顺利跑通自己的第一个AirSim仿真。
