Windows 10 下 AirSim 1.3.1 与 UE4.27.2 编译配置全攻略

1. 项目概述与核心痛点如果你正在为无人机、自动驾驶或机器人研究寻找一个高保真的仿真环境AirSim 绝对是一个绕不开的名字。作为微软开源的仿真平台它基于虚幻引擎UE4构建提供了极其逼真的物理和视觉模拟。然而从“知道它好”到“真正能用上”中间隔着的往往是一道名为“环境配置”的鸿沟。特别是当你看到官方文档或网络上零散的教程提到需要 Visual Studio、特定版本的 UE4、Python、CMake 等一系列工具时那种无从下手的迷茫感我太懂了。我最近在 Windows 10 上成功编译配置了 AirSim 1.3.1 版本整个过程可以说是一路“踩坑”过来的。最大的“坑”莫过于 Visual Studio (VS) 和 Unreal Engine 4 (UE4) 的版本兼容性问题。AirSim 1.3.1 这个版本对编译环境有比较明确但又不那么广为人知的要求用错了版本轻则编译报错重则工程都无法生成。网上的教程要么年代久远要么只讲某一步缺乏一个贯穿始终、能避开所有常见陷阱的完整指南。所以我决定把这次从零开始、成功跑通 AirSim 仿真的全过程包括每一个步骤、每一个关键选择背后的原因、以及我踩过的每一个坑和解决方案详细地记录下来。这份指南的目标是“保姆级”力求让你只要跟着做就能在 Windows 10 上搭建起一个可编译、可运行、可连接外部飞控如 PX4的 AirSim 1.3.1 仿真环境。2. 环境准备精确的版本锁定与安装编译 AirSim 就像组装一台精密仪器每一个零件的型号都必须匹配。这一步走错了后面全是徒劳。我们的核心目标是为 AirSim 1.3.1 准备一个它“认识”且“喜欢”的编译工具链。2.1 操作系统与关键组件首先确保你的系统是Windows 10 64位版本 1909 或更高。我强烈推荐使用 20H2 或更新版本以确保系统底层库的完整性。AirSim 的编译过程会依赖一些较新的 Windows SDK 特性。你需要以管理员身份运行后续的安装程序和命令行。很多操作尤其是环境变量设置和系统级安装都需要管理员权限。2.2 Visual Studio 2019唯一推荐的选择这是第一个也是最重要的版本坑。AirSim 1.3.1 强烈推荐且最兼容的 IDE 是 Visual Studio 2019 (VS2019)。虽然有些教程提到了 VS2017 或 VS2022但根据我的实测和 AirSim 社区的大量反馈VS2019 是麻烦最少的。为什么是 VS2019而不是 VS2022AirSim 1.3.1 的构建脚本如build.cmd和 UE4 插件构建流程与 VS2019 的工具链MSVC v142结合得最为紧密。使用 VS2022MSVC v143可能会在链接阶段遇到一些诡异的 LNKxxxx 错误这些错误通常与 C 运行时库或标准库的版本不匹配有关排查起来非常耗时。为了求稳直接选择 VS2019。安装组件选择运行 VS2019 安装程序选择“使用 C 的桌面开发”工作负载。在右侧的“安装详细信息”中必须勾选以下两项MSVC v142 - VS 2019 C x64/x86 生成工具 (v14.29)这是核心编译器。Windows 10 SDK (10.0.19041.0 或更高版本)AirSim 和 UE4 都需要这个版本的 SDK。10.0.19041.0 是一个经过广泛测试的稳定版本。注意安装程序可能会默认勾选一个更高版本的 SDK如 10.0.20348.0请确保至少包含 19041.0。你可以同时勾选多个版本构建时会自动选择合适的。可选但建议的组件“用于 Windows 的 C CMake 工具”和“测试工具核心功能 - 测试工具”这些对后续的开发和调试有帮助。实操心得安装 VS 时如果硬盘空间充足建议把“用于 Windows 的 C CMake 工具”也装上。虽然 AirSim 主要用其自带的脚本但 CMake 在配置一些第三方依赖如果你需要修改 AirSim 底层时非常有用。安装路径尽量保持默认避免中文和空格。2.3 Unreal Engine 4.27黄金搭档这是第二个版本坑。与 AirSim 1.3.1 最匹配的 UE4 版本是 4.27.2。UE4 的版本迭代很快不同版本间的插件二进制接口ABI可能不兼容。用错了版本会导致编译出的 AirSim 插件无法被 UE4 编辑器加载。安装方式通过 Epic Games Launcher 安装是最佳途径。下载并安装 Epic Games Launcher。登录你的 Epic 账户需要注册一个。切换到“虚幻引擎”标签页点击“库”然后点击“引擎版本”旁的“”号。在版本选择中找到4.27.2并勾选。点击“安装”选择一个大容量的硬盘位置安装需要约 30GB 空间。为什么不是 4.26 或 5.0UE4.26 可能也能用但 AirSim 1.3.1 的代码库是针对 4.27 进行测试和优化的。UE5 则改动太大AirSim 官方尚未提供稳定支持强行编译会面临大量 API 变更导致的编译错误。2.4 其他必备工具Git用于克隆 AirSim 源代码。从 git-scm.com 下载并安装安装时记得勾选“Git from the command line and also from 3rd-party software”这样可以在系统任何地方使用git命令。Python 3.8 或 3.9AirSim 的构建脚本和部分工具依赖 Python。建议从 Python 官网安装 3.8.x 或 3.9.x 版本并在安装时务必勾选“Add Python to PATH”。避免使用 Python 3.10某些旧的 Python 包可能兼容性不佳。CMake ( 3.15)用于生成构建文件。可以从 cmake.org 下载安装程序同样记得将其bin目录添加到系统 PATH 环境变量中。注意事项所有工具的安装路径都不要包含中文或空格。像C:\Program Files这样的路径虽然常见但有时在命令行处理时可能会引发问题尽管现代工具大多已能处理。最稳妥的做法是安装到类似C:\Dev\UE_4.27、C:\Dev\Python39这样的自定义目录。3. 获取与编译 AirSim 源代码环境准备好后我们就可以开始动手编译 AirSim 的核心插件了。这一步是将 C 源代码转化为 UE4 能加载的二进制文件.dll和.lib。3.1 克隆源代码与准备打开VS2019 的开发人员命令提示符。你可以在开始菜单搜索 “Developer Command Prompt for VS 2019”。务必使用这个而不是普通的 CMD 或 PowerShell因为它会自动设置好 VS 的所有编译环境变量如cl.exe,link.exe的路径。在命令行中切换到你希望存放项目的目录例如D:\Projects。执行克隆命令git clone https://github.com/Microsoft/AirSim.git cd AirSim关键步骤切换到 1.3.1 版本默认克隆的是master分支可能包含更新的、不稳定的代码。我们需要切换到稳定的 1.3.1 标签。git checkout v1.3.1执行后命令行会提示HEAD is now at ...表示切换成功。3.2 执行编译脚本在AirSim根目录下运行构建脚本build.cmd这个build.cmd脚本会自动完成以下工作检查环境Python, CMake 等。使用 CMake 配置Configure和生成Generate针对 VS2019 的解决方案文件.sln。调用msbuild编译整个解决方案生成 AirSim 插件。编译过程详解与可能的问题过程脚本会先编译一个名为rpclib的第三方网络库这是 AirSim 用于 RPC 通信的基础。然后编译 AirSim 的核心模块。整个过程在性能较好的电脑上可能需要 10-20 分钟。成功标志当你在命令行最后看到Build succeeded或类似的成功提示并且没有红色的错误信息时就说明编译成功了。输出位置编译生成的插件文件主要是AirSim.lib、AirSim.dll以及一些.pdb调试文件会位于AirSim\Unreal\Plugins\AirSim\Binaries\Win64目录下。同时在AirSim\Unreal\Environments目录下会准备好一些示例环境。3.3 编译常见错误与排查即使版本都选对了编译过程也可能出错。以下是我遇到过的几个典型问题错误找不到 Windows SDK 或 MSVC 工具集现象CMake 配置失败提示找不到合适的编译器或WindowsSDKDir变量未定义。排查确保你是在VS2019 开发人员命令提示符中运行命令。普通终端没有必要的环境变量。可以输入cl命令如果显示“不是内部或外部命令”则证明环境不对。错误Python 找不到或版本不对现象脚本一开始就报错提示 Python 相关错误。排查在命令行输入python --version确认版本是 3.8 或 3.9并且能正常显示。如果提示“找不到”说明 Python 未正确加入 PATH。你需要手动将 Python 的安装目录如C:\Python38和其Scripts目录如C:\Python38\Scripts添加到系统的环境变量PATH中然后重新打开开发人员命令提示符。错误git submodule 更新失败现象在编译初期脚本尝试更新子模块如 rpclib时网络超时或失败。解决由于网络问题可能需要手动初始化子模块。在运行build.cmd前可以先执行git submodule update --init --recursive如果速度慢可以尝试配置 git 使用代理或者多次重试。错误编译过程中出现 C 语法错误 (Cxxxx) 或链接错误 (LNKxxxx)现象这是最令人头疼的一类错误通常指向代码问题。排查首先再次确认你已通过git checkout v1.3.1切换到了正确的版本。master分支的代码可能正在开发中存在不稳定因素。其次确保你的 UE4 版本是 4.27.2。如果错误与某个特定第三方库有关可以尝试清理构建缓存删除AirSim目录下的cmake_build或build文件夹如果有然后重新运行build.cmd。实操心得编译过程最好保持网络通畅。第一次编译时间较长耐心等待。如果某个包下载失败脚本可能会卡住按CtrlC中断后重新运行build.cmd它通常会从中断处继续。编译成功后建议将整个AirSim文件夹备份一份以后如果只是 UE4 项目配置出问题可以直接使用这些编译好的插件文件。4. 创建并配置 Unreal Engine 项目插件编译好了接下来我们需要一个 UE4 项目来“承载”这个插件并创建一个可以运行的仿真场景。4.1 生成 Blocks 示例项目AirSim 源码中自带了一个经典的“方块世界”Blocks示例。我们用它来测试。在刚才的 AirSim 目录下进入示例环境目录cd Unreal\Environments\Blocks运行生成脚本update_from_git.bat这个脚本会做两件事将编译好的 AirSim 插件复制到当前项目的Plugins文件夹下生成 UE4 的项目文件Blocks.sln和Blocks.uproject。4.2 用 Visual Studio 打开并编译项目双击生成的Blocks.sln文件它会在 VS2019 中打开。在 VS 顶部的工具栏中找到解决方案配置下拉菜单选择DebugGame_Editor和Win64。这是用于在编辑器内进行调试的配置也是运行 AirSim 仿真最常用的配置。在“解决方案资源管理器”中右键点击Blocks项目注意是第一个不是BlocksEditor选择“设为启动项目”。按下F5键或者点击菜单栏的“调试 - 开始调试”。这将启动 UE4 编辑器的编译和加载过程。首次编译 UE4 项目这又是一个耗时较长的过程可能 10-30 分钟取决于电脑性能。UE4 需要编译项目本身的代码模块以及 AirSim 插件在编辑器模式下的代码。状态栏会显示编译进度。4.3 在 UE4 编辑器中运行仿真当 UE4 编辑器成功启动后你会看到 Blocks 场景——一个由彩色方块构成的简单环境。确保“内容浏览器”中打开了Blocks项目的Content文件夹。你应该能看到一些地图文件如Blocks.umap。点击编辑器工具栏上的“播放”按钮一个绿色的三角形。此时视口会进入“模拟”模式。在弹出的模式选择窗口中选择“Multirotor”多旋翼无人机或“Car”汽车。你会看到无人机或汽车出现在场景中。此时你可以使用键盘W/A/S/D 控制汽车方向键控制无人机视角或后续通过 API 来控制载具。同时在屏幕左上角你会看到 AirSim 的状态信息例如Waiting for TCP connection on port 4560这说明 AirSim 的仿真服务器已经启动正在等待外部客户端如 PX4 飞控软件的连接。恭喜至此一个本地的、独立的 AirSim 仿真环境已经搭建并运行成功。你可以在这个环境里进行基本的视觉和物理仿真测试。注意事项如果点击播放后编辑器卡住或崩溃请检查项目配置是否为DebugGame_Editor和Win64用Development_Editor也可以但DebugGame包含了更多调试信息。插件是否正确加载在编辑器菜单栏选择“编辑 - 插件”在“已安装”列表里搜索“AirSim”确保它已被启用。显卡驱动是否更新UE4 对显卡驱动有一定要求过旧的驱动可能导致渲染问题。5. 高级配置连接 PX4 进行硬件在环仿真对于无人机研究者仅仅在 UE4 编辑器里手动控制是不够的我们需要 AirSim 能够与真实的飞控软件如 PX4通信实现硬件在环HITL或软件在环SITL仿真。这是 AirSim 最强大的功能之一。5.1 理解通信架构在连接之前必须理解 AirSim 和 PX4 的角色PX4作为飞控软件它运行一个“仿真实例”例如jmavsim或gazebo但实际上它需要连接到一个“仿真器”来获取传感器数据和发送电机指令。在这个架构里PX4 是服务器Server。AirSim作为高保真仿真器它模拟无人机模型、物理、传感器和环境。AirSim 是客户端Client它主动去连接 PX4 的服务器端口。所以启动顺序必须是先启动 AirSim并使其进入等待连接状态再启动 PX4。5.2 配置 AirSim 的 Settings.jsonAirSim 的行为通过一个 JSON 配置文件来控制。这个文件需要放在固定位置C:\Users\你的用户名\Documents\AirSim\settings.json。如果AirSim文件夹不存在就手动创建它。以下是一个用于连接 PX4 SITL 的基本配置示例{ SettingsVersion: 1.2, SimMode: Multirotor, ClockType: SteppableClock, Vehicles: { PX4: { VehicleType: PX4Multirotor, UseSerial: false, UseTcp: true, TcpPort: 4560, ControlIp: remote, ControlPortLocal: 14540, ControlPortRemote: 14580, LocalHostIp: 127.0.0.1, Parameters: { NAV_RCL_ACT: 0, NAV_DLL_ACT: 0, COM_OBL_RC_ACT: 1, LPE_LAT: 47.641468, LPE_LON: -122.140165 } } } }关键字段解析SimMode:Multirotor对应无人机Car对应汽车。ClockType:SteppableClock允许仿真步进对于与外部飞控同步至关重要。Vehicles.PX4.VehicleType: 必须指定为PX4Multirotor。TcpPort:4560这是 PX4 SITL 默认监听的端口AirSim 会去连接这个端口。LocalHostIp:这是最容易出错的地方如果 PX4 和 AirSim 运行在同一台 Windows 电脑上例如 PX4 运行在 WSL2 或 Windows 本地编译的版本这里填127.0.0.1。如果 PX4 运行在另一台电脑或虚拟机里这里需要填写 Windows 主机在该网络中的 IP 地址例如192.168.1.100。不能填127.0.0.1因为那是回环地址只能本机访问。Parameters: 这里可以覆盖 PX4 的一些参数。LPE_LAT和LPE_LON是初始的 GPS 经纬度需要与你的仿真场景大致对应Blocks 场景的默认坐标就是上面给出的。5.3 启动 PX4 SITL这里假设你在同一台 Windows 机器上通过 WSL2 运行 PX4。这是非常常见的配置。在 WSL2 终端中首先设置环境变量告诉 PX4 AirSim 在哪里export PX4_SIM_HOST_ADDR127.0.0.1如果 AirSim 的LocalHostIp填的是其他 IP这里也要对应修改。导航到你的 PX4-Autopilot 源码目录启动 SITLcd ~/PX4-Autopilot make px4_sitl_default none_irispx4_sitl_default是目标。none_iris表示不使用图形前端如 jMAVSim 或 Gazebo因为我们用 AirSim 作为前端。iris是机型。如果一切正常PX4 会开始启动并在最后输出类似INFO [simulator] Got initial simulation connection的信息这表明它已经成功连接到了 AirSim。5.4 使用 QGroundControl 监控下载并运行 QGroundControl (QGC)。正常情况下QGC 会自动通过 UDP 端口 14550 发现并连接到正在运行的 PX4 SITL 实例。连接成功后QGC 界面左下角会显示飞行状态如 “Armed” / “Disarmed”你可以在 QGC 上规划任务、切换飞行模式并看到 AirSim 场景中的无人机做出相应反应。5.5 连接故障排查表现象可能原因排查步骤AirSim 一直显示Waiting for TCP connection on port 45601. PX4 未启动。2. 防火墙阻止了连接。3.LocalHostIp配置错误。1. 确认 PX4 SITL 已启动并检查其日志。2. 临时关闭 Windows 防火墙或为 4560 端口添加入站规则。3. 在 WSL 中ping $PX4_SIM_HOST_ADDR必须能通。PX4 启动失败提示连接超时或拒绝连接1. AirSim 未先启动并进入等待状态。2. 端口被占用。1.严格遵守启动顺序先 AirSim (Play)后 PX4。2. 检查是否有其他程序占用了 4560 端口 (netstat -ano | findstr :4560)。QGC 无法连接 PX41. PX4 未正确启动。2. QGC 连接方式错误。1. 检查 PX4 终端是否有错误。2. 在 QGC 中尝试手动添加连接类型 UDP端口 14550。无人机在 AirSim 中不动或物理表现怪异1.SimMode或VehicleType设置错误。2. PX4 参数未正确同步。1. 确认 JSON 配置中载具类型与仿真模式匹配。2. 在 QGC 的参数页面检查SYS_AUTOSTART是否为 4001适用于 Iris 机型。实操心得连接问题 90% 出在 IP 地址和启动顺序上。务必理解“AirSim 是客户端连接 PX4 服务器”这一模型。在复杂网络环境如公司内网、多网卡下使用ipconfig命令仔细查看 Windows 主机的正确 IP 地址并确保 PX4 所在的环境WSL/虚拟机/另一台主机能 ping 通这个 IP。第一次成功连接后建议将正确的settings.json文件备份。6. 性能优化与日常开发调试技巧环境搭好了仿真跑起来了接下来就是如何更高效地使用和开发了。6.1 提升仿真运行效率图形设置调整在 UE4 编辑器中播放时帧率FPS直接影响仿真的实时性。可以尝试在编辑器“设置 - 引擎可扩展性设置”中将画质调整为“低”或“中”关闭抗锯齿、动态阴影等耗资源选项。使用独立进程在 UE4 编辑器中点击“播放”旁边的下拉箭头选择“独立进程游戏”。这会将仿真运行在一个单独的.exe进程中稳定性更好且关闭仿真时不会连带关闭编辑器。关闭不必要的插件在“编辑 - 插件”中禁用项目中用不到的插件可以减少内存占用和启动时间。6.2 代码修改与重新编译如果你需要修改 AirSim 的 C 源代码例如添加新的传感器模型在AirSim源码目录下修改代码。重新打开VS2019 开发人员命令提示符导航到AirSim目录。再次运行build.cmd。脚本会检测到更改并重新编译。编译成功后需要重新生成 UE4 项目。进入Unreal\Environments\Blocks目录再次运行update_from_git.bat。这个脚本会将新编译的插件二进制文件复制到项目里。在 VS2019 中重新编译并运行Blocks项目即可。6.3 使用 Python API 进行外部控制AirSim 提供了强大的 Python API让你可以脱离 UE4 编辑器用脚本控制仿真。安装 AirSim Python 包pip install airsim注意这个包只包含客户端 API不包含仿真器本身。编写一个简单的测试脚本test.pyimport airsim import time # 连接到仿真器 client airsim.MultirotorClient() client.confirmConnection() # 解锁并起飞 client.enableApiControl(True) client.armDisarm(True) client.takeoffAsync().join() # 飞行到指定位置 client.moveToPositionAsync(10, 10, -10, 5).join() # (x, y, z, velocity) # 悬停并降落 time.sleep(2) client.landAsync().join() client.armDisarm(False) client.enableApiControl(False)确保 AirSim 仿真正在运行UE4 编辑器处于播放状态或独立进程正在运行。在命令行运行python test.py你会看到无人机自动执行飞行任务。6.4 日志与调试AirSim 日志日志文件默认位于C:\Users\用户名\Documents\AirSim\airsim.log。当遇到连接问题或 API 调用错误时首先查看这个文件里面包含了非常详细的通信和状态信息。UE4 输出日志在 UE4 编辑器中窗口菜单下打开“输出日志”可以查看引擎和插件的实时日志。PX4 日志PX4 SITL 会在终端输出大量日志。关注INFO [simulator]和ERROR级别的信息。整个配置过程确实繁琐但一旦打通AirSim 为你提供的将是一个功能强大、近乎真实的机器人仿真沙盒。从视觉感知算法测试到复杂的多机协同策略验证它都能提供坚实的支撑。最关键的就是开头那几步VS2019、UE4.27.2、版本对号入座后续的很多问题都会迎刃而解。希望这份详细的记录能帮你避开我踩过的那些坑顺利开启你的仿真之旅。如果在配置过程中遇到新的问题多查看日志善用搜索引擎和 AirSim 的 GitHub Issues通常都能找到解决方案。