UE4.27集成AirSim插件：无人机仿真项目C++配置全攻略

1. 项目概述与核心挑战

最近在做一个无人机仿真相关的项目，核心需求是在UE4.27引擎里，通过C++代码驱动一个高保真的飞行器模型，并接入真实的飞控算法进行闭环测试。AirSim这个由微软开源的仿真平台自然就成了首选，它原生支持PX4和ArduPilot，物理和传感器模型都比较靠谱。但说实话，把AirSim插件集成到一个已有的、或者新建的UE4.27 C++项目里，这个过程远没有官方文档描述的那么“开箱即用”。我前后折腾了快一周，踩遍了从环境变量、编译选项到uproject配置的几乎所有坑，才终于让插件在编辑器里正常加载，并且能用自己的C++代码去调用它的API。这篇指南就是把我趟过的这些雷区，以及最终成功的配置细节，完整地记录下来。如果你也正在做类似的事情，无论是做无人机算法验证、自动驾驶仿真，还是任何需要将AirSim作为仿真后端集成到自定义UE4项目中的工作，这篇内容应该能帮你节省大量时间，避免在环境配置上无谓地消耗精力。

2. 前期环境准备与关键依赖梳理

在动手修改任何代码或配置文件之前，一个干净、正确的基础环境是成功的基石。很多人集成失败，第一步就栽在了这里。

2.1 编译环境与工具链锁定

首先，必须明确一个版本对应关系：AirSim v1.8.1是最后一个官方明确支持UE 4.27的稳定版本。后续的版本（如v1.9+）主要面向UE5，在UE4.27上编译会遇到大量API不兼容的问题。所以，请务必从AirSim的GitHub Release页面下载v1.8.1的源代码。

其次，编译工具链必须匹配。UE4.27默认使用Visual Studio 2019和Windows 10 SDK (10.0.18362.0 或更高)。我强烈建议你通过Visual Studio Installer确认并安装以下工作负载：

• “使用C++的桌面开发”：这是基础。
• “使用C++的游戏开发”：这个工作负载会包含编译UE4所需的所有Windows SDK、.NET Framework等组件，避免后续出现找不到头文件的错误。

注意：即使你电脑上已经安装了VS2022，也请务必安装VS2019并作为编译UE4的主要工具。UE4对编译器版本非常敏感，混用会导致难以排查的链接错误。

2.2 AirSim源码的预处理与编译

下载的AirSim源码并不能直接作为插件使用，它需要先被编译成一个UE4能识别的插件模块。这个过程官方提供了一个build.cmd脚本，但直接运行常常会出问题。

1. 源码放置：不要将AirSim源码放在路径包含中文或特殊字符的目录下。我建议在某个盘的根目录创建一个简单的工作区，例如D:\AirSimProject。
2. 运行编译脚本：以管理员身份打开“VS2019的开发者命令提示符”，导航到AirSim源码目录下的Unreal\Plugins文件夹。直接运行build.cmd。这个脚本会自动下载UE4.27的源码（如果本地没有），并编译AirSim插件。
3. 关键一步：复制产物：编译成功后，你会在AirSim\Unreal\Environments\Blocks\Plugins目录下看到一个名为AirSim的文件夹。这个才是我们最终需要集成到项目中的插件。将其完整复制到你的剪贴板备用。不要使用源码根目录下的那个AirSim文件夹。

2.3 目标UE4 C++项目的创建

创建一个纯净的UE4 C++项目作为起点至关重要。打开Epic Games Launcher，启动UE4.27，选择“游戏” -> “空白” -> “C++”项目，取名如MyAirSimProject，选择带初学者内容，创建一个。创建成功后，关闭UE编辑器。

找到项目目录，其结构应类似于：

MyAirSimProject/ ├── MyAirSimProject.uproject ├── Source/ │ ├── MyAirSimProject/ │ ├── MyAirSimProject.Target.cs │ └── MyAirSimProjectEditor.Target.cs └── Content/

3. 插件集成与uproject配置详解

这是整个流程的核心，也是最容易出错的部分。我们将把编译好的AirSim插件放入项目，并深度配置.uproject文件。

3.1 插件目录的放置

在你的MyAirSimProject根目录下，创建一个名为Plugins的文件夹（如果不存在）。将之前复制的AirSim插件文件夹粘贴到MyAirSimProject/Plugins/目录下。此时结构应为：

MyAirSimProject/ ├── Plugins/ │ └── AirSim/ (包含 Binaries, Content, Resources, Source, AirSim.uplugin等) ├── MyAirSimProject.uproject ├── Source/ └── Content/

3.2 深度解析.uproject文件配置

右键点击MyAirSimProject.uproject，选择“Generate Visual Studio project files”。然后用Visual Studio 2019打开生成的MyAirSimProject.sln。先不要编译，我们需要先手动编辑MyAirSimProject.uproject文件。

用文本编辑器（如VSCode）打开.uproject文件。初始内容大概是这样：

{ "FileVersion": 3, "EngineAssociation": "4.27", "Category": "", "Description": "", "Modules": [ { "Name": "MyAirSimProject", "Type": "Runtime", "LoadingPhase": "Default" } ] }

为了让项目正确加载并编译AirSim插件，我们需要进行以下几处关键修改：

修改1：添加插件依赖在"Modules"数组的后面，添加一个"Plugins"数组。这告诉UE4，本项目必须加载以下插件。

{ "FileVersion": 3, "EngineAssociation": "4.27", "Category": "", "Description": "", "Modules": [ { "Name": "MyAirSimProject", "Type": "Runtime", "LoadingPhase": "Default" } ], "Plugins": [ { "Name": "AirSim", "Enabled": true } ] }

修改2：调整模块加载顺序（关键避坑点）AirSim插件内部有自己的模块（如AirSim，RPCLib等）。如果你的游戏模块（MyAirSimProject）需要在代码中直接#include "AirSim.h"并使用其API，那么你的游戏模块必须在AirSim插件模块之后加载，否则编译时会报“未识别的标识符”错误。 这是通过"LoadingPhase"参数控制的。将游戏模块的"LoadingPhase"从"Default"改为"PostConfigInit"。这个阶段在引擎核心系统和大多数插件初始化之后，确保AirSim的头文件已经可用。

"Modules": [ { "Name": "MyAirSimProject", "Type": "Runtime", "LoadingPhase": "PostConfigInit" } ],

修改3：启用必要的引擎插件AirSim依赖一些引擎自带的插件，例如"Json"、"JsonUtilities"（用于RPC通信），以及"ShaderConductor"（可能用于某些渲染特性）。为了确保万无一失，最好也在"Plugins"数组中显式启用它们。

"Plugins": [ { "Name": "AirSim", "Enabled": true }, { "Name": "Json", "Enabled": true }, { "Name": "JsonUtilities", "Enabled": true }, { "Name": "ShaderConductor", "Enabled": true } ]

修改4：解决潜在编译冲突（Windows平台）AirSim使用了Windows.h头文件，这可能会与UE4本身的一些定义（如TEXT()宏）产生冲突。一个常见的解决方案是告诉UE4在编译我们的游戏模块时，不要使用预编译头（PCH）中的某些Windows定义。这需要在项目的Build.cs文件中配置，但先在.uproject中我们可以为插件设置一些参数。不过更常见的做法是在Build.cs中处理。我们稍后会在C++配置部分详细说明。

保存修改后的.uproject文件。

4. 项目C++配置与代码集成

现在配置项目的C++端，使其能够与AirSim插件协同工作。

4.1 编辑项目构建文件（.Build.cs）

导航到MyAirSimProject/Source/MyAirSimProject/目录，打开MyAirSimProject.Build.cs文件。

我们需要在这里添加对AirSim插件模块的依赖，并处理Windows头文件冲突。

using UnrealBuildTool; public class MyAirSimProject : ModuleRules { public MyAirSimProject(ReadOnlyTargetRules Target) : base(Target) { PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs; // 1. 添加公共依赖模块 PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", // 添加对Json模块的依赖，因为AirSim的RPC会用到 "Json", "JsonUtilities" }); // 2. 添加私有依赖模块（插件模块通常在这里添加） PrivateDependencyModuleNames.AddRange(new string[] { // 依赖AirSim插件模块 "AirSim" }); // 3. 解决Windows.h冲突 (关键！) // 定义这个宏，可以避免Windows.h中的`min`和`max`宏与C++标准库冲突 PublicDefinitions.Add("NOMINMAX"); // 定义这个宏，可以避免`TEXT()`宏的重复定义问题 PublicDefinitions.Add("WIN32_LEAN_AND_MEAN"); // 4. 如果你需要用到AirSim的RPC客户端功能，可能需要添加额外的库路径 // 但通常AirSim插件会自己处理好，除非你遇到链接错误。 // 如果遇到无法解析的外部符号错误，可以在这里添加： // if (Target.Platform == UnrealTargetPlatform.Win64) // { // PublicAdditionalLibraries.Add("Path/To/Your/rpclib.lib"); // } } }

4.2 编写测试代码调用AirSim API

为了验证集成是否成功，我们在游戏模块中写一段简单的代码来调用AirSim。

首先，在MyAirSimProject/Source/MyAirSimProject/目录下，修改MyAirSimProject.h和MyAirSimProject.cpp。这里我们创建一个简单的Actor，在游戏开始时打印出AirSim的API版本。

MyAirSimProject.h

#pragma once #include "CoreMinimal.h" #include "GameFramework/Actor.h" // 包含AirSim的主要头文件 #include "AirSim.h" #include "MyAirSimProject.generated.h" UCLASS() class MYAIRSIMPROJECT_API AMyAirSimProject : public AActor { GENERATED_BODY() public: AMyAirSimProject(); protected: virtual void BeginPlay() override; public: virtual void Tick(float DeltaTime) override; };

MyAirSimProject.cpp

#include "MyAirSimProject.h" #include "Misc/DateTime.h" AMyAirSimProject::AMySimProject() { PrimaryActorTick.bCanEverTick = true; } void AMyAirSimProject::BeginPlay() { Super::BeginPlay(); // 尝试获取AirSim的API客户端 msr::airlib::RpcLibClient* client = nullptr; try { // 连接到本地默认的AirSim服务器（端口41451） client = new msr::airlib::RpcLibClient("127.0.0.1", 41451); client->confirmConnection(); // 确认连接 // 获取API版本信息 std::string serverVersion = client->getServerVersion(); FString msg = FString::Printf(TEXT("[AirSim] Connected! Server Version: %s"), *FString(serverVersion.c_str())); GEngine->AddOnScreenDebugMessage(-1, 10.0f, FColor::Green, msg); UE_LOG(LogTemp, Log, TEXT("%s"), *msg); delete client; } catch (const std::exception& e) { FString errMsg = FString::Printf(TEXT("[AirSim] Connection Failed: %s"), *FString(e.what())); GEngine->AddOnScreenDebugMessage(-1, 10.0f, FColor::Red, errMsg); UE_LOG(LogTemp, Error, TEXT("%s"), *errMsg); if (client) delete client; } } void AMyAirSimProject::Tick(float DeltaTime) { Super::Tick(DeltaTime); }

这段代码在游戏开始时，会尝试连接到本机运行的AirSim仿真（需要通过AirSim提供的可执行文件或自己启动一个仿真环境），并打印出版本号。这是一个最基本的连通性测试。

4.3 首次编译与生成

1. 回到Visual Studio 2019，右键点击解决方案资源管理器中的MyAirSimProject项目，选择“重新生成”。
2. 这个过程会比较久，因为这是第一次编译，需要编译整个项目以及我们集成的AirSim插件。确保你的磁盘空间充足（可能需要几十GB的临时空间）。
3. 编译成功后，你可以在VS中按F5启动调试，或者直接关闭VS，双击MyAirSimProject.uproject文件启动UE4编辑器。

启动编辑器时的关键观察点：

• 在UE4编辑器启动的加载阶段，你应该在输出日志中看到类似“LogAirSim: AirSim: Starting AirSim plugin...”的信息。这表明插件已被成功加载。
• 进入编辑器后，在菜单栏中应该能看到“Play -> AirSim”的选项，里面有各种仿真设置。这是插件加载成功的另一个标志。

5. 常见编译与运行时问题排查

即使按照上述步骤操作，你也可能会遇到一些问题。下面是我遇到过的典型错误及其解决方案。

5.1 编译错误排查表

5.2 运行时连接问题

当你运行我们写的测试代码时，可能会连接失败。

• 错误：Connection refused或超时这表示没有AirSim仿真环境在运行。你需要先启动一个AirSim环境。

  1. 最简单的方法是使用AirSim自带的Blocks环境。导航到AirSim\Unreal\Environments\Blocks目录，双击Blocks.uproject。首次打开会编译Shader，稍等片刻。
  2. 在Blocks编辑器中，点击“播放”按钮。这时，一个AirSim仿真服务器就在本地启动了（默认端口41451）。
  3. 然后，再运行你自己的MyAirSimProject。此时测试代码就应该能连接成功了。

• 错误：Vehicle not available这表示连接成功，但默认的车辆（或无人机）没有初始化。在Blocks环境中，确保你是在“车辆模式”下运行。你可以在你的项目代码中，通过client->enableApiControl(true)和client->armDisarm(true)来尝试获取控制权，但这需要更复杂的设置匹配仿真环境中的车辆名称。

5.3 性能与稳定性建议

1. 独立进程模式：对于严肃的仿真应用，建议将AirSim运行在独立进程（例如Blocks环境），你的UE4项目作为另一个客户端进程。这样即使你的客户端崩溃，仿真服务器也不会受影响。可以通过RPC（默认端口41451）或ROS/ROS2进行通信。
2. 蓝图与C++：AirSim暴露了丰富的蓝图节点，对于快速原型设计非常方便。但对于需要高性能、复杂逻辑或与外部代码（如PX4）深度集成的部分，坚持使用C++ API是更可靠的选择。
3. 资源管理：AirSim的传感器渲染（尤其是激光雷达、深度相机）非常消耗资源。在项目设置中合理调整渲染分辨率和帧率，在代码中控制传感器数据的更新频率，对于维持实时性至关重要。

6. 高级配置：自定义设置与多车辆控制

当基础集成跑通后，你通常会需要进行更复杂的配置。

6.1 理解与修改settings.json

AirSim的行为由一个settings.json文件控制。当你的项目运行时，AirSim插件会在以下位置寻找这个文件（按优先级）：

1. 你的项目可执行文件（.exe）所在的目录。
2. 你的项目Saved目录下的Config文件夹。
3. 你的用户文档目录（%USERPROFILE%\Documents\AirSim）。

我建议在你的项目根目录下创建一个settings.json文件，这样最容易管理。一个最简单的多旋翼无人机配置如下：

{ "SettingsVersion": 1.2, "SimMode": "Multirotor", // 仿真模式：Multirotor（多旋翼）, Car, ComputerVision "Vehicles": { "Drone1": { // 车辆名称，在代码中会用到 "VehicleType": "SimpleFlight", // 物理模型类型 "X": 0, "Y": 0, "Z": 0, // 初始位置 (米) "Yaw": 0 // 初始偏航角 (度) } }, "CameraDefaults": { "CaptureSettings": [ { "ImageType": 0, // 0=Scene, 1=Depth, 2=Segmentation... "Width": 256, "Height": 144, "FOV_Degrees": 90 } ] } }

在你的C++代码中，你可以通过车辆名称来获取特定车辆的客户端：

// 连接到特定的车辆 msr::airlib::MultirotorRpcLibClient client(“127.0.0.1”, 41451, “Drone1”); client.confirmConnection(); client.enableApiControl(true); client.armDisarm(true); // 现在可以控制 Drone1 了 client.takeoffAsync(5)->waitOnLastTask(); // 起飞到5米高

6.2 与外部飞控（如PX4）的集成

这是AirSim最强大的功能之一。你需要将AirSim配置为使用PX4的“Software In The Loop (SITL)”模式。

1. 修改settings.json:

   { "SettingsVersion": 1.2, "SimMode": "Multirotor", "Vehicles": { "PX4Drone": { "VehicleType": "PX4Multirotor", // 关键：使用PX4物理模型 "UseSerial": false, // 使用UDP通信 "UseTcp": true, "TcpPort": 4560, // PX4 SITL默认端口 "ControlPort": 14580, "LocalHostIp": "127.0.0.1", "OffboardUpdateFrequency": 50 // Hz } } }

2. 启动PX4 SITL：你需要按照PX4开发指南搭建SITL环境（通常使用jmavsim或gazebo）。启动后，PX4会在本地4560端口等待连接。

3. 启动你的UE4项目：当你的项目运行时，AirSim插件会自动尝试连接到127.0.0.1:4560的PX4实例。连接成功后，你可以在QGroundControl中看到飞机状态，并通过MAVLink指令或PX4的Offboard模式来控制它。

这个过程环境配置比较复杂，涉及到PX4固件编译、jmavsim启动等多个步骤，但一旦打通，你就拥有了一个硬件在环（HITL）或软件在环（SITL）的高保真仿真平台。

集成AirSim到自定义UE4 C++项目，与其说是一个技术活，不如说是一个“配置管理”的精细活。核心在于理解UE4的模块加载顺序、插件依赖关系以及编译工具链的版本锁死。最深刻的教训就是：严格遵循版本对应（AirSim v1.8.1 for UE4.27, VS2019），并耐心检查每一个配置文件的语法和路径。当编辑器成功加载插件，你的第一行C++代码成功调用到AirSim API的那一刻，之前所有的折腾都是值得的。这个环境搭建好后，你就可以专注于最核心的仿真逻辑和算法开发了。如果在集成后还需要添加新的传感器模型或者修改物理参数，直接去修改Plugins/AirSim/Source下的代码并重新编译插件即可，这又是另一个层次的工作流了。