Ubuntu 20.04 下 AirSim 与 Unreal Engine 4 仿真环境全流程搭建指南

1. 项目概述与核心价值最近在折腾无人机和自动驾驶的仿真项目发现微软开源的AirSim真是个宝藏。它本质上是一个基于虚幻引擎Unreal Engine的仿真平台能让你在高度逼真的虚拟环境里测试和训练你的算法模型无论是无人机飞控、自动驾驶的感知决策还是机器人路径规划都能找到用武之地。不过好东西的门槛通常也不低尤其是在Linux系统下要把AirSim和它依赖的Unreal Engine 4UE4环境给配通绝对是个技术活堪称“从入门到放弃”的经典劝退场景。我这次的目标是在Ubuntu 20.04 LTS这个相对稳定和流行的发行版上完成从零开始的全套环境搭建。这不仅仅是把几个软件装上就完事了它涉及到NVIDIA显卡驱动的正确安装、UE4庞大源码的编译、AirSim插件的集成以及最终一个可运行仿真场景的部署。整个过程环环相扣任何一个环节出错都可能导致前功尽弃。网上虽然有不少教程但要么年代久远要么步骤跳跃对于新手或者不熟悉Linux编译生态的朋友来说照着做很容易卡在某个莫名其妙的错误上。所以我决定结合自己最近在实验室服务器和本地工作站上反复折腾的经验写一份尽可能详尽、可复现的“保姆级”攻略。这份攻略的价值在于它不仅告诉你每一步该输入什么命令更会解释清楚每一步背后的逻辑和可能遇到的“坑”。比如为什么一定要用特定版本的驱动编译UE4时内存不足怎么办AirSim构建失败最常见的几个原因是什么我希望你跟着走完一遍后不仅能成功跑起仿真更能理解这套复杂系统是如何被组装起来的以后遇到问题也能自己排查。2. 环境准备与核心依赖解析在动手敲命令之前我们必须把“地基”打牢。这个地基就是Ubuntu 20.04操作系统本身以及一系列必须的底层依赖。很多人环境配置失败问题往往就出在这一步的疏忽上。2.1 系统更新与基础工具链安装首先确保你的系统是最新的。打开终端执行以下命令sudo apt update sudo apt upgrade -y这不仅仅是更新软件包列表upgrade操作会升级所有已安装的包到最新版本能修复很多已知的系统级bug为后续编译提供一个更稳定的基础。接下来安装编译UE4和AirSim所必需的基础开发工具和库。这是一组庞大的软件包但请务必一次性安装完成sudo apt install -y build-essential software-properties-common cmake git wget curl zip unzip tar pkg-config \ libglu1-mesa-dev libgl1-mesa-dev libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev \ libudev-dev libwayland-dev wayland-protocols libxkbcommon-dev libdbus-1-dev \ zlib1g-dev libgmp-dev libmpfr-dev libmpc-dev libssl-dev \ python3 python3-dev python3-pip python3-setuptools我来解释一下其中几个关键包的作用build-essential: 包含了GCC、G、make等最核心的编译工具链没有它什么都编译不了。cmake: 现代C项目的事实标准构建工具UE4和AirSim都重度依赖它。libglu1-mesa-dev等以-dev结尾的包这些是OpenGL、X11窗口系统等图形和输入相关的开发库。UE4编辑器是一个图形化应用程序缺少这些库会导致编译成功但编辑器无法启动或者运行时黑屏、崩溃。python3及相关包UE4的构建脚本和部分工具链是用Python写的虽然我们主要用C但Python环境是必需的。注意安装过程中如果遇到提示“无法定位软件包”可能是你的软件源配置问题。可以尝试更换为阿里云或清华的镜像源然后再执行sudo apt update。2.2 NVIDIA显卡驱动安装避坑指南这是整个环境配置中最关键、也最容易出问题的一步。AirSim和UE4都需要GPU进行图形渲染和物理计算没有正确的驱动一切都无从谈起。Ubuntu系统自带的nouveau开源驱动性能不足且兼容性差必须替换为官方的NVIDIA闭源驱动。为什么不推荐使用ubuntu-drivers自动安装很多教程会教你sudo ubuntu-drivers autoinstall。这个方法在桌面版Ubuntu上有时能成功但在无图形界面的服务器版或者某些特定型号的显卡上极易导致系统启动后黑屏、卡在登录循环。其根本原因是自动安装的驱动版本可能与你的内核或显卡型号不完全匹配或者与已有的图形服务器如Xorg或Wayland产生冲突。推荐的手动安装方法我强烈建议从NVIDIA官网下载对应你显卡型号的驱动进行手动安装过程更可控。禁用nouveau驱动sudo bash -c echo blacklist nouveau /etc/modprobe.d/blacklist-nvidia-nouveau.conf sudo bash -c echo options nouveau modeset0 /etc/modprobe.d/blacklist-nvidia-nouveau.conf更新initramfs并重启sudo update-initramfs -u sudo reboot重启后进入纯命令行模式。如果你使用的是带有图形界面的Ubuntu在登录界面按CtrlAltF3F1到F6通常都可以切换到TTY命令行终端登录。关闭图形显示服务如果是服务器版可跳过sudo systemctl stop gdm3 # 或者如果你用的是lightdm # sudo systemctl stop lightdm下载驱动。去NVIDIA官网https://www.nvidia.com/Download/index.aspx根据你的显卡型号和系统选择驱动。对于Ubuntu 20.04通常选择Linux 64-bit版本。假设你下载的文件是NVIDIA-Linux-x86_64-xxx.xx.run将其放在~/Downloads目录下。安装驱动cd ~/Downloads chmod x NVIDIA-Linux-x86_64-xxx.xx.run sudo ./NVIDIA-Linux-x86_64-xxx.xx.run在安装过程中可能会提示“The distribution-provided pre-install script failed...” - 选择Continue。“Would you like to register the kernel module sources with DKMS?” - 建议选择Yes这样未来内核更新后驱动能通过DKMS自动重新编译。“Install NVIDIAs 32-bit compatibility libraries?” - 选择Yes。其他选项保持默认即可。安装完成后重启系统sudo reboot。验证安装重启后在终端输入nvidia-smi。如果能看到显卡型号、驱动版本、CUDA版本如果驱动包内含以及GPU使用情况表格那么恭喜你驱动安装成功了。这是通往成功的第一步也是最坚实的一步。实操心得在服务器上安装时如果重启后网络连接丢失SSH连不上很可能是驱动影响了网络接口。此时需要接上显示器和键盘进入系统后检查网络配置或尝试回滚驱动。对于Tesla系列的计算卡可能需要从NVIDIA数据中心驱动页面下载专门的驱动版本。3. Unreal Engine 4 源码编译UE4不是通过apt安装的普通软件我们需要从Epic Games的GitHub仓库拉取源码然后进行本地编译。这个过程非常消耗时间和系统资源尤其是内存和磁盘空间请确保你有至少50GB的可用磁盘空间和16GB以上的物理内存32GB或以上为佳。3.1 获取UE4源码首先你需要访问 https://github.com/EpicGames/UnrealEngine 并关联你的Epic Games账户需要先注册。关联后才能克隆仓库。在终端中切换到你打算存放UE4的目录例如~/Developmentcd ~ mkdir -p Development cd Development克隆仓库。注意不要直接克隆主分支主分支是最新的开发版可能不稳定。我们应该克隆一个长期支持LTS或稳定的发布版本分支。UE 4.27.2 是一个被AirSim广泛测试和兼容的稳定版本。git clone --depth 1 --branch 4.27.2-release https://github.com/EpicGames/UnrealEngine.git cd UnrealEngine--depth 1参数表示只克隆最近的一次提交可以极大减少下载数据量加快速度。3.2 运行依赖安装脚本UE4提供了一个方便的脚本来安装所有额外的依赖项./Setup.sh这个脚本会下载并安装编译所需的特定版本的工具链如 .NET Core、特定版本的Clang等。它会检查你的系统环境并提示缺失的包。根据提示你可能还需要补充安装一些包通常脚本会给出明确的apt install命令照做即可。3.3 编译UE4引擎这是最耗时的一步可能需要数小时取决于你的CPU核心数和性能。./GenerateProjectFiles.sh make./GenerateProjectFiles.sh: 这个脚本会调用UE4自带的构建系统UnrealBuildTool来生成用于make的Makefile。make: 开始真正的编译过程。你可以使用make -j$(nproc)来启用并行编译充分利用所有CPU核心显著缩短时间。注意事项内存不足问题编译UE4极其消耗内存。如果内存不足例如在只有8GB内存的机器上编译进程可能会被系统杀死出现Killed或Segmentation fault。如果遇到这种情况尝试不使用-j参数或者使用make -j2或make -j4减少并行任务数。最根本的解决办法是增加物理内存或创建足够大的交换空间swap。磁盘空间编译过程中会产生大量中间文件确保/tmp分区也有足够空间至少10GB。整个UE4目录编译完成后可能会超过70GB。耐心等待编译过程会输出大量日志只要没有红色的错误Error信息就让它安心运行。你可以去喝杯咖啡或者处理其他事情。编译成功后你会在目录下看到Engine/Binaries/Linux文件夹里面包含了UnrealEditor等可执行文件。为了后续方便可以创建一个软链接或将其路径加入环境变量PATH中echo export UE4_ROOT~/Development/UnrealEngine ~/.bashrc echo export PATH$UE4_ROOT/Engine/Binaries/Linux:$PATH ~/.bashrc source ~/.bashrc现在尝试在终端输入UnrealEditor如果UE4编辑器能够成功启动那么最艰难的一部分就已经完成了。4. AirSim 插件编译与集成有了可用的UE4引擎接下来我们就可以将AirSim作为插件集成到UE4项目中。AirSim提供了两种使用方式1) 作为插件集成到你自己创建的UE4项目中2) 使用AirSim官方预配置好的示例项目。对于初学者强烈推荐第二种方式因为它省去了很多配置的麻烦。4.1 克隆与准备AirSim源码首先将AirSim的源码克隆到本地。我们同样选择一个稳定的发布版本例如v1.8.1。cd ~/Development git clone --branch v1.8.1 https://github.com/microsoft/AirSim.git cd AirSimAirSim的编译依赖于一个更现代的C构建环境。它使用cmake进行构建并且推荐使用clang编译器。我们需要先安装一些额外的依赖并设置编译环境./setup.sh这个脚本会安装clang-10,llvm-10,libc等必要的工具链。如果脚本执行报错可以尝试手动安装sudo apt install -y clang-10 llvm-10 libc-10-dev libcabi-10-dev4.2 编译AirSim插件AirSim的编译分为两步首先编译它依赖的rpclib一个RPC库然后编译AirSim插件本身。更新子模块并构建依赖git submodule update --init --recursive这步会拉取rpclib等子模块代码。创建构建目录并编译mkdir build cd build cmake .. -DCMAKE_C_COMPILERclang-10 -DCMAKE_CXX_COMPILERclang-10 make -j$(nproc)这里明确指定使用clang-10系列编译器是为了确保与UE4的兼容性避免使用系统默认的GCC可能带来的ABI应用二进制接口不兼容问题。cmake命令会配置生成Makefile。make命令开始编译。这个过程比编译UE4快得多通常几分钟就能完成。编译成功后你会在build目录下的output文件夹或类似位置找到生成的AirSim.soLinux下的动态链接库等文件。但更重要的是AirSim的构建系统会自动将这些编译好的插件文件复制到正确的位置。4.3 集成到UE4示例项目AirSim仓库里自带了一个配置好的UE4示例项目位于Unreal/Environments目录下。我们需要将这个项目“嫁接”到我们刚才编译好的UE4引擎上。复制插件AirSim的构建脚本通常已经帮你做了这件事。检查~/Development/AirSim/Unreal/Plugins目录下是否有AirSim文件夹。如果没有你需要手动将编译好的插件内容复制过去或者重新运行cmake和make时确保安装了插件。准备示例项目以Blocks环境为例这是一个简单的方块世界适合快速测试。cd ~/Development cp -r AirSim/Unreal/Environments/Blocks ./MyAirSimProject cd MyAirSimProject现在MyAirSimProject目录下应该有Blocks.uproject文件和一个Plugins文件夹里面应该已经包含了指向AirSim插件的符号链接或实际文件。生成项目文件为了让UE4引擎识别这个项目我们需要为其生成IDE项目文件虽然我们可能不用IDE但这一步是必须的。$UE4_ROOT/Engine/Binaries/Linux/UnrealBuildTool -projectfiles -project$(pwd)/Blocks.uproject -game -engine这个命令会调用UE4的构建工具扫描项目目录和插件生成必要的.slnVisual Studio或.xcodeprojXcode文件在Linux下主要是生成Makefile所需的文件。5. 运行与测试你的第一个仿真所有艰苦的编译工作完成后终于到了激动人心的运行时刻。5.1 启动UE4编辑器并打开项目有两种方式可以打开项目命令行启动这是最直接的方式尤其适合在无图形界面的服务器上通过X11转发运行。cd ~/Development/MyAirSimProject $UE4_ROOT/Engine/Binaries/Linux/UnrealEditor Blocks.uproject图形界面启动如果你在Ubuntu桌面环境下也可以直接双击Blocks.uproject文件系统可能会提示你选择使用哪个UE4版本选择我们编译的版本路径即可。首次打开项目时UE4编辑器会进行着色器编译Shader Compilation。这个过程会将项目用到的所有材质转换为你的GPU可以执行的代码可能会花费几分钟到十几分钟期间编辑器可能会暂时无响应这是正常的请耐心等待进度条走完。5.2 启动仿真与连接AirSim客户端当UE4编辑器完全加载Blocks场景后你看到一个由彩色方块构成的世界。点击编辑器左上角的“播放”Play按钮场景开始运行。现在仿真环境服务器端已经就绪。我们需要一个客户端Client来与之通信发送控制指令并接收数据。AirSim提供了Python、C等多种语言的客户端API。我们用最方便的Python来测试。安装AirSim Python客户端库pip3 install msgpack-rpc-python pip3 install airsim注意这里安装的airsim是一个轻量级的Python包只包含客户端API不是我们刚才编译的庞大插件。编写一个简单的测试脚本。在你的项目目录或其他地方创建一个test_airsim.py文件import airsim import time # 连接到本地运行的AirSim仿真器 client airsim.MultirotorClient() client.confirmConnection() # 解锁无人机让其可以接受指令 client.enableApiControl(True) client.armDisarm(True) print(Taking off...) client.takeoffAsync().join() # 起飞 time.sleep(2) # 悬停2秒 print(Moving forward 5 meters...) client.moveToPositionAsync(5, 0, -3, 2).join() # 向前飞5米高度-3米AirSim中Z轴向下为负速度2m/s time.sleep(2) print(Landing...) client.landAsync().join() # 降落 time.sleep(2) # 锁定并断开API控制 client.armDisarm(False) client.enableApiControl(False) print(Test completed!)运行测试脚本确保UE4编辑器仍在运行Blocks场景并处于“播放”模式。然后在终端运行python3 test_airsim.py如果一切配置正确你将看到UE4编辑器中的无人机默认在场景中心生成自动起飞、向前飞行一段距离然后降落。同时终端会打印出相应的状态信息。至此你已经成功地在Ubuntu 20.04上搭建了完整的AirSim UE4仿真环境并完成了第一次自动化飞行测试6. 常见问题与深度排查实录即使按照攻略一步步操作由于硬件、网络、系统状态的差异你仍然可能会遇到一些问题。下面是我在多次配置中遇到的典型问题及其解决方案。6.1 UE4编译失败相关问题问题1编译过程中出现virtual memory exhausted: Cannot allocate memory或进程被Killed。原因这是典型的内存不足OOM。UE4编译某些模块如ShaderCompiler时内存需求极大。解决方案增加交换空间这是最有效的临时解决方案。# 创建一个8GB的交换文件 sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 永久生效编辑 /etc/fstab添加一行/swapfile none swap sw 0 0减少并行编译任务不使用-j$(nproc)改用make -j2或直接make进行单线程编译速度慢但内存需求低。终极方案增加物理内存。对于UE4开发32GB是起步推荐配置。问题2./Setup.sh或./GenerateProjectFiles.sh失败提示找不到.NET或mono。原因UE4的构建系统需要.NET框架或Mono来运行一些C#工具。解决方案脚本应该会自动处理。如果失败可以尝试手动安装Monosudo apt install -y mono-devel mono-complete然后重新运行脚本。6.2 AirSim编译与连接问题问题1编译AirSim时cmake步骤报错提示找不到UE4路径。原因AirSim的CMakeLists.txt需要知道UE4的安装位置来链接正确的库。解决方案设置环境变量UE4_ROOT。确保你已经按照前面步骤将export UE4_ROOT~/Development/UnrealEngine添加到了~/.bashrc并执行了source ~/.bashrc。然后在一个新的终端窗口中重新进行cmake和make。问题2成功编译并运行UE4项目但Python客户端连接超时 (airsim.exceptions.TimeoutError)。原因AirSim的RPC服务器默认监听本地回环地址127.0.0.1的41451端口。连接失败可能因为UE4项目未处于“播放”模式。防火墙阻止了连接。客户端代码中指定的IP地址或端口不对。排查步骤确认UE4编辑器正在运行并且你点击了“播放”按钮进入了仿真模式。编辑器窗口左下角应显示“Playing”。检查端口是否监听在终端运行netstat -tulpn | grep 41451应该能看到一个airsim相关的进程在监听。在Python连接代码中尝试显式指定主机和端口client airsim.MultirotorClient(ip127.0.0.1, port41451)如果是远程连接客户端和UE4运行在不同机器需要确保UE4启动时允许远程连接默认允许并且客户端代码中的IP地址要改为UE4所在机器的IP同时确保网络互通且防火墙放行了41451端口。问题3无人机在场景中不动或者控制指令无响应。原因最常见的原因是API控制未启用或者无人机未解锁armed。解决方案确保你的客户端代码中在发送移动指令前正确调用了client.enableApiControl(True)和client.armDisarm(True)。顺序很重要必须先启用API控制才能解锁。6.3 性能与渲染问题问题UE4编辑器或仿真运行时非常卡顿帧率很低。原因驱动问题虽然nvidia-smi显示驱动已安装但可能没有在正确使用GPU进行渲染。运行glxinfo | grep renderer如果输出是llvmpipe等软件渲染器说明OpenGL渲染未使用NVIDIA驱动。UE4设置问题编辑器默认设置可能未优化。场景复杂度高一些官方示例场景如LandscapeMountains非常消耗资源。解决方案对于驱动问题确保你按照指南禁用了nouveau并且安装了正确的驱动。对于双显卡笔记本可能需要使用prime-select选择NVIDIA显卡作为主显卡。在UE4编辑器的“编辑” - “项目设置”中搜索“RHI”将“默认后端”从Default改为Vulkan或DirectX 12如果可用有时能获得更好的Linux性能。不过AirSim对Vulkan的支持可能需要额外测试。在编辑器“播放”旁边的下拉菜单中将“游戏模式”的视口分辨率调低如1280x720并关闭“特效”等不必要的后期处理。对于测试优先使用简单的Blocks环境而不是复杂的大型场景。7. 场景部署与自定义环境进阶成功运行官方示例只是第一步。AirSim的真正威力在于你可以将其集成到自己的UE4项目中或者修改现有场景来满足特定的仿真需求。7.1 将AirSim集成到自定义UE4项目假设你已经有一个自己的UE4项目MyGame.uproject你想在其中加入无人机仿真功能。复制插件将编译好的AirSim插件即~/Development/AirSim/Unreal/Plugins/AirSim整个文件夹复制到你项目的Plugins目录下。如果Plugins目录不存在就创建一个。cd ~/Development/MyGame mkdir -p Plugins cp -r ~/Development/AirSim/Unreal/Plugins/AirSim ./Plugins/生成项目文件和之前一样需要为你的项目重新生成项目文件让UE4识别新插件。$UE4_ROOT/Engine/Binaries/Linux/UnrealBuildTool -projectfiles -project$(pwd)/MyGame.uproject -game -engine打开项目并启用插件用UE4编辑器打开你的MyGame.uproject。首次打开可能会提示“重新编译模块”点击确认。然后在编辑器菜单栏选择“编辑” - “插件”在搜索框输入“AirSim”确保“AirSim”和“AirSim HUD”插件已被勾选启用。重启编辑器。配置仿真演员在你的游戏关卡中你需要放置一个“AirSim游戏模式”和“无人机或汽车演员”。最简单的方法是从Blocks项目中借鉴打开Blocks地图查看“世界场景设置”World Settings看看“游戏模式重载”是如何设置的以及场景中放置了哪些AirSim特有的蓝图如BP_FlyingPawn。将这些元素复制或借鉴到你的项目中。7.2 修改与创建仿真环境UE4编辑器本身就是一个强大的3D场景创作工具。你可以修改现有地图在Blocks地图中你可以随意添加、删除、移动静态网格体Static Mesh改变地形调整光照。这些修改会直接影响仿真的感知输入相机看到的画面。创建全新地图你可以从零开始创建一个符合你需求的环境比如一个室内仓库、一个城市街道、或者一片特定的农田。将AirSim插件集成到这个新项目中即可。配置传感器AirSim的强大之处在于其可配置的传感器套件。你可以在项目的设置文件如settings.json中详细配置相机位置、视角、分辨率、噪声类型、激光雷达、IMU、GPS等传感器的参数以模拟真实世界的传感器特性。7.3 使用设置文件进行高级配置AirSim的行为可以通过一个名为settings.json的配置文件进行精细控制。这个文件通常放在你的项目可执行文件或Documents/AirSim目录下。一个基础的settings.json示例如下用于配置多旋翼无人机和一台相机{ SettingsVersion: 1.2, SimMode: Multirotor, Vehicles: { Drone1: { VehicleType: SimpleFlight, X: 0, Y: 0, Z: 0, Sensors: { camera_front: { SensorType: 2, Enabled: true, CaptureSettings: [ { Width: 640, Height: 480, FOV_Degrees: 90 } ] } } } } }通过这个文件你可以定义多个载具、初始位置、使用的物理模型如SimpleFlight是简化动力学PX4则通过MavLink连接更真实的飞控软件、以及每个载具上搭载的传感器列表及其参数。掌握settings.json的配置是进行高级仿真的关键。整个配置过程虽然步骤繁多但每一步都有其明确的目的。从驱动到引擎再到插件和项目本质上是在搭建一个分层的软件栈。驱动为硬件提供接口UE4引擎提供了世界渲染和物理模拟的基石AirSim插件则在此之上抽象出了机器人仿真的通用模型和通信接口。理解了这个层次结构当出现问题时你就能更准确地定位故障发生在哪一层是驱动兼容性、引擎编译问题、插件链接错误还是项目配置不当。这份攻略希望能为你扫清入门的主要障碍剩下的就是在逼真的虚拟天空和大地中尽情探索和验证你的算法了。