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++ 的桌面开发”工作负载。在右侧的“安装详细信息”中，必须勾选以下两项：
  1. MSVC v142 - VS 2019 C++ x64/x86 生成工具 (v14.29)：这是核心编译器。
  2. 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 安装是最佳途径。
  1. 下载并安装 Epic Games Launcher。
  2. 登录你的 Epic 账户（需要注册一个）。
  3. 切换到“虚幻引擎”标签页，点击“库”，然后点击“引擎版本”旁的“+”号。
  4. 在版本选择中，找到4.27.2并勾选。点击“安装”，选择一个大容量的硬盘位置（安装需要约 30GB 空间）。
• 为什么不是 4.26 或 5.0？UE4.26 可能也能用，但 AirSim 1.3.1 的代码库是针对 4.27 进行测试和优化的。UE5 则改动太大，AirSim 官方尚未提供稳定支持，强行编译会面临大量 API 变更导致的编译错误。

2.4 其他必备工具

1. Git：用于克隆 AirSim 源代码。从 git-scm.com 下载并安装，安装时记得勾选“Git from the command line and also from 3rd-party software”，这样可以在系统任何地方使用git命令。
2. Python 3.8 或 3.9：AirSim 的构建脚本和部分工具依赖 Python。建议从 Python 官网安装 3.8.x 或 3.9.x 版本，并在安装时务必勾选“Add Python to PATH”。避免使用 Python 3.10+，某些旧的 Python 包可能兼容性不佳。
3. 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 克隆源代码与准备

1. 打开VS2019 的开发人员命令提示符。你可以在开始菜单搜索 “Developer Command Prompt for VS 2019”。务必使用这个，而不是普通的 CMD 或 PowerShell，因为它会自动设置好 VS 的所有编译环境变量（如cl.exe,link.exe的路径）。
2. 在命令行中，切换到你希望存放项目的目录，例如D:\Projects。
3. 执行克隆命令：

   git clone https://github.com/Microsoft/AirSim.git cd AirSim

4. （关键步骤）切换到 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 编译常见错误与排查

即使版本都选对了，编译过程也可能出错。以下是我遇到过的几个典型问题：

1. 错误：找不到 Windows SDK 或 MSVC 工具集

   • 现象：CMake 配置失败，提示找不到合适的编译器或WindowsSDKDir变量未定义。
   • 排查：确保你是在VS2019 开发人员命令提示符中运行命令。普通终端没有必要的环境变量。可以输入cl命令，如果显示“不是内部或外部命令”，则证明环境不对。

2. 错误：Python 找不到或版本不对

   • 现象：脚本一开始就报错，提示 Python 相关错误。
   • 排查：在命令行输入python --version，确认版本是 3.8 或 3.9，并且能正常显示。如果提示“找不到”，说明 Python 未正确加入 PATH。你需要手动将 Python 的安装目录（如C:\Python38）和其Scripts目录（如C:\Python38\Scripts）添加到系统的环境变量PATH中，然后重新打开开发人员命令提示符。

3. 错误：git submodule 更新失败

   • 现象：在编译初期，脚本尝试更新子模块（如 rpclib）时网络超时或失败。
   • 解决：由于网络问题，可能需要手动初始化子模块。在运行build.cmd前，可以先执行：

     git submodule update --init --recursive

     如果速度慢，可以尝试配置 git 使用代理，或者多次重试。

4. 错误：编译过程中出现 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）示例。我们用它来测试。

1. 在刚才的 AirSim 目录下，进入示例环境目录：

   cd Unreal\Environments\Blocks

2. 运行生成脚本：

   update_from_git.bat

   这个脚本会做两件事：将编译好的 AirSim 插件复制到当前项目的Plugins文件夹下；生成 UE4 的项目文件Blocks.sln和Blocks.uproject。

4.2 用 Visual Studio 打开并编译项目

1. 双击生成的Blocks.sln文件，它会在 VS2019 中打开。
2. 在 VS 顶部的工具栏中，找到解决方案配置下拉菜单，选择DebugGame_Editor和Win64。这是用于在编辑器内进行调试的配置，也是运行 AirSim 仿真最常用的配置。
3. 在“解决方案资源管理器”中，右键点击Blocks项目（注意是第一个，不是BlocksEditor），选择“设为启动项目”。
4. 按下F5键，或者点击菜单栏的“调试 -> 开始调试”。这将启动 UE4 编辑器的编译和加载过程。

首次编译 UE4 项目：这又是一个耗时较长的过程（可能 10-30 分钟，取决于电脑性能）。UE4 需要编译项目本身的代码模块以及 AirSim 插件在编辑器模式下的代码。状态栏会显示编译进度。

4.3 在 UE4 编辑器中运行仿真

1. 当 UE4 编辑器成功启动后，你会看到 Blocks 场景——一个由彩色方块构成的简单环境。
2. 确保“内容浏览器”中打开了Blocks项目的Content文件夹。你应该能看到一些地图文件，如Blocks.umap。
3. 点击编辑器工具栏上的“播放”按钮（一个绿色的三角形）。此时，视口会进入“模拟”模式。
4. 在弹出的模式选择窗口中，选择“Multirotor”（多旋翼无人机）或“Car”（汽车）。你会看到无人机或汽车出现在场景中。
5. 此时，你可以使用键盘（W/A/S/D 控制汽车，方向键控制无人机视角）或后续通过 API 来控制载具。同时，在屏幕左上角，你会看到 AirSim 的状态信息，例如Waiting for TCP connection on port 4560，这说明 AirSim 的仿真服务器已经启动，正在等待外部客户端（如 PX4 飞控软件）的连接。

恭喜！至此，一个本地的、独立的 AirSim 仿真环境已经搭建并运行成功。你可以在这个环境里进行基本的视觉和物理仿真测试。

注意事项：如果点击播放后，编辑器卡住或崩溃，请检查：

1. 项目配置是否为DebugGame_Editor和Win64？用Development_Editor也可以，但DebugGame包含了更多调试信息。
2. 插件是否正确加载？在编辑器菜单栏选择“编辑 -> 插件”，在“已安装”列表里搜索“AirSim”，确保它已被启用。
3. 显卡驱动是否更新？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，因为那是回环地址，只能本机访问。
• Parameters: 这里可以覆盖 PX4 的一些参数。LPE_LAT和LPE_LON是初始的 GPS 经纬度，需要与你的仿真场景大致对应（Blocks 场景的默认坐标就是上面给出的）。

5.3 启动 PX4 SITL

这里假设你在同一台 Windows 机器上通过 WSL2 运行 PX4。这是非常常见的配置。

1. 在 WSL2 终端中，首先设置环境变量，告诉 PX4 AirSim 在哪里：

   export PX4_SIM_HOST_ADDR=127.0.0.1

   （如果 AirSim 的LocalHostIp填的是其他 IP，这里也要对应修改。）

2. 导航到你的 PX4-Autopilot 源码目录，启动 SITL：

   cd ~/PX4-Autopilot make px4_sitl_default none_iris

   • px4_sitl_default是目标。
   • none_iris表示不使用图形前端（如 jMAVSim 或 Gazebo），因为我们用 AirSim 作为前端。iris是机型。

3. 如果一切正常，PX4 会开始启动，并在最后输出类似INFO [simulator] Got initial simulation connection的信息，这表明它已经成功连接到了 AirSim。

5.4 使用 QGroundControl 监控

1. 下载并运行 QGroundControl (QGC)。
2. 正常情况下，QGC 会自动通过 UDP 端口 14550 发现并连接到正在运行的 PX4 SITL 实例。
3. 连接成功后，QGC 界面左下角会显示飞行状态（如 “Armed” / “Disarmed”），你可以在 QGC 上规划任务、切换飞行模式，并看到 AirSim 场景中的无人机做出相应反应。

5.5 连接故障排查表

实操心得：连接问题 90% 出在 IP 地址和启动顺序上。务必理解“AirSim 是客户端，连接 PX4 服务器”这一模型。在复杂网络环境（如公司内网、多网卡）下，使用ipconfig命令仔细查看 Windows 主机的正确 IP 地址，并确保 PX4 所在的环境（WSL/虚拟机/另一台主机）能 ping 通这个 IP。第一次成功连接后，建议将正确的settings.json文件备份。

6. 性能优化与日常开发调试技巧

环境搭好了，仿真跑起来了，接下来就是如何更高效地使用和开发了。

6.1 提升仿真运行效率

• 图形设置调整：在 UE4 编辑器中播放时，帧率（FPS）直接影响仿真的实时性。可以尝试在编辑器“设置 -> 引擎可扩展性设置”中，将画质调整为“低”或“中”，关闭抗锯齿、动态阴影等耗资源选项。
• 使用独立进程：在 UE4 编辑器中点击“播放”旁边的下拉箭头，选择“独立进程游戏”。这会将仿真运行在一个单独的.exe进程中，稳定性更好，且关闭仿真时不会连带关闭编辑器。
• 关闭不必要的插件：在“编辑 -> 插件”中，禁用项目中用不到的插件，可以减少内存占用和启动时间。

6.2 代码修改与重新编译

如果你需要修改 AirSim 的 C++ 源代码（例如添加新的传感器模型）：

1. 在AirSim源码目录下修改代码。
2. 重新打开VS2019 开发人员命令提示符，导航到AirSim目录。
3. 再次运行build.cmd。脚本会检测到更改并重新编译。
4. 编译成功后，需要重新生成 UE4 项目。进入Unreal\Environments\Blocks目录，再次运行update_from_git.bat。这个脚本会将新编译的插件二进制文件复制到项目里。
5. 在 VS2019 中重新编译并运行Blocks项目即可。

6.3 使用 Python API 进行外部控制

AirSim 提供了强大的 Python API，让你可以脱离 UE4 编辑器，用脚本控制仿真。

1. 安装 AirSim Python 包：

   pip install airsim

   注意：这个包只包含客户端 API，不包含仿真器本身。
2. 编写一个简单的测试脚本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)

3. 确保 AirSim 仿真正在运行（UE4 编辑器处于播放状态，或独立进程正在运行）。
4. 在命令行运行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，通常都能找到解决方案。