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,而不是 VS2022?AirSim 1.3.1 的构建脚本(如
build.cmd)和 UE4 插件构建流程,与 VS2019 的工具链(MSVC v142)结合得最为紧密。使用 VS2022(MSVC 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.0?UE4.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.9:AirSim 的构建脚本和部分工具依赖 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.1HEAD 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命令,如果显示“不是内部或外部命令”,则证明环境不对。
- 现象:CMake 配置失败,提示找不到合适的编译器或
错误:Python 找不到或版本不对
- 现象:脚本一开始就报错,提示 Python 相关错误。
- 排查:在命令行输入
python --version,确认版本是 3.8 或 3.9,并且能正常显示。如果提示“找不到”,说明 Python 未正确加入 PATH。你需要手动将 Python 的安装目录(如C:\Python38)和其Scripts目录(如C:\Python38\Scripts)添加到系统的环境变量PATH中,然后重新打开开发人员命令提示符。
错误:git submodule 更新失败
- 现象:在编译初期,脚本尝试更新子模块(如 rpclib)时网络超时或失败。
- 解决:由于网络问题,可能需要手动初始化子模块。在运行
build.cmd前,可以先执行:
如果速度慢,可以尝试配置 git 使用代理,或者多次重试。git submodule update --init --recursive
错误:编译过程中出现 C++ 语法错误 (Cxxxx) 或链接错误 (LNKxxxx)
- 现象:这是最令人头疼的一类错误,通常指向代码问题。
- 排查:首先,再次确认你已通过
git checkout v1.3.1切换到了正确的版本。master分支的代码可能正在开发中,存在不稳定因素。其次,确保你的 UE4 版本是 4.27.2。如果错误与某个特定第三方库有关,可以尝试清理构建缓存:删除AirSim目录下的cmake_build或build文件夹(如果有),然后重新运行build.cmd。
实操心得:编译过程最好保持网络通畅。第一次编译时间较长,耐心等待。如果某个包下载失败,脚本可能会卡住,按
Ctrl+C中断后,重新运行build.cmd,它通常会从中断处继续。编译成功后,建议将整个AirSim文件夹备份一份,以后如果只是 UE4 项目配置出问题,可以直接使用这些编译好的插件文件。
4. 创建并配置 Unreal Engine 项目
插件编译好了,接下来我们需要一个 UE4 项目来“承载”这个插件,并创建一个可以运行的仿真场景。
4.1 生成 Blocks 示例项目
AirSim 源码中自带了一个经典的“方块世界”(Blocks)示例。我们用它来测试。
- 在刚才的 AirSim 目录下,进入示例环境目录:
cd Unreal\Environments\Blocks - 运行生成脚本:
这个脚本会做两件事:将编译好的 AirSim 插件复制到当前项目的update_from_git.batPlugins文件夹下;生成 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.json
AirSim 的行为通过一个 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,因为那是回环地址,只能本机访问。
- 如果 PX4 和 AirSim 运行在同一台 Windows 电脑上(例如 PX4 运行在 WSL2 或 Windows 本地编译的版本),这里填
Parameters: 这里可以覆盖 PX4 的一些参数。LPE_LAT和LPE_LON是初始的 GPS 经纬度,需要与你的仿真场景大致对应(Blocks 场景的默认坐标就是上面给出的)。
5.3 启动 PX4 SITL
这里假设你在同一台 Windows 机器上通过 WSL2 运行 PX4。这是非常常见的配置。
在 WSL2 终端中,首先设置环境变量,告诉 PX4 AirSim 在哪里:
export PX4_SIM_HOST_ADDR=127.0.0.1(如果 AirSim 的
LocalHostIp填的是其他 IP,这里也要对应修改。)导航到你的 PX4-Autopilot 源码目录,启动 SITL:
cd ~/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 4560 | 1. 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 无法连接 PX4 | 1. 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 包:
注意:这个包只包含客户端 API,不包含仿真器本身。pip install airsim - 编写一个简单的测试脚本
test.py:import 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,通常都能找到解决方案。
