1. 项目概述为什么编译AirSim是个“版本地狱”如果你正在研究无人机、自动驾驶或者机器人仿真那你大概率听说过AirSim这个名字。作为微软开源的仿真平台它基于虚幻引擎Unreal Engine简称UE构建能提供高保真的物理和视觉模拟是算法开发和测试的利器。但几乎所有第一次尝试自己编译AirSim的开发者都会在第一步——环境搭建上栽个大跟头。我自己也不例外曾经被各种版本不兼容、编译报错折磨得焦头烂额浪费了好几天时间。这个项目的核心痛点非常明确版本兼容性。AirSim、Unreal Engine、Visual Studio这三者就像三个齿轮必须严丝合缝地对上机器才能转起来。官方文档往往只给出一个宽泛的版本范围或者更新不及时导致新手照着做也步步是坑。最常见的惨状就是兴冲冲地装好了VS2019和UE4.27拉下最新的AirSim代码运行build.cmd然后面对满屏的“无法找到头文件”、“链接错误”、“模块不匹配”而束手无策。所以我决定把最稳定、验证过的一条路径固化下来Windows 10 Visual Studio 2019 Unreal Engine 4.24 AirSim 1.3.1。这个组合是我和团队多次踩坑后总结出的“黄金搭配”编译成功率接近100%。这篇内容就是带你一步步走通这条路径避开所有已知的深坑把环境稳稳当当地搭起来。无论你是想用AirSim做学术研究还是进行产品原型开发一个稳定的编译环境都是万里长征的第一步。2. 环境准备精确到版本的“三件套”安装编译AirSim不是简单的“下载-安装-运行”它要求操作系统、开发工具和游戏引擎三者之间达成一种微妙的平衡。任何一环的版本偏差都可能导致后续编译失败。因此我们的第一步不是急着敲命令而是像配化学试剂一样精确地准备好每一个组件。2.1 操作系统Windows 10的版本与更新管理首先确认你的操作系统是Windows 10。虽然Windows 11理论上也可以但AirSim社区在Win10上的测试更充分遇到问题也更容易找到解决方案。关键在于系统版本和必要的系统组件。系统版本建议使用Windows 10 版本 20H2 或 21H2。这两个版本比较成熟且对开发工具的支持良好。你可以在“设置”-“系统”-“关于”里查看你的Windows规格。系统更新确保系统已安装所有重要更新。特别是涉及到C运行时库和通用CRTC Runtime的更新。很多编译错误比如经典的“无法打开...\ucrt\stdio.h”错误根源就是系统SDK版本不匹配或缺失。通过Windows Update安装最新的质量更新如KB5033052这类更新通常能解决这类问题。开启开发者模式在“设置”-“更新和安全”-“开发者选项”中开启“开发者模式”。这允许你从非商店渠道安装应用比如我们自己编译的UE4并简化一些文件系统权限问题。注意不建议使用Windows 10 Enterprise LTSC 2021这类长期服务版作为开发环境。它们为了稳定性会大幅削减功能更新可能导致缺少UE4或VS2019所需的最新系统组件从而引发难以排查的依赖问题。2.2 开发工具Visual Studio 2019的组件选择艺术Visual Studio 2019是编译UE4和AirSim的指定工具。但安装VS2019时默认选项是不够的我们必须手动勾选必要的组件。下载与安装从微软官网下载Visual Studio 2019 Community版免费且功能完整。运行安装程序在选择工作负载时必须勾选“使用C的桌面开发”。关键组件明细在右侧的“安装详细信息”中以下组件是编译UE4和AirSim所必需的请务必确保选中MSVC v142 - VS 2019 C x64/x86 生成工具Windows 10 SDK (10.0.18362.0 或更高版本)。这里是个关键点UE4.24需要特定版本的Windows SDK。我强烈建议同时勾选一个版本稍旧的SDK例如10.0.18362.0因为UE4.24的构建脚本可能更适配它。你也可以在安装后通过Visual Studio Installer来添加多个Windows SDK版本。C CMake 工具用于 Windows 的 C CMake 工具测试工具核心功能 - 测试适配器适用于最新 v142 生成工具的 C ATL (x86 x64)适用于最新 v142 生成工具的 C MFC (x86 x64)安装路径尽量避免安装路径中包含中文或空格使用默认路径C:\Program Files (x86)\Microsoft Visual Studio\2019\Community是最稳妥的选择。安装完成后建议打开一次Visual Studio 2019让它完成初始配置。然后在开始菜单中找到“x64 Native Tools Command Prompt for VS 2019”并运行一次。这个命令提示符环境配置了正确的编译器和库路径后续我们可能会用到。2.3 游戏引擎获取特定版本的Unreal Engine 4.24UE4不像普通软件那样直接下载安装包。我们需要通过Epic Games启动器来获取指定版本的源代码并进行编译。这是整个流程中最耗时但也最关键的一步。安装Epic Games启动器从Epic Games官网下载并安装启动器注册/登录你的Epic账户。关联GitHub账户在启动器的“设置”-“连接”中关联你的GitHub账户。这是下载UE4源代码的必要条件。切换至“库”标签在左侧导航栏选择“库”向下滚动到“引擎版本”部分。添加引擎版本点击“引擎版本”旁边的“”按钮在弹出的版本列表中选择“4.24”。请注意不要选择4.24.1、4.24.2等小版本就选择4.24。启动器会开始下载该版本的源代码。这个过程会下载约8GB的数据耗时取决于你的网速。编译UE4下载完成后点击对应版本旁边的“...”按钮选择“选项”。在“目标平台”下确保“Win64”被选中。然后关闭选项窗口点击“启动”按钮。第一次启动实际上会触发引擎的编译过程而不是直接打开编辑器。系统会弹出一个命令行窗口开始漫长的编译通常需要1-2小时取决于电脑性能。请耐心等待直到命令行窗口自动关闭Epic Games启动器显示“运行中”状态。此时UE4.24才真正安装编译完成。实操心得编译UE4时确保电脑有足够的磁盘空间建议预留50GB以上并且不要进行其他高负载任务。编译过程CPU占用率会很高风扇狂转是正常现象。如果编译中途失败可以尝试以管理员身份运行Epic Games启动器或者检查系统环境变量是否有异常。3. 核心编译流程从源码到可用的AirSim插件环境就绪后我们正式进入AirSim的编译环节。这个过程可以分解为三个主要阶段获取正确版本的AirSim源码、使用VS2019生成项目文件、以及最终编译生成插件二进制文件。3.1 获取与准备AirSim 1.3.1源码AirSim的版本必须与UE4.24匹配。1.3.1版本是经过验证与UE4.24兼容性良好的一个稳定版本。使用Git克隆代码打开命令行CMD或PowerShell导航到你希望存放项目的目录例如D:\Projects。cd D:\Projects克隆特定标签的代码我们不克隆默认的主分支而是直接克隆对应1.3.1版本的标签。这能确保代码的绝对一致性。git clone https://github.com/microsoft/AirSim.git cd AirSim git checkout v1.3.1执行git checkout v1.3.1后终端会显示Note: switching to v1.3.1...表示已成功切换到1.3.1版本的代码快照。初始化子模块AirSim依赖一些第三方库它们作为Git子模块管理。必须同步这些子模块。git submodule update --init --recursive这一步会下载rpclib、MavLink等依赖库需要一定时间。3.2 运行编译脚本与项目生成AirSim提供了一个便捷的编译脚本build.cmd它会自动调用CMake和Visual Studio来配置和生成项目。以管理员身份运行“VS2019的x64本机工具命令提示符”在Windows开始菜单中搜索“x64 Native Tools Command Prompt for VS 2019”右键选择“以管理员身份运行”。这一步非常重要因为编译过程中可能需要创建符号链接或写入受保护目录管理员权限可以避免很多权限错误。导航到AirSim源码目录在上一步打开的命令行中切换到你的AirSim目录。cd D:\Projects\AirSim执行编译脚本运行以下命令。--vs2019参数指定使用VS2019--ue4参数需要指向你编译好的UE4.24的根目录。.\build.cmd --vs2019 --ue4 C:\Program Files\Epic Games\UE_4.24请将上述路径替换为你电脑上UE_4.24的实际安装路径。通常Epic Games启动器会将引擎安装在C:\Program Files\Epic Games\下。这个build.cmd脚本会执行一系列操作检查环境变量和依赖。调用CMake根据--ue4参数提供的路径定位UE4的构建工具链。生成适用于VS2019的解决方案文件.sln。自动调用MSBuildVisual Studio的构建工具开始编译AirSim的核心库。在脚本运行过程中你会看到大量的编译输出信息。如果一切顺利最终会出现Build succeeded或类似的成功提示。编译产物主要是AirSim.lib、AirSim.dll等会输出到AirSim\build\output目录下。3.3 生成Unreal插件上一步编译的是AirSim的核心库。要让它在Unreal Editor中作为插件使用还需要生成插件文件。运行插件生成脚本在同一个管理员命令行中运行.\run.ps1 --ue4 C:\Program Files\Epic Games\UE_4.24同样请替换为你的UE4.24路径。这个PowerShell脚本会将编译好的库文件复制到正确位置。生成最终的Unreal插件包位于AirSim\Unreal\Plugins\AirSim。验证插件完成上述步骤后你可以检查AirSim\Unreal\Plugins\AirSim目录。里面应该包含Source、Resources、Content等文件夹以及一个AirSim.uplugin文件。这个目录就是可以放入任何UE4.24项目中使用AirSim插件。4. 常见编译错误全解析与解决方案即使按照上述步骤操作你也可能遇到一些错误。下面我整理了在这个特定版本组合下最常见的几个错误及其解决方案。4.1 错误fatal error C1083: Cannot open include file: corecrt.h: No such file or directory或无法打开 ucrt\stdio.h这是最经典的Windows SDK路径问题。原因Visual Studio找不到正确版本的Windows SDK头文件。可能是安装了多个SDK版本环境变量指向了错误的版本或者UE4构建系统期望的SDK版本未安装。解决方案打开Visual Studio Installer点击“修改”你的VS2019。在“单个组件”选项卡中搜索“Windows 10 SDK”。确保安装了版本10.0.18362.0或10.0.17763.0。如果已安装可以尝试额外安装一个更新的版本如10.0.19041.0但编译时可能需要指定版本。更根本的解决方法是在运行build.cmd时显式指定SDK版本。但这需要修改AirSim的构建脚本对新手不友好。最稳妥的办法是确保系统只安装了上述推荐的SDK版本并通过Windows Update保持系统最新。4.2 错误LINK : fatal error LNK1104: cannot open file xxx.lib链接器找不到必要的库文件。原因通常是第三方依赖库如rpclib没有正确编译或者其路径没有被包含到链接器搜索路径中。解决方案确保你严格按照步骤执行了git submodule update --init --recursive。删除AirSim目录下的build文件夹和cmake生成的缓存文件如CMakeCache.txt然后重新运行build.cmd。这能确保从干净的状态开始构建。检查是否在以管理员权限运行VS2019的命令行工具。非管理员权限有时无法在特定目录创建文件或符号链接。4.3 错误UnrealBuildTool相关错误提示找不到UE4安装原因build.cmd脚本中的--ue4参数路径不正确或者路径中包含空格、中文字符没有用引号括好。解决方案仔细核对UE4.24的安装路径。使用文件资源管理器直接导航到Epic Games\UE_4.24目录确认Engine文件夹存在。在命令行中确保路径被双引号包围尤其是路径中包含空格Program Files时。--ue4 C:\Program Files\Epic Games\UE_4.24。可以尝试在命令中直接使用UE4的构建工具C:\Program Files\Epic Games\UE_4.24\Engine\Build\BatchFiles\Build.bat。但这需要更复杂的参数建议还是修复--ue4参数。4.4 错误Git子模块更新失败或网络超时原因rpclib等子模块的仓库托管在GitHub上国内网络访问可能不稳定。解决方案配置Git的HTTP/HTTPS代理。如果你有可用的代理可以在命令行中设置git config --global http.proxy http://your-proxy:port git config --global https.proxy https://your-proxy:port如果代理不可用可以尝试多次执行git submodule update --init --recursive命令。终极方案手动下载。根据错误提示找到失败的子模块仓库地址如https://github.com/rpclib/rpclib.git在浏览器中访问下载ZIP包解压到AirSim目录下对应的路径如AirSim\external\rpclib然后再次尝试执行子模块更新命令。4.5 错误编译过程中PowerShell执行策略禁止运行脚本原因Windows系统默认禁止运行未签名的PowerShell脚本如run.ps1。解决方案以管理员身份打开PowerShell执行以下命令更改执行策略仅限当前会话Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process然后在这个PowerShell窗口中导航到AirSim目录再执行.\run.ps1命令。这样做只影响当前窗口不会永久降低系统安全性。5. 插件集成与项目测试成功编译出插件后我们还需要将其集成到一个Unreal项目中并运行一个简单测试来验证一切正常。5.1 创建Unreal项目并集成插件启动Unreal Engine 4.24通过Epic Games启动器启动刚才编译好的UE4.24。创建新项目选择“游戏”类别然后选择“空白”模板。在项目设置中确保项目类型是“C”而不是“蓝图”并选择一个合适的存放位置和项目名称例如MyAirSimProject。点击“创建”UE4会为你生成一个基础的C项目并打开Visual Studio 2019解决方案。集成AirSim插件关闭Unreal Editor和Visual Studio。将之前编译好的插件文件夹AirSim\Unreal\Plugins\AirSim整个复制到你新建的Unreal项目的Plugins目录下。如果项目下没有Plugins文件夹就手动创建一个。 最终路径结构应类似于D:\UE_Projects\MyAirSimProject\Plugins\AirSim\AirSim.uplugin。重新生成项目文件右键点击项目的.uproject文件例如MyAirSimProject.uproject选择“Generate Visual Studio project files”。这会重新解析插件并更新VS解决方案。打开项目并启用插件双击.uproject文件打开项目。如果插件放置正确UE4会自动检测到它。你也可以在编辑器菜单栏点击“编辑”-“插件”在“已安装”列表中找到“AirSim”确保其复选框已被勾选启用。然后重启编辑器。5.2 运行示例场景验证最直接的验证方法是运行AirSim自带的示例。迁移示例内容在AirSim源码的Unreal\Environments目录下有多个示例环境文件夹例如Blocks。将这个Blocks文件夹整个复制到你的项目目录的Content文件夹下。打开关卡在UE4编辑器的内容浏览器中导航到Content/Blocks双击打开Blocks.umap关卡。设置游戏模式在关卡编辑器的“世界场景设置”面板中找到“游戏模式重载”点击“游戏模式基类”下拉框选择“AirSimGameMode”。如果找不到说明插件没有正确加载请检查插件目录和是否启用。播放测试点击编辑器上方的“播放”按钮。如果一切顺利你将看到一个简单的方块世界并且可以在终端或输出日志窗口中看到AirSim的启动信息表明仿真环境已经成功运行。此时你就可以通过AirSim的API默认通过本地网络端口41451来控制这个仿真世界中的车辆或无人机了。6. 高级配置与性能调优基础环境搭建完成后为了获得更好的开发体验和仿真性能可以进行一些优化配置。6.1 开发环境配置优化Visual Studio智能感知优化UE4项目代码量巨大可能导致VS的IntelliSense变慢甚至卡死。可以在VS中右键点击解决方案资源管理器中的项目选择“属性”-“NMake”-“IntelliSense”在“预处理器定义”中添加_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH。这能缓解一些因标准库版本差异导致的IntelliSense错误。使用Live Coding在UE4编辑器中启用“编译”-“实时编码”功能。这样在修改C代码并编译后无需重启编辑器即可看到部分更改效果极大提升迭代效率。但注意涉及插件核心类的修改可能仍需重启。配置启动参数在VS中调试UE4项目时可以在项目属性-“调试”-“命令参数”中设置一些启动参数。例如添加-ResX1280 -ResY720 -WINDOWED可以指定编辑器以窗口模式和较低分辨率启动节省系统资源。6.2 AirSim仿真性能调优AirSim仿真的性能主要消耗在图像渲染和物理计算上。图形设置降级在UE4编辑器中打开“项目设置”-“引擎”-“渲染”可以关闭或降低一些不影响算法测试的图形特性如将“后期处理”质量调低。关闭“环境光遮蔽”Ambient Occlusion。降低“阴影”质量或距离。使用更简单的抗锯齿如FXAA代替TAA。降低传感器频率在AirSim的配置文件settings.json中可以调整相机、激光雷达等传感器的更新频率CaptureSettings中的FPS。对于不需要高频数据的算法测试适当降低频率能显著提升性能。使用无头模式Headless Mode如果你不需要看到渲染窗口只进行数据交互可以在启动UE4编辑器或打包后的可执行文件时添加命令行参数-RenderOffScreen或-NullRHI。这将完全禁用渲染器极大提升性能并减少GPU占用适合在服务器上运行仿真。优化物理子步在settings.json的PhysicsEngine设置中调整Substep参数。增加子步数可以提高物理模拟精度但降低性能减少则反之。根据你的车辆模型和仿真需求找到一个平衡点。6.3 多车与场景管理当你需要测试多智能体协同或复杂的城市场景时管理变得重要。多车辆配置在settings.json中Vehicles对象下可以配置多个车辆每个都有独立的传感器套件和初始位置。通过API连接时使用不同的车辆名称如Car1,Car2进行控制。自定义环境构建Blocks环境只是一个起点。你可以使用UE4强大的编辑器构建任意复杂的3D场景。对于自动驾驶可以导入真实城市的OpenStreetMap数据并使用RoadRunner、Carla等工具辅助生成带车道线、交通标志的逼真道路网络。使用Python API进行批量测试AirSim提供了完善的Python客户端库。你可以编写Python脚本自动化执行一系列测试任务例如让车辆沿预定路径行驶在不同天气条件下通过API动态更改天气收集传感器数据并自动保存日志和图像。这非常适合回归测试和数据集生成。7. 从仿真到算法验证的工作流搭建环境搭建的最终目的是服务于算法开发。这里分享一个我常用的、基于AirSim的感知与控制算法测试工作流。7.1 数据采集与标注管道AirSim不仅能提供RGB图像还能直接获取深度图、语义分割图、实例分割图、表面法线等“真值”Ground Truth信息这为计算机视觉模型训练提供了极大便利。配置传感器在settings.json中为你的车辆添加所需的传感器。例如同时配置前向RGB相机、深度相机和语义分割相机。Cameras: { front_center: { CaptureSettings: [ { ImageType: 0, // Scene (RGB) Width: 640, Height: 480 }, { ImageType: 1, // DepthPlanner (深度图) Width: 640, Height: 480 }, { ImageType: 3, // Segmentation (语义分割) Width: 640, Height: 480 } ] } }编写采集脚本使用Python API控制车辆在场景中随机或按规划路径移动并在每个位姿同步触发所有传感器并保存数据。关键API调用包括simGetImages()和simSetVehiclePose()。数据同步保存确保为每一帧数据保存时间戳、车辆位姿位置和朝向以及所有传感器图像。可以使用ROS的bag格式、或简单的文件夹结构按时间戳命名图像和对应的位姿txt文件进行组织。7.2 与外部算法模块的联调AirSim作为一个仿真器其核心价值是与你的算法进行闭环测试。Python API 实时控制这是最常见的方式。你的感知/规划/控制算法运行在独立的Python进程中通过airsim库连接到AirSim默认localhost:41451。算法从AirSim获取传感器数据经过计算后将控制指令如油门、转向发送回AirSim驱动车辆。import airsim client airsim.CarClient() client.confirmConnection() # 获取图像 responses client.simGetImages([...]) # 你的算法处理 images... # 发送控制指令 car_controls airsim.CarControls(throttle0.5, steering0.1) client.setCarControls(car_controls)ROS Bridge如果你的算法栈基于ROSRobot Operating System可以使用AirSim官方提供的airsim_ros_pkgs包。它会将AirSim的传感器数据发布为ROS话题如/camera/rgb/imu同时订阅控制话题如/car_cmd来控制车辆。这样你可以直接使用ROS中现有的SLAM、导航、控制节点与AirSim交互。C 客户端集成对于性能要求极高或需要与现有C代码深度集成的场景可以直接使用AirSim的C客户端库将其链接到你的项目中实现进程内的高效通信。7.3 结果可视化与评估仿真测试需要定量评估。轨迹记录与对比通过API持续记录车辆的真实位姿simGetVehiclePose和期望位姿算法输出的目标轨迹。仿真结束后可以使用Matplotlib或ROS的rviz绘制轨迹对比图计算误差指标如平均绝对误差ATE、均方根误差RMSE。关键事件记录在Python脚本中监听碰撞事件simGetCollisionInfo、越界事件等。任何一次碰撞或违规都标志着测试失败并记录下发生时的场景上下文位置、速度、传感器快照用于后续分析。使用Unreal Editor的录制功能UE4编辑器自带“影片场景捕获”功能可以录制高质量的视频。你可以录制算法控制车辆运行的整个过程生成演示视频直观地展示算法表现。整个流程走下来你会发现虽然初期环境搭建有些繁琐但一旦这个稳定的“AirSim UE4.24 VS2019”环境就绪它就成为了一个极其强大的算法沙盒。你可以在这里安全、快速、低成本地迭代你的无人机飞控、自动驾驶感知模型或者机器人路径规划算法而不用担心真实世界中的硬件损坏、场地限制和安全风险。这节省的时间和资源远远超过了当初为配置环境所付出的努力。