1. 项目概述从编译报错到成功运行AirSim如果你是一名对无人机仿真、自动驾驶或者机器人研究感兴趣的开发者那么AirSim这个由微软开源的仿真平台你一定不会陌生。它基于虚幻引擎Unreal Engine构建提供了极为逼真的物理环境和传感器模拟是算法验证和原型开发的利器。然而AirSim的编译过程尤其是与较新版本的虚幻引擎如UE5.2搭配时堪称一道“劝退”高墙。各种依赖缺失、版本冲突、编译报错层出不穷让无数开发者望而却步宝贵的精力都消耗在了环境搭建上而不是核心算法的研究上。我自己最近就深陷这个泥潭。在Windows 10系统上使用官方主流的UE5.2版本编译AirSim遭遇了各种稀奇古怪的编译错误从Python脚本执行失败到虚幻引擎构建工具UnrealBuildTool的模块引用错误每一步都像在“扫雷”。经过一番折腾我发现问题的核心往往在于AirSim官方仓库的代码与虚幻引擎最新版本的API或构建系统不完全同步。幸运的是社区里存在一个名为“Colosseum”的分支它专门为适配更新版本的UE包括UE5.2进行了大量修复和调整。这个分支就像一把“金钥匙”能帮你绕开大部分官方主线代码的编译陷阱。这篇文章就是为你准备的“排雷”实战手册。我将手把手带你在Windows 10系统上使用UE5.2和AirSim的Colosseum分支完成从零开始的编译、配置直到成功运行Car车辆模式的完整流程。无论你是刚接触AirSim的新手还是被编译问题困扰已久的老兵这篇保姆级教程都能帮你节省大量试错时间直达目标。2. 环境准备与工具选型为何是这套组合拳在开始动手之前我们先来明确一下这次搭建的“技术栈”及其背后的逻辑。知其然更要知其所以然这样即使未来版本更新你也能举一反三。2.1 操作系统Windows 10 22H2为什么选择Win10而不是Win11稳定性与兼容性是首要考量。Win10 22H2版本是目前经过长期验证、最为稳定的Windows版本之一。大量的开发工具、驱动和SDK对其支持最为完善。Win11虽然新但其右键菜单、资源管理器等改动有时会与一些老旧的构建脚本或命令行工具产生微妙的兼容性问题增加不必要的变量。我们的目标是搭建一个稳定可靠的开发环境而非尝鲜。因此一个干净、无过多第三方软件干扰的Win10专业版或企业版是最佳选择。注意如果你的系统已经升级到Win11并且遇到了问题可以考虑在虚拟机如VMware或VirtualBox中安装一个纯净的Win10系统进行开发。虚拟机环境隔离性好方便做快照和重置。2.2 虚幻引擎5.2.x版本UE5.2是一个重要的里程碑版本引入了Nanite虚拟化几何体和Lumen全局光照等革命性技术虽然AirSim本身不一定用到这些高级特性但使用一个较新且稳定的引擎版本有助于获得更好的编辑器体验和长期支持。更重要的是AirSim的Colosseum分支已经针对UE5.2进行了适配修复了在5.0、5.1版本中可能存在的API变更导致的问题。我们不选择最新的UE5.3或5.4是因为社区分支的适配工作可能存在滞后而5.2是一个经过充分验证的“甜点”版本。安装建议通过Epic Games Launcher进行确保安装时勾选以下组件.NET桌面开发这是运行C#编译器和一些工具链的基础。Windows 10/11 SDKAirSim的编译依赖Windows SDK。Unreal Engine C 工具这是必须的它包含了编译UE项目所需的所有头文件、库和构建工具如UnrealBuildTool。2.3 AirSim代码Colosseum分支这是本教程的核心。AirSim官方仓库github.com/microsoft/AirSim的主分支main通常与某个特定版本的UE如UE4.27绑定最紧密。当UE版本升级后由于引擎模块路径、函数签名或构建规则的改变主分支代码很可能无法直接编译通过。Colosseum分支通常指github.com/nervosys/AutonomySim仓库下的相关分支或社区维护的特定适配分支其名称可能包含colosseum或ue5.2字样是由社区开发者维护的他们主动将AirSim代码向前移植forward-port到更新的UE版本上修复了编译错误和运行时问题。使用这个分支相当于站在了前人的肩膀上直接跳过了最痛苦的“踩坑”阶段。2.4 其他关键工具Visual Studio 2022必须安装“使用C的桌面开发”工作负载并确保包含“MSVC v143 - VS 2022 C x64/x86 生成工具”和“Windows 10/11 SDK”。VS不仅是代码编辑器更是编译UE和AirSim的“发动机”。CMake ( 3.18)用于生成AirSim的客户端库如Python库的构建文件。虽然UE项目本身用.uproject文件管理但AirSim的一些外部依赖和包装库需要CMake。Python 3.8/3.9 (64-bit)AirSim的很多工具脚本如设置环境变量、生成项目文件是用Python写的。避免使用Python 3.10因为某些科学计算库的兼容性可能有问题。安装时务必勾选“Add Python to PATH”。Git用于克隆代码仓库。这套“Win10 UE5.2 AirSim Colosseum分支 VS2022”的组合是当前平衡了稳定性、功能性和社区支持的最佳实践方案。3. 详细实操步骤一步步攻克编译堡垒理论准备就绪现在开始实战。请严格按照步骤操作任何一步的疏漏都可能导致后续失败。3.1 第一步基础环境搭建与检查首先我们需要一个干净、有序的工作目录。假设我们在D:\盘下工作。创建工作区新建文件夹D:\AirSim_UE5。所有相关代码都将放在这里路径中不要有中文或空格。安装并验证工具打开命令提示符CMD或 PowerShell依次运行以下命令检查安装是否成功git --version cmake --version python --version打开Visual Studio Installer确认已安装“使用C的桌面开发”和必要的Windows SDK。获取虚幻引擎5.2通过Epic Games Launcher安装UE 5.2.x。记住其安装路径通常是C:\Program Files\Epic Games\UE_5.2。3.2 第二步克隆与准备AirSim Colosseum分支代码这里以社区中一个较为活跃的、针对UE5.2适配的仓库为例实际操作时请在GitHub上搜索最新最稳定的Colosseum分支。克隆仓库在D:\AirSim_UE5目录下打开Git Bash或PowerShell。git clone https://github.com/nervosys/AutonomySim.git cd AutonomySim注AutonomySim是AirSim的一个活跃分支其ue5.2或colosseum分支通常维护得很好。克隆后默认可能在main分支。切换到适配分支查找并切换到针对UE5.2的适配分支。git branch -a | findstr /i ue5.2 # 查看远程是否有ue5.2相关分支 git checkout -b ue5.2 origin/ue5.2 # 假设远程分支名为ue5.2并创建本地分支跟踪如果找不到明确的ue5.2分支可以尝试git checkout colosseum或查看仓库的README和Issues寻找推荐的分支名。这是最关键的一步选对分支成功了一半。3.3 第三步使用项目文件生成器至关重要这是避免后续一系列编译错误的“魔法”步骤。AirSim仓库根目录下有一个setup.bat或build.cmd脚本但对于Colosseum分支我们更依赖Python脚本。运行环境准备脚本cd D:\AirSim_UE5\AutonomySim python setup.bat或者如果setup.bat不存在或报错尝试python -m pip install --upgrade pip pip install -r requirements.txt # 安装Python依赖这个脚本会检查环境并可能提示你设置UNREAL_HOME环境变量。设置UNREAL_HOME环境变量如果脚本未自动设置右键点击“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”或“用户变量”中新建一个变量变量名UNREAL_HOME变量值C:\Program Files\Epic Games\UE_5.2请替换为你的实际路径。同时将%UNREAL_HOME%\Engine\Binaries\DotNET\UnrealBuildTool所在的路径通常是C:\Program Files\Epic Games\UE_5.2\Engine\Binaries\DotNET添加到系统的PATH变量中这能确保命令行可以找到UnrealBuildTool。生成UE项目文件这是核心操作将AirSim模块集成到UE项目中。python build.cmd --ue-path C:\Program Files\Epic Games\UE_5.2 --gen-project-files这个命令会调用UE的构建工具读取AirSim的模块定义文件*.Build.cs并生成Visual Studio解决方案文件*.sln和UE项目文件*.uproject。如果这一步成功你会看到生成了AutonomySim.uproject文件。实操心得很多编译报错如“Missing UnrealBuildTool”、“Could not find rule file”等都源于这一步没有正确执行或者UNREAL_HOME路径设置错误。务必确保路径指向的UE目录包含Engine\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe。3.4 第四步编译AirSim插件与项目生成项目文件后我们有两种编译方式使用Visual Studio编译解决方案或者使用UE编辑器编译。推荐第一种更底层问题更易排查。使用Visual Studio打开解决方案在D:\AirSim_UE5\AutonomySim目录下找到并双击AutonomySim.sln文件用Visual Studio 2022打开。在VS顶部的解决方案配置下拉菜单中选择Development Editor和Win64。编译解决方案在解决方案资源管理器中右键点击AutonomySim项目不是解决方案选择“生成”。这是一个漫长的过程首次编译可能需要30分钟到1小时以上取决于你的电脑性能。编译过程中会下载并编译AirSim的所有依赖如rpclib、MavLink等。关键观察点编译输出窗口会滚动大量信息。你需要关注的是是否有“错误”出现。常见的错误包括找不到头文件可能是Windows SDK版本不对或路径问题。链接错误通常是库文件版本不匹配或者某些依赖库没有正确编译。Python脚本错误检查Python环境变量和版本。处理常见编译报错错误示例1fatal error C1083: 无法打开包括文件: “Windows/Windows.h”: No such file or directory原因Windows SDK未安装或VS未正确配置。解决用Visual Studio Installer修改安装确保勾选了正确版本的Windows 10/11 SDK。然后在VS中打开“项目” - “属性” - “配置属性” - “常规”检查“Windows SDK版本”是否已设置。错误示例2LNK1181: 无法打开输入文件“xxx.lib”原因依赖库编译失败或路径不对。解决先尝试清理解决方案“生成” - “清理解决方案”然后重新生成。如果问题依旧去AutonomySim\AirLib\deps目录下查看各第三方库如rpclib、MavLinkCom的源码是否存在尝试手动执行其CMake构建步骤查看对应目录下的README。错误示例3UnrealBuildTool 异常或规则文件缺失原因UNREAL_HOME环境变量错误或UE安装不完整。解决重新检查并设置UNREAL_HOME环境变量确保指向的UE目录完整。可以尝试在命令行直接运行%UNREAL_HOME%\Engine\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe看是否能启动。编译成功标志当VS输出窗口最后显示 生成: 成功 1 个失败 0 个最新 0 个跳过 0 个 并且D:\AirSim_UE5\AutonomySim\Plugins\AirSim\Binaries\Win64目录下生成了UnrealEditor-AirSim.dll等文件说明插件编译成功。3.5 第五步配置并运行Car车辆模式编译成功后我们终于可以启动虚幻编辑器并配置车辆模式了。启动项目双击D:\AirSim_UE5\AutonomySim\AutonomySim.uproject。UE编辑器会启动并可能提示你“重新编译模块”点击“是”。编辑器加载完成后你应该能看到一个默认的场景可能是“Blocks”环境。启用Car模式AirSim默认是Multirotor多旋翼无人机模式。我们需要修改设置来启用Car车辆。在项目内容浏览器中导航到AirSim-Settings。如果没有settings.json文件就自己创建一个。在项目根目录与.uproject文件同级下创建或编辑settings.json文件。这个文件是AirSim运行时加载的配置文件。将以下内容写入settings.json{ SettingsVersion: 1.2, SimMode: Car, Vehicles: { Car1: { VehicleType: PhysXCar, AutoCreate: true } } }SimMode: Car指定仿真模式为车辆。VehicleType: PhysXCar指定使用PhysX物理引擎的车辆模型这是UE内置的最稳定。AutoCreate: true告诉AirSim在仿真开始时自动生成这辆车。放置车辆和玩家起点在UE编辑器世界中你需要一个玩家出生点Player Start和一辆车辆。对于Car模式通常我们直接使用AirSim提供的车辆蓝图。在内容浏览器中搜索CarPawn或PhysXCar路径可能在AirSim/VehicleAdv下找到车辆蓝图。将其从内容浏览器拖放到场景地面。确保场景中有一个Player Start组件可以在放置模式下搜索并放置。车辆和Player Start的位置将决定仿真开始时的位置。运行测试点击编辑器顶部的“运行”按钮或按F8键进入“独立游戏”模式。如果一切配置正确你将看到一辆车出现在场景中并且视角锁定在车辆上。你可以使用键盘方向键或WASD来尝试控制车辆前后左右移动。如果车辆不动可能是输入绑定问题需要检查UE的输入设置或者AirSim的车辆控制API。4. 深度排错与常见问题实录即使按照教程一步步来你也可能遇到独特的问题。下面是我在多次搭建中遇到的“坑”及其解决方案。4.1 编译阶段顽固错误排查问题build.cmd脚本运行一半卡住或报Python错误。排查打开build.cmd或对应的Python脚本如setup.py查看其具体执行逻辑。有时脚本会尝试从网络下载依赖如果网络超时就会卡住。可以尝试手动安装所需的Python包pip install -r requirements.txt或者使用代理。解决对于网络问题可以手动下载缺失的预编译库放到指定目录。更直接的方法是在GitHub的仓库Issues或Pull Requests中搜索你的错误信息很可能有人已经提供了补丁patch或修改后的脚本文件。问题编译时出现大量C语法错误例如expected a ‘;’在Eigen库文件中。原因这很可能是Visual Studio的编译器版本与代码不兼容。AirSim及其依赖如Eigen对编译器标准有要求。VS2022默认使用较新的MSVC编译器可能与某些代码的严格模式冲突。解决在项目属性中尝试降低C语言标准。右键点击AutonomySim项目 - “属性” - “C/C” - “语言” - “C语言标准”尝试改为“ISO C17 标准 (/std:c17)”甚至“ISO C14 标准 (/std:c14)”。但注意UE5.2本身可能需要C17或更高所以这只是一个尝试方向。更好的方法是确保你使用的Colosseum分支已经为VS2022和UE5.2做好了适配。问题成功编译但启动编辑器时崩溃提示AirSim插件加载失败。排查查看Windows事件查看器Event Viewer或UE编辑器的输出日志通常位于项目文件夹/Saved/Logs目录下的.log文件。日志中会有详细的错误堆栈。常见原因1插件依赖的DLL缺失。确保AirSim.dll及其所有依赖如rpc.lib相关的DLL都正确复制到了插件的Binaries/Win64目录下。有时需要手动从deps目录的构建文件夹中拷贝。常见原因2UE引擎版本与插件二进制文件不匹配。你编译插件用的UE版本必须和启动项目用的UE版本完全一致都是5.2.x的同一个小版本。通过Epic Games Launcher启动编辑器可以保证这一点。4.2 运行时配置与连接问题问题Car模式能运行但车辆对键盘输入无反应。检查1UE编辑器输入绑定。打开“编辑” - “项目设置” - “引擎” - “输入”查看“操作映射”和“轴映射”中是否有与车辆控制相关的设置如Throttle,Steering。AirSim插件通常会自己添加但有时会失效。检查2AirSim的车辆API控制。Car模式默认可能优先监听外部API如Python客户端的控制指令。确保你没有运行任何正在发送控制指令的AirSim Python脚本。你可以尝试通过Python客户端发送一个简单的armDisarm命令或setCarControls命令看车辆是否响应来区分是输入问题还是API控制权问题。临时解决在settings.json中可以尝试为车辆添加RC配置模拟遥控器信号但这通常用于多旋翼。问题如何连接Python客户端控制车辆AirSim的强大之处在于可以通过API进行外部控制。确保仿真运行后在另一个命令行窗口你可以运行Python脚本。安装AirSim Python客户端在AutonomySim\PythonClient目录下运行pip install -r requirements.txt然后pip install -e .进行本地安装。基础测试脚本创建一个test_car.pyimport airsim import time # 连接到仿真器 client airsim.CarClient() client.confirmConnection() # 获取车辆控制对象 car_controls airsim.CarControls() # 设置油门和转向 car_controls.throttle 0.5 car_controls.steering 0.2 client.setCarControls(car_controls) # 让车跑两秒 time.sleep(2) # 刹车 car_controls.brake 1.0 car_controls.throttle 0.0 client.setCarControls(car_controls)运行此脚本如果车辆移动说明从编译到API连接的整个链路都通了。4.3 性能优化与进阶配置问题仿真运行很卡帧率低。降低图形设置在UE编辑器中打开“设置” - “引擎可扩展性设置”将质量从“史诗”调至“高”或“中”。对于算法测试视觉保真度不是首要的。关闭不必要的插件在“编辑” - “插件”中禁用暂时用不到的插件。使用简单的场景AirSim自带的“Blocks”环境已经很轻量。避免在初期使用高度复杂、植被繁多的官方示例地图。调整AirSim设置在settings.json中可以降低传感器数据的更新频率或者关闭暂时不需要的传感器如激光雷达能显著提升性能。进阶配置多个车辆或自定义传感器多车辆在settings.json的Vehicles对象中添加多个键值对即可如Car1,Car2并分别配置它们的起始位置X, Y, Z。自定义传感器在车辆配置中添加Sensors对象详细定义摄像头、雷达、IMU等参数如焦距、分辨率、视野角FOV、数据输出频率等。这需要参考AirSim官方文档中关于传感器配置的部分但配置格式是通用的。整个流程走下来从环境准备到成功运行Car模式虽然步骤繁多但每一步都有其明确的目的。核心的“捷径”就是利用好社区维护的Colosseum分支它能帮你解决90%的版本兼容性报错。剩下的10%则需要你耐心地根据错误信息结合本文提供的排查思路逐一攻克。记住编译环境的搭建本身就是一项重要的技能成功解决这些问题的过程会让你对UE项目的构建链、C依赖管理有更深的理解。当你第一次看到自己编译的AirSim车辆在虚幻引擎的精致世界里奔驰时那种成就感会让你觉得所有的折腾都是值得的。