1. 项目概述与核心价值最近在折腾无人机仿真和自动驾驶相关的项目发现AirSim这个由微软开源的仿真平台确实是个好东西。它基于虚幻引擎UE4/UE5能提供非常逼真的物理环境和传感器模拟无论是做算法验证还是原型开发效率都比直接上真机高太多了。但说实话第一次在Ubuntu上搭建UE4AirSim这套环境绝对是个“劝退级”的体验。各种依赖冲突、编译错误、版本不匹配网上的教程又多是零散的照着做十有八九会卡在某个莫名其妙的环节。所以我决定把这次从零开始在Ubuntu 20.04 LTS上成功搭建UE4.27和AirSim开发环境的完整过程连同我踩过的所有坑和解决方案系统地整理出来。这篇指南的目标很明确让你能一次成功把时间花在真正的开发上而不是无休止的环境配置上。无论你是做机器人、自动驾驶的研究者还是对仿真技术感兴趣的开发者这套环境都是你进入这个领域的坚实起点。我会假设你有一台安装了Ubuntu 20.04的机器物理机或虚拟机均可但物理机性能更佳并且具备基本的Linux命令行操作知识。接下来我们就手把手开始。2. 环境准备与前置条件检查在开始安装任何软件之前打好基础至关重要。一个干净、配置正确的系统环境能避免后续至少50%的奇怪问题。2.1 系统更新与基础依赖安装首先确保你的Ubuntu 20.04系统是最新的。打开终端执行以下命令sudo apt update sudo apt upgrade -y这个命令会更新软件包列表并升级所有可升级的包。完成后我们需要安装一系列编译UE4和AirSim所必需的工具和库。这包括构建工具、Python环境、图形库等。一次性安装以下包组sudo apt install -y \ build-essential \ cmake \ git \ python3 \ python3-pip \ python3-dev \ libxml2-dev \ libxslt1-dev \ zlib1g-dev \ libgl1-mesa-dev \ libglu1-mesa-dev \ libxrandr-dev \ libxinerama-dev \ libxcursor-dev \ libxi-dev \ libssl-dev \ libudev-dev \ libvulkan1 \ vulkan-utils \ mesa-vulkan-drivers \ libomp-dev \ clang \ ninja-build \ curl \ wget \ unzip \ pkg-config注意这里安装的libvulkan1和mesa-vulkan-drivers是UE4在Linux上运行所必需的Vulkan图形API支持。如果你的机器是NVIDIA显卡并打算使用专有驱动后续还需要额外配置但这一步确保了基础图形库的存在。2.2 显卡驱动与CUDA工具包安装NVIDIA用户如果你使用的是NVIDIA显卡并且希望利用GPU进行加速这对于UE4编辑器流畅运行和AirSim仿真至关重要那么安装合适的驱动和CUDA是必须的。这里有个大坑UE4.27对CUDA版本有特定要求而CUDA版本又依赖于特定的NVIDIA驱动版本。经过实测CUDA 11.4与UE4.27兼容性较好。我们可以通过官方仓库安装添加NVIDIA CUDA仓库wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-ubuntu2004.pin sudo mv cuda-ubuntu2004.pin /etc/apt/preferences.d/cuda-repository-pin-600 sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/3bf863cc.pub sudo add-apt-repository deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/ / sudo apt update安装CUDA 11.4及相关驱动sudo apt install -y cuda-toolkit-11-4这个命令会同时安装匹配的NVIDIA驱动。安装完成后需要重启系统。验证安装 重启后打开终端运行nvidia-smi你应该能看到显卡信息并且CUDA版本显示为11.4。同时运行nvcc --version确认CUDA编译器也已正确安装。实操心得强烈建议在物理机上操作。在VMware等虚拟机中直通NVIDIA显卡GPU Passthrough非常复杂且性能损耗大。对于仿真开发物理机是首选。如果只有虚拟机可以考虑使用UE4的“空项目”进行代码编译但运行编辑器进行场景编辑会非常卡顿。2.3 配置Python虚拟环境虽然系统自带了Python3但为了避免项目间的包冲突我们为AirSim创建一个独立的虚拟环境。AirSim的Python API是其重要组成部分。# 安装虚拟环境管理工具 sudo apt install -y python3-venv python3-pip # 创建一个名为airsim的虚拟环境建议放在用户目录下 cd ~ python3 -m venv airsim_env # 激活虚拟环境 source ~/airsim_env/bin/activate激活后你的命令行提示符前会出现(airsim_env)字样。请确保在后续所有与AirSim Python API相关的操作中都保持此虚拟环境处于激活状态。在这个虚拟环境中安装一些基础包pip install --upgrade pip pip install numpy msgpack-rpc-python3. 获取与编译虚幻引擎4.27这是整个流程中最为耗时和容易出错的环节。Epic Games官方并未提供Linux版的UE4编辑器二进制发行版我们必须从源码编译。3.1 获取UE4源代码你需要访问Epic Games的GitHub仓库并关联你的Epic账户。如果你还没有请先去 Epic Games官网 注册一个账户。关联GitHub账户登录你的GitHub账户。访问 Epic Games的GitHub组织页面 。你会看到UnrealEngine仓库。点击进入网页会引导你完成Epic账户与GitHub的关联授权。完成授权后你就有权限克隆代码了。克隆代码这需要一些时间代码库很大# 切换到计划存放引擎的目录例如用户目录下的Development文件夹 cd ~ mkdir -p Development cd Development # 克隆UE4.27发布分支的代码 # 注意请使用你自己的GitHub用户名替换YOUR_GITHUB_USERNAME git clone -b 4.27 https://github.com/EpicGames/UnrealEngine.git cd UnrealEngine克隆完成后目录结构大概是~/Development/UnrealEngine。3.2 安装引擎编译依赖UE4提供了一个便捷的脚本来安装所有必要的依赖./Setup.sh这个脚本会自动下载并安装所需的工具链包括特定的Clang版本、 .NET Core等。它会检查你的系统并提示缺失的依赖通常按照提示安装即可。整个过程会持续较长时间并且需要稳定的网络连接。3.3 编译虚幻引擎依赖安装完成后开始编译引擎。这是对机器性能尤其是CPU核心数和内存的考验。./GenerateProjectFiles.sh makeGenerateProjectFiles.sh会生成Makefile。make命令开始编译。你可以通过-j参数指定并行编译的作业数以加快速度例如make -j 8假设你的CPU有8个线程。编译过程可能持续1到3小时取决于你的硬件配置。避坑指南编译过程中最常见的错误是内存不足Out of Memory。如果机器内存小于16GB强烈建议增加交换空间Swap。# 创建一个8GB的交换文件 sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 为了永久生效将以下行添加到 /etc/fstab # /swapfile none swap sw 0 0编译完成后你可以选择关闭或保留这个交换文件。编译成功后你会在~/Development/UnrealEngine/Engine/Binaries/Linux目录下找到UnrealEditor等可执行文件。你可以创建一个启动器或别名来方便启动# 在~/.bashrc中添加别名 echo alias ue4-editor~/Development/UnrealEngine/Engine/Binaries/Linux/UnrealEditor ~/.bashrc source ~/.bashrc现在在终端输入ue4-editor应该就能启动UE4编辑器了。第一次启动会进行一些初始化设置可能会比较慢。4. 编译与配置AirSim有了UE4引擎我们现在可以编译AirSim插件了。AirSim本质上是一个UE4插件。4.1 获取AirSim源代码我们同样从GitHub克隆代码。建议放在一个独立于引擎的目录例如~/Development。cd ~/Development git clone https://github.com/microsoft/AirSim.git cd AirSim4.2 编译AirSim插件AirSim的编译过程会调用我们刚才编译好的UE4引擎。关键是要正确设置UE4_ROOT环境变量指向你的UE4源码根目录。# 设置UE4根目录环境变量请根据你的实际路径修改 export UE4_ROOT~/Development/UnrealEngine # 运行AirSim自带的编译脚本 ./setup.sh ./build.shsetup.sh脚本会检查环境并安装一些额外的Python依赖如airsim包。build.sh脚本则会调用UE4的构建系统UnrealBuildTool来编译AirSim插件。这个过程会比编译整个引擎快很多通常十几分钟到半小时。编译成功后输出主要在两个地方插件本身位于AirSim/Unreal/Plugins/AirSim目录下。这个文件夹可以直接被复制到任何UE4项目中使用。Python客户端库位于AirSim/PythonClient。编译过程会自动将生成的airsim包安装到当前系统的Python环境或者你激活的虚拟环境中。你可以验证一下# 确保仍在airsim_env虚拟环境中 source ~/airsim_env/bin/activate python -c “import airsim; print(airsim.__version__)”如果没有报错并输出版本号说明Python客户端安装成功。4.3 创建并配置UE4项目以使用AirSim我们不直接在引擎中开发而是创建一个独立的UE4项目来集成AirSim插件。使用UE4编辑器创建新项目运行ue4-editor启动编辑器。选择“游戏Games” - “空白Blank”模板。选择项目存放位置例如~/Development/MyAirSimProject项目名称设为MyAirSimProject确保“包含初学者内容包”被选中这可以提供一些基础素材。点击“创建项目”。编辑器会打开这个新项目。集成AirSim插件关闭UE4编辑器。将编译好的AirSim插件文件夹~/Development/AirSim/Unreal/Plugins/AirSim整个复制到你的项目插件目录~/Development/MyAirSimProject/Plugins/。如果Plugins文件夹不存在就创建一个。复制完成后你的项目结构应类似于MyAirSimProject/ ├── Config/ ├── Content/ ├── Plugins/ │ └── AirSim/ -- 这就是复制过来的插件 ├── Source/ └── MyAirSimProject.uproject生成Visual Studio项目文件用于C开发 如果你想修改AirSim的C代码或创建自己的无人机模型/传感器需要将项目转换为C项目并生成IDE文件。在项目目录MyAirSimProject.uproject所在处右键选择“Generate Visual Studio project files”。或者使用命令行cd ~/Development/MyAirSimProject $UE4_ROOT/Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool -projectfiles -project“MyAirSimProject.uproject” -game -rocket -progress这会在项目目录下生成MyAirSimProject.sln等文件。配置项目设置文件 AirSim的行为通过配置文件控制。在你的项目目录~/Development/MyAirSimProject/Config下创建一个名为settings.json的文件。这是一个最基础的配置示例定义了一台具有默认传感器的四旋翼无人机{ “SeeDocsAt”: “https://github.com/Microsoft/AirSim/blob/master/docs/settings.md”, “SettingsVersion”: 1.2, “SimMode”: “Multirotor”, “Vehicles”: { “Drone1”: { “VehicleType”: “SimpleFlight”, “X”: 0, “Y”: 0, “Z”: 0, “Sensors”: { “imu”: { “SensorType”: 2 }, “gps”: { “SensorType”: 3 }, “magnetometer”: { “SensorType”: 4 }, “barometer”: { “SensorType”: 5 } } } } }这个文件告诉AirSim模拟模式是多旋翼Multirotor有一台名为Drone1的无人机使用SimpleFlight飞行控制器初始位置在原点并搭载了IMU、GPS、磁力计和气压计传感器。5. 运行测试与基础验证环境搭建是否成功最终要靠运行来检验。5.1 启动带AirSim的UE4项目再次启动UE4编辑器。这次你可以直接双击MyAirSimProject.uproject文件或者在终端进入项目目录运行ue4-editor MyAirSimProject.uproject。编辑器启动时会提示“已禁用插件‘AirSim’因为它的模块‘AirSim’未能正确加载。你想现在启用它吗”。点击“是”。编辑器加载完成后你应该能在菜单栏看到“AirSim”的选项这表明插件已成功加载。5.2 使用Python API进行基础控制测试保持UE4编辑器运行它会作为仿真服务器。打开一个新的终端窗口激活你的AirSim Python虚拟环境并运行一个简单的测试脚本。创建测试脚本在任意位置例如~/Development创建一个test_airsim.py文件#!/usr/bin/env python3 import airsim import time # 连接到AirSim仿真服务器默认在本地localhost:41451 client airsim.MultirotorClient() client.confirmConnection() # 获取控制权并解锁 client.enableApiControl(True) client.armDisarm(True) print(“Taking off...”) client.takeoffAsync().join() # 起飞 time.sleep(2) # 悬停2秒 print(“Moving forward...”) # 以1米/秒的速度向前飞5秒 client.moveByVelocityBodyFrameAsync(1, 0, 0, 5).join() print(“Landing...”) client.landAsync().join() # 降落 # 上锁并释放控制权 client.armDisarm(False) client.enableApiControl(False) print(“Test completed!”)运行测试确保UE4编辑器正在运行并且处于“播放Play”模式点击编辑器顶部的“播放”按钮。你会看到场景中的无人机。在新的终端中运行脚本cd ~/Development source ~/airsim_env/bin/activate python test_airsim.py观察UE4编辑器窗口你应该能看到无人机起飞、前飞、然后降落。同时在终端中看到相应的打印信息。如果以上步骤都成功了那么恭喜你一个完整的UE4AirSim开发环境已经搭建完毕6. 常见问题与深度排查指南即使按照步骤操作也可能会遇到问题。这里汇总了我遇到的和社区常见的一些“坑”及其解决方案。6.1 编译阶段问题问题1./Setup.sh或./GenerateProjectFiles.sh失败提示缺少.NET SDK。原因UE4的构建工具需要特定版本的.NET Core。解决运行./Setup.sh时脚本应该会尝试自动安装。如果失败可以尝试手动安装。但更推荐的方法是确保你的系统已完全更新sudo apt update sudo apt upgrade并且按照Epic官方文档使用他们提供的安装脚本。有时网络问题会导致下载失败多试几次或使用代理。问题2make编译过程中出现internal compiler error: Killed (program cc1plus)。原因这几乎总是因为内存不足OOM编译器进程被系统终止了。解决增加交换空间如前文所述创建足够大的交换文件16GB以上更稳妥。减少并行编译任务使用make -j 2或make -j 1来减少内存峰值使用量虽然编译时间会变长。关闭其他内存占用大的程序。问题3编译AirSim时./build.sh报错提示找不到UnrealBuildTool或UE4_ROOT不正确。原因环境变量UE4_ROOT没有设置或者设置路径不正确。解决# 确认路径必须是UE4源码的根目录 echo $UE4_ROOT # 如果不正确重新设置并导出 export UE4_ROOT/home/你的用户名/Development/UnrealEngine # 可以将此命令添加到 ~/.bashrc 中永久生效 echo “export UE4_ROOT/home/你的用户名/Development/UnrealEngine” ~/.bashrc6.2 运行阶段问题问题4启动UE4编辑器时崩溃或启动后加载项目时崩溃错误信息涉及Vulkan或OpenGL。原因图形驱动问题。可能是NVIDIA驱动未安装、安装不正确或者是集成显卡Intel驱动不支持所需的特性。解决再次确认NVIDIA驱动已正确安装nvidia-smi。尝试在启动编辑器时指定使用特定的图形API或禁用高级特性。可以创建一个启动脚本# 编辑一个启动脚本 start_ue.sh echo ‘#!/bin/bash cd ~/Development/UnrealEngine/Engine/Binaries/Linux ./UnrealEditor -opengl4’ ~/start_ue.sh chmod x ~/start_ue.sh使用-opengl4参数强制使用OpenGL 4而不是Vulkan。也可以尝试-vulkan或-nosplash。对于虚拟机环境图形加速能力有限崩溃是常态。考虑在物理机上运行。问题5Python客户端无法连接提示airsim.exceptions.TimeoutError。原因AirSim仿真服务器UE4编辑器没有在运行或者没有处于“播放”模式也可能是网络端口被阻止。解决确保UE4编辑器已启动你的项目并且点击了顶部工具栏的“播放Play”按钮。AirSim API只在播放模式下监听连接。检查连接参数。默认连接的是localhost:41451。如果你的Python脚本运行在另一台机器或容器里需要修改IP地址。在UE4编辑器中查看“输出日志Output Log”搜索“ApiServer”确认它已启动并监听端口。问题6无人机在仿真中不动或者控制指令无效。原因可能是飞行控制器SimpleFlight初始化问题或者物理场景设置有问题。解决检查settings.json配置文件确保VehicleType正确例如“SimpleFlight”。在UE4编辑器中检查世界场景设置World Settings确保“Enable Physics”是开启的。尝试重置仿真在Python脚本中调用client.reset()。查看UE4编辑器的“输出日志”看是否有来自AirSim插件或物理引擎的错误信息。6.3 性能优化与进阶配置提升仿真流畅度降低图形设置在UE4编辑器中打开“设置Settings” - “引擎可扩展性设置Engine Scalability Settings”将各项从“史诗Epic”调至“高High”或“中Medium”特别是阴影、后期处理、纹理等选项。使用简单的场景初期测试时使用“空白”项目自带的“初学者内容”场景或者AirSim自带的“Blocks”环境需要从AirSim的Content目录复制它们比复杂的自定义场景运行得更快。关闭不必要的传感器在settings.json中只启用你当前测试必需的传感器。每个传感器尤其是摄像头都会增加计算负担。连接外部飞行控制器如PX4AirSim的强大之处在于可以连接真实的飞控软件进行硬件在环HITL仿真。这需要额外搭建PX4或ArduPilot的仿真环境。安装PX4-Autopilot按照PX4官方指南克隆并编译其代码。配置AirSim在settings.json中将VehicleType改为“PX4Multirotor”并配置UdpPort等参数使其与PX4的仿真端口通常为14540通信。启动顺序先启动PX4的JMAVSim或Gazebo仿真器再启动UE4AirSim。这个过程更为复杂涉及两个系统的网络通信和时钟同步建议在基础环境稳定后再尝试。7. 开发工作流与工具链集成环境搭好了最终是为了高效开发。这里分享我日常使用的工具链配置。代码编辑与调试Visual Studio Code (VSCode)是我的主力编辑器。配置C和Python开发环境。C安装微软的“C/C”扩展。在项目根目录创建.vscode/c_cpp_properties.json正确配置includePath和defines指向UE4和AirSim的源代码目录。这能提供代码补全和跳转。Python安装“Python”扩展。将解释器路径设置为你的airsim_env虚拟环境中的Python~/airsim_env/bin/python。这样就能方便地编写和调试调用AirSim API的Python脚本。CLion / Qt Creator如果你更喜欢专业的C IDE它们对CMake项目支持很好。AirSim的底层编译虽然用UE4工具链但代码阅读和编辑可以用这些IDE。版本控制你的MyAirSimProject项目目录应该用Git管理。注意在.gitignore文件中忽略Binaries、Intermediate、Saved、DerivedDataCache等UE4生成的中间文件和二进制文件。通常只提交Config、Content你自己的资产、Source和.uproject文件。资产管理与迁移如果你从网上下载了UE4场景或模型.uasset文件将其放入项目的Content目录下然后在UE4编辑器的“内容浏览器Content Browser”中右键点击该目录选择“在资源管理器中显示”将文件复制进去再回到编辑器内刷新即可。将AirSim插件从一个项目复制到另一个项目时确保UE4引擎版本一致并重新生成项目文件右键点击 .uproject - Generate Visual Studio project files。搭建这个环境的过程确实充满挑战但一旦完成它就为你打开了一扇通往高保真机器人仿真与自动驾驶研究的大门。这套环境允许你以极低的成本和风险测试从简单的控制算法到复杂的深度学习感知模型。我个人的体会是前期在环境配置上多花些时间把所有依赖和路径理清楚做好笔记后续的开发效率会成倍提升。当你的Python脚本成功控制着UE4窗口中精致的无人机模型穿越障碍时那种成就感会让你觉得所有的折腾都是值得的。如果在后续使用中遇到新的问题多查阅AirSim的官方文档和GitHub Issues社区通常能找到答案。