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

1. 项目概述与环境准备

在自动驾驶、无人机和机器人算法的研发领域，仿真测试是验证算法鲁棒性、安全性和效率的关键环节，它能将昂贵的物理测试成本和对现实世界的潜在风险降到最低。微软开源的AirSim，作为一个基于游戏引擎的高保真物理仿真平台，因其对传感器（如摄像头、激光雷达、IMU）的精细模拟和对PX4、ROS等生态的良好支持，成为了研究者和工程师的首选工具之一。而Unreal Engine 4（UE4）则为其提供了令人惊叹的视觉渲染能力和灵活的场景构建工具。然而，将AirSim与UE4在Ubuntu 20.04这个稳定的Linux发行版上成功“撮合”起来，并开发属于自己的仿真场景，这个过程本身就像一场充满技术细节的“探险”。我花了将近一周的时间，踩遍了从驱动安装到编译错误的几乎所有“坑”，才最终让无人机在自定义的城市上空稳定起飞。这篇文章，就是这份“探险”笔记的完整复盘，旨在为后来者铺平道路，让你能绕过我踩过的那些坑，高效地搭建起属于你自己的高逼真度仿真沙盒。

这个环境主要面向几类朋友：一是从事自动驾驶、无人机路径规划或计算机视觉算法的研究者，需要一个可编程、可重复的测试环境；二是机器人领域的工程师，希望在实际部署前，在仿真中验证控制逻辑和感知系统；三是任何对高保真模拟感兴趣，并愿意在Linux环境下折腾的技术爱好者。整个流程可以概括为三个核心阶段：首先是打好地基，即准备一个“干净”且驱动完备的Ubuntu 20.04系统；其次是构建核心，分别安装并配置UE4和AirSim；最后是创造世界，将自定义的3D场景导入UE4，并与AirSim联动。我会在每个阶段都穿插我实际遇到的“坑”和解决技巧，这些往往是官方文档不会详细提及的。

注意：整个安装过程对网络环境要求较高，需要从GitHub、Epic Games等国外服务器拉取大量数据（UE4引擎本身约30GB，AirSim及依赖约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准备“武器库”。这包括编译工具链、必要的库文件以及版本管理工具。

1. 安装基础编译工具和Python3：UE4和AirSim的编译构建离不开它们。

   sudo apt install build-essential cmake clang-12 lld-12 python3 python3-pip

   这里指定clang-12和lld-12是因为UE4源码编译对Clang版本有特定要求，12是一个经过验证的稳定版本。

2. 安装.NET Core SDK：AirSim的构建脚本（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仓库要求为准

3. 安装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 UnrealEngine

2.3 运行安装脚本并开始编译

UE4提供了一个自动化安装脚本，它会下载剩余的二进制依赖组件（如.NET、Visual Studio Code的调试工具等，即使在Linux上也需要）。

./Setup.sh

这个脚本运行时间较长，它会检查系统环境并下载约数GB的依赖文件。完成后，开始真正的编译：

./GenerateProjectFiles.sh make

make编译是整个过程的核心，它会调用Clang编译器，消耗大量的CPU和内存资源。在我的Ryzen 7 5800X（8核16线程）和32GB内存的机器上，这个过程持续了大约2个半小时。期间CPU会持续满载，风扇狂转，这是正常现象。

注意事项与排坑实录：

1. 内存不足：编译UE4是内存吞噬兽。如果内存不足（例如只有8GB），极有可能在编译到70%-80%时因virtual memory exhausted而失败。解决方案有两种：一是增加物理内存或创建足够大的交换空间（swap），我建议交换空间至少16GB；二是使用make -j N限制并行编译任务数，N为你的CPU核心数，甚至更少（如make -j 4），以减少内存峰值压力。
2. 磁盘空间不足：确保目标分区有超过100GB的可用空间。编译过程中会产生大量的中间文件。
3. 网络超时：./Setup.sh下载依赖时可能因网络问题失败。可以尝试多次运行，或者寻找可靠的网络环境。有时失败后，再次运行脚本会从中断处继续。
4. 编译错误：如果遇到特定的编译错误，通常与缺少某个系统库有关。仔细阅读错误信息，根据提示使用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 AirSim

AirSim的构建系统使用了自己编写的脚本。首先，我们需要更新其子模块：

git submodule update --init --recursive

3.2 编译AirSim插件

AirSim提供了针对Linux的编译脚本。在AirSim根目录下，直接运行：

./build.sh

这个脚本会：

1. 检查环境（包括之前安装的.NET Core SDK和编译工具）。
2. 使用cmake配置生成构建文件。
3. 调用make进行编译。

编译过程比UE4快得多，通常10-20分钟即可完成。编译成功后，会在AirSim根目录下生成一个名为Unreal的文件夹（如果不存在则创建），并在其中生成插件所需的文件，最关键的是AirSim.so（动态链接库）和AirSim.uplugin（插件描述文件）。

3.3 将AirSim插件集成到UE4中

有两种集成方式：引擎级集成和项目级集成。引擎级集成会将插件安装到UE4引擎的全局插件目录，这样所有基于该引擎创建的项目都能直接使用AirSim。项目级集成则是将插件文件复制到特定项目的Plugins文件夹下，只对该项目生效。对于学习和开发自定义场景，我推荐项目级集成，因为它更干净，不影响引擎本身。

步骤一：创建或打开一个UE4空白项目

1. 启动之前编译好的UE4编辑器 (./UE4Editor)。
2. 在项目浏览器中，选择“Games” -> “Blank”，创建一个新的C++空白项目（必须是C++项目，蓝图项目无法直接集成源码插件）。给项目起个名字，比如MyAirSimProject，选择保存路径。
3. 点击“Create”，编辑器会为你生成项目文件并打开。

步骤二：复制插件文件

1. 关闭UE4编辑器。
2. 在文件管理器中，导航到你的AirSim源码目录下的Unreal/Plugins文件夹。你应该能看到一个AirSim文件夹。
3. 将这个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格式的街区模型为例。

在导入前，有几点需要特别注意：

1. 模型尺寸和单位：许多3D建模软件（如Blender、3ds Max）的默认单位与UE4（厘米）可能不一致。在导出FBX时，务必在导出设置中将单位调整为“厘米”（Centimeters），并勾选“应用缩放”（Apply Scale）。否则，模型导入UE4后可能变得巨大或微小。
2. 模型复杂度：过于精细的模型（面数过高）会严重影响仿真时的渲染性能。在可能的情况下，在3D软件中进行适当的减面优化（Decimation）。
3. 材质和纹理：确保模型附带的纹理图片（如.jpg,.png）也一并准备好，并放在一个单独的文件夹里，方便UE4导入时自动关联。

4.2 在UE4中导入FBX场景

1. 在你的MyAirSimProject中，在内容浏览器（Content Browser）里，右键点击空白处，选择“Import to /Game...”。
2. 在弹出的文件对话框中，找到你的.fbx文件，选中它。
3. 会弹出一个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”（合并网格体）可以简化场景层级，但有时为了单独控制某个物体（如可移动的障碍物），可能需要分开。
4. 点击“Import”。UE4会开始处理模型，并在内容浏览器中生成对应的静态网格体（Static Mesh）和材质（Material）资产。

实操心得：我导入一个中等规模的FBX城市模型时，遇到了“未发现平滑组”的警告。这通常意味着模型在导出时丢失了面的平滑信息，导致在UE4中渲染时出现不自然的硬边。解决方法有两种：一是在原始的3D建模软件中重新计算并导出平滑组；二是在UE4中，双击导入的静态网格体，在网格体编辑器中，选择所有面，在“细节”面板中找到“法线”（Normals）部分，点击“重新计算平滑组”（Recompute Normals）或“平均法线”（Average Normals），可以很大程度上改善外观。

4.3 构建场景与设置玩家出生点

1. 放置场景：从内容浏览器中，将刚刚导入的静态网格体拖拽到视口（Viewport）中，它就会成为你场景的一部分。你可以使用移动、旋转、缩放工具（快捷键W/E/R）来调整它的位置。
2. 添加地面和碰撞：导入的模型可能没有物理碰撞体，这意味着无人机或车辆会直接穿透它。你需要为场景添加碰撞。在静态网格体编辑器中，可以点击“碰撞”（Collision）菜单，选择“添加简化碰撞”（Add Simplified Collision）或“自动生成凸包碰撞”（Auto Convex Collision）。对于复杂地形，使用“简化碰撞”生成一个包裹模型的大致形状的简单碰撞盒通常就足够了，性能更好。
3. 设置玩家出生点：在UE4中，仿真智能体（如无人机）的初始位置是由“Player Start”演员决定的。在模式面板（Modes Panel）中搜索“Player Start”，将其拖放到场景中你希望无人机初始出现的位置（例如，离地2米高的空中）。
4. 添加光源：默认场景可能是黑的。从模式面板拖拽一个“定向光源”（Directional Light）和“天空大气”（Sky Atmosphere）到场景中，可以快速获得基本的日光照明效果。

4.4 配置AirSim仿真参数

场景搭建好后，我们需要告诉AirSim在这个场景中模拟什么。这通过一个名为settings.json的配置文件来完成。这个文件需要放在你的项目可执行文件（或项目内容目录）旁边。

1. 在你的项目目录下（与.uproject文件同级），创建一个名为settings.json的文件。
2. 用文本编辑器打开，输入基本的配置。以下是一个支持多旋翼无人机（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 Start），Z=-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 启动仿真

1. 在UE4编辑器中，确保你的场景已经保存（Ctrl+S）。
2. 点击工具栏上的“Play”按钮（或按F8）旁边的下拉箭头，选择“Standalone Game”模式。这会以独立游戏的方式运行你的项目，而不是在编辑器视口中播放。
3. 点击“Play”。UE4会编译最后的着色器（如果第一次运行此场景），然后弹出一个独立的游戏窗口，显示你的3D场景。无人机（可能是一个默认的模型，如四轴飞行器）会出现在你设置的Player Start位置。

此时，AirSim仿真服务器已经在后台运行，并监听API调用。

5.2 使用Python API进行控制测试

AirSim提供了多种语言的客户端API，Python是最方便进行快速测试的一种。打开一个新的终端。

1. 安装AirSim Python客户端库：

   pip install msgpack-rpc-python airsim

2. 编写一个简单的测试脚本，例如test_drone.py：

   import airsim import time # 连接到AirSim仿真服务器 client = airsim.MultirotorClient() client.confirmConnection() # 等待连接建立 # 解锁无人机（Arm） client.enableApiControl(True, vehicle_name="Drone1") client.armDisarm(True, vehicle_name="Drone1") # 起飞到5米高度 print("Taking off...") client.takeoffAsync(vehicle_name="Drone1").join() time.sleep(2) # 向前飞10米 print("Moving forward...") client.moveByVelocityBodyFrameAsync(3, 0, 0, 2, vehicle_name="Drone1").join() # vx=3m/s, 持续2秒 time.sleep(1) # 悬停2秒 client.hoverAsync(vehicle_name="Drone1").join() time.sleep(2) # 降落 print("Landing...") client.landAsync(vehicle_name="Drone1").join() # 上锁并断开API控制 client.armDisarm(False, vehicle_name="Drone1") client.enableApiControl(False, vehicle_name="Drone1") print("Test completed.")

3. 在仿真运行的情况下，在终端运行这个脚本：

   python3 test_drone.py

如果一切顺利，你将看到游戏窗口中的无人机自动执行起飞、前飞、悬停和降落的动作。同时，终端会打印出相应的状态信息。至此，一个完整的Ubuntu 20.04下AirSim与UE4联合仿真环境，以及自定义场景的开发流程就全部跑通了。

6. 常见问题排查与性能优化技巧

即便按照步骤操作，你也可能会遇到一些棘手的问题。下面是我在搭建和调试过程中遇到的典型问题及其解决方案。

6.1 编译与启动类问题

6.2 运行时与API连接问题

6.3 性能优化与开发建议

1. 场景优化是性能关键：仿真帧率（FPS）直接影响控制的实时性和物理模拟的准确性。对于大型自定义场景：

   • 使用LOD（层次细节）：在UE4中为复杂静态网格体设置LOD，让远处的模型用更少的面数渲染。
   • 合并网格体：将大量小物体（如一堆石头、草丛）合并成一个大的静态网格体，可以减少绘制调用（Draw Calls）。
   • 谨慎使用动态光源和阴影：实时阴影非常消耗性能。尽量使用烘焙光照（Lightmass）或静态光源。
   • 在AirSim中关闭不必要的传感器：在settings.json中只启用你实验必需的传感器（如摄像头、激光雷达）。每个传感器都会增加每帧的计算开销。

2. 使用tmux或screen管理长时间任务：编译UE4、运行仿真服务器都是长时间进程。在远程服务器或防止终端关闭导致任务中断时，使用tmux new -s ue4_build创建一个会话，在其中运行编译命令，即使断开SSH连接，编译也会继续。

3. 版本控制与备份：UE4项目目录（尤其是Content和Config文件夹）和AirSim的settings.json文件应该纳入Git版本控制。但注意不要提交Binaries、Intermediate、DerivedDataCache等编译生成的大型文件夹，将它们添加到.gitignore中。

4. 调试与日志：当出现诡异问题时，查看日志是首要任务。AirSim的日志默认输出到~/.ros/log或项目目录下的airsim.log文件（取决于设置）。UE4编辑器的日志可以在启动时添加-log参数，或查看~/.config/Epic/UnrealEngine/4.27/下的日志文件。仔细阅读错误信息，往往能快速定位问题根源。

搭建这个环境的过程，就像在组装一台精密的仪器，每一个环节的严丝合缝都至关重要。从驱动到编译，从导入到配置，每一步的疏忽都可能导致后续的失败。但一旦成功，你所获得的将是一个功能强大、高度可控的虚拟试验场，无论是测试一个新颖的SLAM算法，还是验证一套复杂的无人机编队协议，它都能提供接近真实的反馈。我个人的体会是，前期在系统环境和编译上多花些时间，确保基础稳固，远比在后期调试各种古怪问题时反复折腾要高效得多。最后一个小技巧：将成功的环境状态（包括特定的驱动版本、UE4提交哈希、AirSim分支）记录下来，形成你自己的“已知稳定配置”，这在未来升级或复现时能节省大量时间。