1. 项目概述与核心价值最近在折腾基于AirSim的无人机仿真研究环境搭建这一步就卡住了不少人。Ubuntu 20.04 LTS作为长期支持版本是很多实验室和开发者的首选系统但在上面部署AirSim尤其是要编译Unreal Engine 4UE4堪称一场“渡劫”。从显卡驱动的版本兼容性到UE4源码编译时动辄上百G的磁盘空间和数小时的等待再到AirSim插件编译中各种依赖库的缺失和版本冲突每一步都可能让你从入门到放弃。我花了将近一周时间反复重装系统、编译、排错才最终把整个环境跑通。这篇文章就是把我踩过的所有坑、验证过的所有有效步骤以及背后的原理梳理出来目标是让你能按照这个指南一次性成功搭建AirSim仿真环境把宝贵的时间用在算法开发上而不是无休止的环境配置上。这个指南的核心价值在于“避坑”。网上能找到的官方或零散教程往往只告诉你“要做什么”但很少详细解释“为什么这么做”以及“做错了会怎样”。我会结合Ubuntu 20.04的系统特性、NVIDIA驱动与CUDA的版本耦合关系、UE4对系统组件的特定要求以及AirSim自身的编译机制把每一步操作背后的逻辑讲清楚。无论你是刚接触机器人仿真的研究生还是希望快速搭建测试环境的工程师这篇指南都能帮你绕过那些令人头疼的暗礁直达目的地。2. 环境搭建的整体思路与前置认知在动手之前我们必须对AirSim在Ubuntu下的运行架构有一个清晰的认知。AirSim不是一个独立的可执行文件它本质上是一个Unreal Engine插件。因此整个环境搭建分为三个层次且环环相扣顺序不能乱系统层确保Ubuntu 20.04系统本身的基础环境就绪重点是显卡驱动和基础开发工具链。显卡驱动不对后面的一切3D渲染都是空谈。引擎层获取并编译Unreal Engine 4的源代码。这是最耗时、最吃资源的一步。UE4官方并不提供Linux的二进制发行版我们必须从Epic Games的Git仓库拉取源码自行编译。这个过程对系统内存、磁盘空间、网络状况都有很高要求。插件层在编译好的UE4环境中编译并集成AirSim插件。这一步需要配置AirSim的依赖如rpclib并生成最终的UE4项目文件。整个流程的依赖关系是单向的系统层支撑引擎层引擎层支撑插件层。任何一个下层出现问题上层都无法正常工作。常见的失败案例比如虚幻编辑器能打开但场景一片黑多半是显卡驱动问题能编译UE4但编译AirSim时报链接错误多半是依赖库版本或路径问题。理解了这个层次关系在排查错误时就能有的放矢。注意强烈建议在一台干净的Ubuntu 20.04系统上开始。如果你已经尝试过多次并失败残留的配置文件、旧版本库可能会带来难以排查的干扰。备份好个人数据后重新安装系统往往是最高效的“重置”方式。2.1 硬件与系统准备要点你的硬件配置直接决定了编译体验和最终仿真性能。CPU与内存编译UE4是一个极度消耗CPU和内存的过程。官方建议至少6核CPU和32GB内存。实测在8核CPU、16GB内存的机器上编译过程会非常缓慢且可能因内存不足而失败。如果内存不足可以尝试创建一个足够大的swap交换分区例如32GB但这会显著降低编译速度因为频繁的磁盘IO。最理想的配置是12核以上CPU64GB内存这样编译过程会顺畅很多。磁盘空间这是另一个容易被低估的“杀手”。你需要为以下内容预留空间UE4源代码约8GB。编译过程中的中间文件约30GB。编译完成后的引擎约40GB。一个基础的UE4空项目约2GB。AirSim插件及依赖约1GB。因此为整个环境预留150GB以上的可用磁盘空间是安全的选择。最好使用SSD机械硬盘的编译速度会让你怀疑人生。显卡必须是NVIDIA显卡。AirSim的许多传感器仿真如深度图、语义分割依赖于CUDA进行GPU加速。AMD显卡在Linux下对UE4的支持非常有限几乎无法正常运行。请确认你的显卡型号如RTX 3060, RTX 4090等这将决定你安装的驱动版本。3. 系统层显卡驱动与基础环境搭建这是整个流程的基石也是最容易出问题的一步。我们的目标是在Ubuntu 20.04上安装一个与CUDA Toolkit兼容的、稳定的NVIDIA驱动。3.1 彻底清理旧驱动关键第一步如果你之前安装过NVIDIA驱动或者系统自带了nouveau开源驱动第一步必须是彻底清理。sudo apt purge *nvidia* *cuda* *cudnn* -y sudo apt autoremove -y sudo apt autoclean -y然后禁用系统自带的nouveau驱动它与NVIDIA专有驱动冲突。# 编辑黑名单配置文件 sudo nano /etc/modprobe.d/blacklist-nouveau.conf在文件中添加以下两行blacklist nouveau options nouveau modeset0保存退出后更新initramfs并重启。sudo update-initramfs -u sudo reboot重启后验证nouveau是否被禁用。执行lsmod | grep nouveau如果没有输出则表示禁用成功。3.2 选择合适的驱动安装方式Ubuntu下安装NVIDIA驱动主要有三种方式各有利弊使用ubuntu-drivers自动安装推荐给新手# 安装工具 sudo apt install ubuntu-drivers-common -y # 检测并推荐驱动 ubuntu-drivers devices # 安装推荐版本通常是带“recommended”标记的 sudo ubuntu-drivers autoinstall这种方式最简单安装的驱动版本通常与当前系统内核兼容性最好。但它安装的可能不是最新版本且对CUDA版本的支持可能不是最优的。使用PPA仓库安装较新版本sudo add-apt-repository ppa:graphics-drivers/ppa -y sudo apt update # 再次查看可用的驱动版本选择较新的例如nvidia-driver-535 ubuntu-drivers devices sudo apt install nvidia-driver-535 -y这种方式可以安装比官方仓库更新的驱动是平衡了新特性和稳定性的选择。从NVIDIA官网下载.run文件手动安装最灵活但最复杂 你需要去NVIDIA官网根据显卡型号和系统下载对应的驱动文件如NVIDIA-Linux-x86_64-550.90.07.run。这种方式可以安装任何你想要的版本但需要关闭图形界面进入tty模式且容易因与系统组件不匹配而导致安装失败或开机黑屏。除非你明确需要某个特定版本否则不推荐新手使用。我的选择与理由对于AirSim和UE4我推荐使用方式2PPA安装nvidia-driver-535。这是一个长期支持分支的版本在Ubuntu 20.04上非常稳定并且完美支持CUDA 11.x和12.x兼容性覆盖了大多数深度学习框架和AirSim的需求。驱动版本太旧可能缺少新显卡的功能支持太新则可能引入未知的稳定性问题。535是一个经过大量实践验证的“甜点”版本。安装完成后必须重启系统。sudo reboot3.3 验证驱动安装成功重启后通过以下命令验证# 查看驱动版本和显卡信息 nvidia-smi你应该看到一个表格显示了GPU型号、驱动版本、CUDA版本这里显示的是驱动内建的最高支持CUDA版本并非已安装的CUDA Toolkit、GPU利用率等信息。如果这个命令能正常输出恭喜你驱动安装成功了。# 查看当前正在使用的显卡渲染器确保不是LLVMpipe等软件渲染 glxinfo | grep “OpenGL renderer”输出应类似“NVIDIA GeForce RTX 4060 Ti/PCIe/SSE2”这表明3D渲染已由NVIDIA显卡硬件加速。4. 引擎层Unreal Engine 4源码编译这是耗时最长、资源消耗最大的部分。请确保你已完成第3步并且磁盘空间、内存充足。4.1 注册Epic Games账户并关联GitHub访问 Unreal Engine官网 注册一个Epic Games账户。在账户设置中关联你的GitHub账户。这是获取UE4源代码的必需步骤。4.2 安装编译依赖UE4编译需要一整套开发工具和库。Epic提供了一个安装脚本但我们需要先确保一些基础工具到位。# 安装Git和Python3系统可能已自带但确保版本 sudo apt install git python3 python3-pip -y # 安装编译所需的基础软件包 sudo apt install build-essential clang-11 lld-11 cmake ninja-build -y # 安装必要的库文件 sudo apt install libxinerama-dev libxcursor-dev libxrandr-dev libxss-dev libgl1-mesa-dev libfreetype6-dev libopenal-dev libsndfile-dev -y # 特别重要的库缺少会导致编译失败 sudo apt install libpng-dev libjpeg-dev libogg-dev libvorbis-dev libatlas-base-dev libboost-all-dev -y实操心得libboost-all-dev这个包尤其重要UE4的构建系统大量使用了Boost库。如果安装时提示找不到可以尝试sudo apt install libboost1.71-dev或对应版本。另外clang-11和lld-11是UE4在Linux上指定的编译器和链接器必须安装。4.3 获取UE4源代码我们不直接克隆主仓库而是使用Epic提供的“克隆工具”它能更好地管理这个巨大的仓库。# 创建一个专门的工作目录路径不要有中文或空格 mkdir -p ~/UnrealEngine cd ~/UnrealEngine # 从GitHub克隆UE4仓库使用你关联了Epic账户的GitHub账号 git clone https://github.com/EpicGames/UnrealEngine.git -b 4.27 cd UnrealEngine这里我们指定了-b 4.27分支。AirSim对UE4版本有要求4.27是一个被广泛支持且稳定的版本。请勿使用最新的5.x版本除非AirSim官方明确声明支持。4.4 运行安装脚本并开始编译# 运行安装脚本它会下载剩余的二进制依赖约数GB ./Setup.sh # 这个过程可能很长取决于你的网速。完成后生成项目文件 ./GenerateProjectFiles.sh # 最后开始编译UE4引擎本体。使用make命令-j参数指定并行编译的线程数通常设为CPU核心数 make -j $(nproc)这是最漫长的阶段在性能足够的机器上可能需要1-2小时在资源紧张的机器上可能需要6小时以上。你可以观察CPU使用率是否跑满来判断编译是否在正常进行。踩坑记录网络问题./Setup.sh需要从Epic的服务器下载大量文件国内网络环境可能很慢甚至失败。可以考虑使用网络代理工具或在夜间网络通畅时进行。内存不足编译过程中如果卡住终端提示“killed”通常是内存耗尽系统杀掉了编译进程。除了增加物理内存唯一办法就是增大swap空间并减少make -j的线程数例如改为make -j4但这会进一步延长编译时间。磁盘空间不足编译中途失败提示“No space left on device”。请务必在开始前确认磁盘空间大于150GB。特定编译错误如果遇到某个模块编译失败可以尝试先执行make ShaderCompileWorker然后再重新执行make -j $(nproc)。有时模块间的依赖需要按顺序编译。4.5 验证UE4编译成功编译完成后在~/UnrealEngine/Engine/Binaries/Linux/目录下会生成一个名为UnrealEditor的可执行文件。# 尝试运行虚幻编辑器 cd ~/UnrealEngine/Engine/Binaries/Linux/ ./UnrealEditor如果一切顺利你将看到Unreal Engine 4的编辑器启动界面。第一次启动会进行一些初始化设置完成后你就可以创建一个新项目了。请务必成功运行一次编辑器确保引擎本身是完好可用的然后再进行下一步。如果编辑器无法启动或闪退请根据错误信息回溯检查通常是驱动或依赖库的问题。5. 插件层AirSim编译与集成现在我们有了健康的UE4引擎可以开始安装AirSim这个“大脑”了。5.1 克隆与准备AirSim源码建议将AirSim克隆到独立目录而不是UE4引擎目录内。# 退出UE4目录回到用户主目录或你的工作区 cd ~ git clone https://github.com/microsoft/AirSim.git cd AirSimAirSim的版本需要与UE4版本匹配。克隆主分支通常对应最新的支持版本。为了与UE4 4.27匹配我们可以切到一个稳定的发布标签。# 查看与UE4.27兼容的标签例如v1.8.1 git tag | grep 1.8 # 切换到该标签 git checkout v1.8.15.2 安装AirSim的Python依赖并构建AirSim的构建过程由Python脚本驱动。# 安装构建所需的Python包 pip3 install msgpack-rpc-python numpy pandas airsim # 运行构建脚本它会自动检测UE4的安装路径 ./setup.sh这个setup.sh脚本会做几件事下载并编译AirSim的核心依赖库如rpclib一个RPC库。提示你输入已编译的UE4引擎的路径。你需要输入之前编译成功的UE4根目录例如/home/yourusername/UnrealEngine。在UE4引擎目录下创建插件符号链接并编译AirSim插件。注意如果setup.sh运行失败最常见的原因是rpclib编译出错。你可以尝试手动编译它cd AirSim ./setup.sh --skip-setup # 然后手动进入external/rpclib目录按照其README进行编译 # 或者使用系统包管理器安装如果版本合适 # sudo apt install librpc-dev5.3 创建并配置UE4项目AirSim插件需要嵌入到一个UE4项目中才能运行。启动UE4编辑器通过之前验证过的./UnrealEditor命令启动。创建新项目在启动器界面选择“游戏” - “空白”项目设置选择“C”必须选择一个合适的项目名称例如MyAirSimProject和保存路径不要放在UE4引擎目录或AirSim源码目录内然后点击“创建”。启用AirSim插件项目创建后在编辑器菜单栏点击“编辑” - “插件”。在插件搜索框中输入“AirSim”你应该能看到“AirSim Plugin”。勾选其旁边的“启用”复选框然后重启编辑器根据提示。设置项目为AirSim模式编辑器重启后在“内容浏览器”中右键点击空白处选择“新建文件夹”命名为Settings。在Settings文件夹内右键选择“新建” - “AirSim” - “Settings (json)”。这会创建一个名为settings.json的配置文件。编辑配置文件双击打开settings.json你可以配置仿真环境。一个最简单的能启动的配置如下{ “SeeDocsAt”: “https://github.com/Microsoft/AirSim/blob/master/docs/settings.md”, “SettingsVersion”: 1.2, “SimMode”: “Car” }这里将仿真模式设为“Car”。你也可以设为“Multirotor”来仿真无人机。更复杂的配置可以指定车辆/无人机型号、传感器套件、物理引擎参数等。5.4 运行仿真与Python客户端测试运行仿真在UE4编辑器中点击工具栏上的“播放”按钮。你应该能看到一个默认的空白场景以及一辆车或一架无人机取决于SimMode。使用Python API控制打开一个新的终端。# 进入你的AirSim源码目录下的Python客户端示例目录 cd ~/AirSim/PythonClient/car # 运行一个简单的测试脚本例如让车开动一下 python3 hello_car.py如果一切正常你应该能在UE4编辑器窗口中看到车辆根据Python脚本的指令做出响应如前进、转向。6. 常见问题与排查技巧实录即使按照步骤操作也可能会遇到各种问题。这里记录了我遇到的一些典型问题及解决方法。6.1 UE4编辑器启动崩溃或黑屏症状运行./UnrealEditor后程序崩溃或窗口黑屏无响应。排查检查驱动再次运行nvidia-smi确认驱动加载正常。尝试在终端中启动编辑器查看是否有具体的错误输出。检查OpenGL运行glxinfo | grep “OpenGL renderer”确认使用的是NVIDIA硬件渲染而不是“LLVMpipe”软件渲染。使用Vulkan后端尝试编辑~/.config/Epic/UnrealEngine/4.27/Engine/Config/Linux/LinuxEngine.ini在[/Script/LinuxTargetPlatform.LinuxTargetSettings]部分添加DefaultGraphicsRHIDefaultGraphicsRHI_Vulkan。但注意AirSim对Vulkan的支持可能不完善。禁用复合窗口管理器如果你使用的是Ubuntu默认的GNOME桌面可以尝试在启动编辑器前执行export SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR0。根本原因99%是显卡驱动或图形环境兼容性问题。6.2 AirSim插件编译失败症状运行./setup.sh时在编译rpclib或AirSim自身时出现编译错误如undefined reference。排查检查UE4路径确保setup.sh脚本提示输入路径时你输入的是绝对路径如/home/user/UnrealEngine并且该路径下确实有编译好的引擎。检查C编译器确保系统默认的g和clang版本符合要求。Ubuntu 20.04默认的gcc-9通常是没问题的。手动编译依赖如之前所述尝试跳过自动设置手动编译rpclib。进入AirSim/external/rpclib目录按照其CMakeLists.txt的指示进行编译安装。查看详细日志setup.sh脚本通常会在AirSim/build或AirSim/external/rpclib/build目录下生成CMakeCache.txt和Makefile查看编译终端输出的最后几行错误信息通常是解决问题的关键。6.3 Python客户端无法连接到仿真器症状运行Python示例脚本如hello_car.py时提示连接超时或拒绝连接。排查确认仿真器在运行UE4编辑器必须处于“播放”模式即仿真运行中。检查IP和端口默认情况下AirSim的RPC服务器运行在localhost:41451。确保Python脚本中连接的是正确的地址默认就是localhost。如果你修改了settings.json中的ApiServerPortPython脚本也需要相应修改。检查防火墙Ubuntu的防火墙ufw可能会阻止本地回环端口的通信但这种情况较少见。可以暂时禁用防火墙测试sudo ufw disable测试后记得启用。使用更简单的测试尝试运行AirSim/PythonClient/hello_drone.py或hello_car.py这些最基本的脚本排除你自己代码的问题。6.4 仿真画面卡顿或传感器数据延迟高症状仿真运行不流畅或者通过API获取图像、激光雷达数据很慢。排查查看GPU占用在仿真运行时在另一个终端运行nvidia-smi -l 1观察GPU利用率和显存占用。如果利用率很低但卡顿可能是CPU瓶颈或设置问题。降低图形设置在UE4编辑器的“播放”模式下点击“设置”-“引擎可扩展性设置”将质量从“史诗”调至“高”或“中”。优化AirSim设置在settings.json中可以关闭不需要的传感器或者降低传感器分辨率、采样频率。例如深度相机和语义分割相机的计算开销很大。使用“独立模式”运行在UE4编辑器中点击“文件”-“打包项目”-“Linux”将项目打包成独立的可执行文件。然后用命令行运行这个可执行文件通常性能会比在编辑器内“播放”更好因为省去了编辑器的开销。整个环境搭建过程确实繁琐但一旦成功你就拥有了一个功能强大、可高度定化的机器人仿真平台。我个人的体会是耐心和细致的日志阅读是关键。每次失败终端输出的错误信息都是最好的线索。不要盲目重试而是根据错误信息去搜索、去理解背后的原因。把这个环境搭建过程走通本身也是对Linux系统管理、大型C项目编译、游戏引擎架构的一次深刻学习。当你第一次用自己的Python代码控制虚幻世界中的无人机平稳起飞时之前所有的折腾都是值得的。