AirSim 1.3.1升级实操：UE4工程迁移与避坑指南

现在复盘这次升级的时候，我的UE4工程已经稳定跑在AirSim 1.3.1上半个月了。整个过程从开始折腾到完全跑通，前前后后花了一个周末，真正的编译和替换其实就几个小时，剩下的时间全耗在接口迁移和排查莫名其妙的运行时问题上。写这篇实操记录，就是想让准备升级AirSim版本的同学少走点弯路。这个版本对老工程不算友好，但只要摸清它到底改了什么、哪些缓存必须删、配置怎么迁，其实半天就能搞定。

先说下背景。我的项目是基于UE4搭建的无人机视觉导航仿真环境，之前一直用AirSim 1.2.x，老版本跑得挺稳，一直没动它。这次要跑新的传感器融合实验，需要用到1.3版本的数据同步特性，不得已才做了这次大版本升级。如果你的项目还停留在旧版本，或者刚接触AirSim想直接上一个稳定分支，这篇记录应该能帮你把升级成本控制在可控范围内。

1. 升级之前，先看清1.3.1到底变了什么

1.1 这次版本升级动了哪些底层逻辑

AirSim 1.3.1不是一次简单的小版本迭代。从1.2.x跳到1.3.1，代码结构、API接口、传感器输出格式和物理引擎配置都做了比较大的调整。最明显的变化是底层命名空间从原来的AirSim统一收敛成了msr::airlib，C++客户端、RPC通信层、传感器抽象层全部换了一套组织方式。这意味着以前直接引用旧命名空间的工程代码，编译时大概率会报找不到头文件或者符号无法解析。

物理引擎方面，1.3开始默认推荐FastPhysicsEngine，并且把物理子步数调整成了更激进的配置。这对飞行效果的影响是直接的：老工程如果没有在settings.json里显式声明物理引擎，升级后无人机的起降手感、悬停稳定性都会发生变化，严重的时候会出现起飞瞬间往旁边漂的情况。另外从1.3开始，SimMode被明确拆分成了Multirotor和Car两个模式，如果你想同时跑无人机和汽车，配置方式跟旧版本完全不同。

还有一个经常被忽略的变化：默认碰撞检测在1.3.1里是关闭的。官方这么做的原因是开着碰撞检测在一些自制地图上会导致机身异常抖动，但如果你跑的是避障实验，忘记开启这个开关，飞机会直接穿过障碍物。这个坑我后面会详细说。

1.2 环境摸底与备份，千万别直接覆盖

升级前最重要的一步不是下载新代码，而是弄清楚当前工程里哪些东西会被新版本覆盖。AirSim是以UE4插件的形式挂在工程里的，插件目录一旦替换，旧版本的二进制文件就没了。我第一次升级的时候就没做备份，结果编译出问题想回滚，被迫临时重新拉了一套旧源码重新编译，白白浪费了一天。

建议动手前把这几样东西完整备份，最好是压缩包形式放在工程目录外：

• 整个工程目录，或者至少是Plugins/AirSim下的所有内容。
• Saved目录，尤其是Saved/Config里的DefaultEngine.ini和DefaultGame.ini，这里面存了很多跟项目绑定的配置。
• Content目录下自定义的关卡、蓝图、材质资源。
• 系统用户目录下的Documents/AirSim/settings.json，所有运行时配置都在这里。

我的习惯是直接用压缩工具把工程整体打一个快照，然后在新副本里做升级。这样即使升级失败，旧工程还能继续跑，不影响实验进度。不推荐直接在正在使用的工程上原地升级，风险收益比不划算。

1.3 磁盘、编译器和网络准备

AirSim 1.3.1官方支持的UE4版本大概在4.24左右，编译器建议直接用VS2019。如果你的UE4版本太老，需要先升级引擎版本，那升级复杂度会翻倍，因为关卡里的光照、材质、蓝图都可能在引擎版本跨越中产生兼容问题。

磁盘空间是容易被忽略的点。UE4工程的Intermediate、Binaries、Saved这三个目录加起来经常超过50GB，加上新版本插件重新编译时又会产生大量中间文件，磁盘不够的话编译到一半报错特别打击士气。我建议至少留出100GB空闲空间，同时把杀毒软件暂时关掉或者添加排除目录，否则编译过程中拦截动态链接库会导致非常诡异的报错。

网络环境对拉取源码影响很大。AirSim仓库里的UE4插件资源比较大，直接完整克隆容易中途失败。我用的方法是浅克隆，只取1.3.1对应的标签版本，节省时间也减少中断概率。如果下载过程中断了，重新拉时会基于本地缓存继续，比从头再来要靠谱得多。

2. 插件替换与工程重建全过程

2.1 拉取1.3.1源码并定位对应分支

一开始我只简单粗暴地从1.2直接复制旧文件到新版本目录里，结果编译直接崩。后来发现正确做法是先从官方仓库拉取对应版本的源码，再迁移到工程里。

实操命令大概是这样的，用浅克隆的方式拉指定标签：

git clone --depth 1 --branch v1.3.1 https://github.com/AirSim/AirSim.git AirSim-1.3.1

这里--depth 1表示只拉取最新一份提交历史，--branch v1.3.1定位到对应版本。需要注意仓库里的子模块需要一并初始化，否则插件的第三方依赖会缺失。

cd AirSim-1.3.1 git submodule update --init --recursive

子模块拉取完成后，把整个源码放到UE4工程外的一个独立目录，不要直接塞进工程里。然后进入AirSim-1.3.1/Unreal/Plugins目录，这里就是最终要放进工程里的插件本体。

2.2 替换Plugins目录，清掉三处缓存

将上一小节提到的AirSim插件整体复制到工程的Plugins目录下。如果工程里已有旧版AirSim目录，先重命名备份，再复制新版本。千万别做覆盖合并，新旧混在一起很容易出现类名冲突或者接口不匹配的玄学问题。

复制完成后，下一步是清缓存。插件替换之后，UE4工程里的三类缓存必须删除，否则编译器会拿旧缓存里的数据索引跟新代码做拼接，产生大量没有实际意义的报错：

• Intermediate目录：编译器中间产物，不删除的话会残留旧版本的.h和.obj引用。
• Binaries目录：之前编译好的旧插件二进制文件，会被IDE或命令行误加载。
• Saved目录：这个目录包含自动化测试、日志和配置缓存。有一个很容易踩的坑是Saved/Config里保存的插件列表，UE4启动时会拿它跟Plugins目录做匹配，不清理就会加载失败。

清理之后，关闭编辑器，删除这三个目录，右键.uproject文件选择Generate Visual Studio project files，重新生成工程索引。

2.3 重新编译，以及首次启动前的配置调整

生成工程索引之后，用VS2019打开.sln文件，注意配置管理器里要选到Development Editor，平台选Win64，然后编译整个解决方案。第一次编译耗时比较长，我这边大概用了四十多分钟，中间一度看起来像卡死了，但本质上只是编译器在生成新的可视化和物理引擎模块，需要耐心等。

如果想用官方脚本全自动编译AirSim插件，也可以直接在AirSim源码根目录执行：

.\build.cmd

脚本会把插件的所有模块构建一遍，再往UE4的插件安装目录里拷贝一份。不过我的做法是手动复制插件到工程目录后，直接在解决方案里编译，因为这样更贴近项目实际使用方式，也好定位错误发生在哪个模块。

编译完成后，先用UE4编辑器打开工程，如果一切正常，会看到Content Browser里出现了AirSim相关的资源和蓝图。此时先别急着跑实验，打开工程关卡，检查World Settings里是否指定了正确的GameMode。1.3.1的GameMode类名仍然是AirSimGameMode，但如果你从旧版迁移过来，蓝图里的类引用可能还是旧路径，需要重新指定。这个细节特别坑，因为它只在启动关卡时报一个非常模糊的警告，不会直接中断流程。

首次启动前，还要确认一下系统Documents目录下的AirSim配置文件。1.3.1如果检测到旧版本格式的settings.json，会自动尝试迁移，但迁移过程有可能丢掉部分自定义字段。所以我建议手动把配置文件重命名备份，让新版本生成一份全新默认配置，然后再逐步添加自定义项。

3. 代码适配：从1.2到1.3的接口迁移

3.1 C++接口与Python API的对应变化

代码迁移是这次升级里最花时间的部分。C++层面，最直接的变化是命名空间。旧版本代码里飞控相关类用的是老命名空间，升级后编译器会直接报一堆namespace "xxx" has no member "yyyy"。处理方式其实不复杂，批量把命名空间前缀替换成msr::airlib就行。

Python端没有这么剧烈的变化，因为1.3.1仍然支持直接安装airsim包：

pip install --upgrade airsim

升级后主要注意类名和部分方法的语义变化。1.3之后，多旋翼和汽车客户端分得更清楚，初始化时的行为和参数校验也变严格了。比如旧代码里直接调用client.enableApiControl(True)不会检查车辆是否就绪，新版本则会在连接不稳定时抛出异常。一个比较典型的1.2时代代码升级后可能是这样的：

import airsim # 连接并确认 client = airsim.MultirotorClient() client.confirmConnection() # 1.3之后建议先检查状态再解锁控制 state = client.getMultirotorState() if state.landed_state == airsim.LandedState.Landed: client.enableApiControl(True) client.armDisarm(True) client.takeoffAsync().join()

这里最值得注意的变化是getMultirotorState()返回的数据对象里，关于碰撞的信息被剥离出去了。1.2时代可以直接从state里拼凑碰撞状态，1.3必须单独调getCollisionInfo()，而且返回结果的结构也不一样，需要用has_collided来判定碰撞。如果忽略这个变化，避障相关的判断逻辑会静默失败，程序不报错但行为不对，排查起来特别费劲。

3.2 坐标转换、HomePoint与传感器时间戳

坐标转换是另一个需要仔细核对的地方。AirSim内部统一用NED坐标系，X轴向前、Y轴向右、Z轴向下，这部分没变。变的是1.3.1对HomePoint的处理更严格了。

旧版本里，工程启动时会根据玩家起始位置自动生成HomePoint，某些场景下我们会在代码里写死一个偏移量来对齐地图原点。1.3.1修正了部分场景下坐标系换算不一致的问题，同时也会导致旧代码里写死的偏移量变成实际误差。升级后你会发现无人机起飞位置和设定点之间差出几米甚至十几米，问题就出在这里。

正确的做法是每次起飞前动态读取HomeGeoLocation，再结合当前GPS数据计算初始偏移，而不是沿用旧工程里写死的常量。我改完之后，坐标问题彻底消失，而且在不同地图上切换时也不用再逐个调整偏移值。

传感器时间戳的变化跟实验关系很大。1.3.1给所有传感器数据都加了time_stamp字段，单位是纳秒，这个字段跟系统的ClockSpeed设置直接相关。如果ClockSpeed被设置成小于1的值，模拟时间变慢，数据里的时间戳也会按比例拉长间隔。这在跑时间同步实验时特别关键，建议确认一下settings.json里有没有误配置ClockSpeed。

3.3 settings.json迁移：从旧格式到新格式

settings.json是最容易被忽略但影响面最大的配置文件。1.3.1把配置格式升级到了SettingsVersion 2，旧格式的配置文件虽然能被读取，但新特性不会生效，而且会在日志里输出一堆警告信息。

我推荐直接手工迁移，把配置文件改成下面这种结构：

{ "SettingsVersion": 2, "SimMode": "Multirotor", "ClockSpeed": 1, "CameraDefaults": { "CaptureSettings": [ { "ImageType": 0, "Width": 1920, "Height": 1080, "FOV_Degrees": 90 } ] } }

这里解释几个关键字段。SimMode必须显式指定，否则默认可能是汽车模式，无人机API调用会失败。ClockSpeed建议保持1，模拟时间跟真实时间一致。CameraDefaults是1.3开始推荐的图像采集配置方式，在同一个结构里管理所有摄像头的分辨率和视场角，比旧版本里逐个设置方便很多。

顺带提一个误区：很多教程会让把SettingsVersion填成1来兼容旧配置。实测下来这样虽然能启动，但1.3新增的传感器时间同步和物理参数不会加载，而且枚举值等校验逻辑也会变宽松，数据一致性没法保证。既然已经升级了，配置格式也应该一步到位。

4. 常见问题与排查技巧实录

4.1 编译期报错处理速查

编译期报错是升级后第一道坎。我一个人踩过的和从同行那里收集到的典型问题，整理成了一张速查表。

编译期问题百分之八十都出在缓存上。UE4的开发环境对缓存一致性很敏感，版本一旦发生大更新，老缓存就是定时炸弹。我现在的习惯是：遇到任何编译问题，先把Intermediate和Saved改名备份，再重新Generate，一半的报错都能自动消失。

4.2 运行时崩溃、数据异常与性能回退

编译通过只是开始，运行时问题才是大头。我遇到的第一类问题是飞行控制异常。升级后第一次起飞，无人机直接斜着冲出去，马上手动急停。查了日志发现是旧的settings.json里没有显式声明物理引擎，新版默认走了FastPhysicsEngine，而我的地图模型比较复杂，物理子步数不够导致碰撞响应异常。在配置里显式加上物理引擎设置并调高子步数后恢复正常。

第二类问题是传感器数据看起来正常但数值有明显漂移。这个问题最迷惑，因为不报错，只是CPU占用比旧版本高。定位后发现是ClockSpeed和传感器更新率在配置迁移时对不上号，导致数据采集线程忙等。把ClockSpeed统一设置成1，所有传感器都按默认更新频率走，问题解决。

性能回退也要提一下。升级后如果发现帧率下降，十有八九是新版本渲染管线或物理管线同时开启导致的开销。可以在Settings里关掉不必要的传感器仿真，比如你只飞视觉导航，那IMU和GPS如果不需要，就单独把更新率调低，或者直接不启用对应传感器模块，性能能明显回升。

4.3 拿到一个报错后通用的排查顺序

这里分享一个我总结的通用排查顺序，适用于大部分升级后出现的问题。首先看日志，AirSim的日志文件写在Saved/Logs目录下，报错信息往往比UE4弹出的对话框更详细。第二步是验证配置，检查settings.json里有没有旧字段残留，我遇到过一次问题就是配置里写错了SimMode，导致API控制全程静默失效。第三步是隔离变量，把代码里的自定义逻辑全部停掉，先让原版AirSim的飞行示例跑起来，确认飞控本身没问题，再逐步加回自己的逻辑。最后才考虑重编译、重拉源码这类重操作。

这个顺序看着朴素，但它能避免你陷入瞎试的泥潭。我见过不少同行升级后出了奇怪问题，第一反应是把整个工程推倒重来，结果旧问题解决了新问题又冒出来，反而不如一步步排查来得快。

5. 升级后的功能验证与个人体会

5.1 一张验证清单，对照跑一遍

所有代码迁移完、问题排查完，不代表升级就算完成了。我习惯按一张验证清单逐项对照检查，全部通过才算真正收工。

这五类验证覆盖了从底层物理到应用接口的完整链路。我建议升级完成后先把示例工程跑一遍，如果示例都过不了，说明是环境问题；如果示例能过而自己的实验跑不了，再聚焦代码迁移部分。

5.2 关于这次升级，我的一点个人心得

最后说点实在的。整个升级过程中，我最后悔的一件事是第一天没备份旧版本二进制。升级到一半编译出问题想回滚时，发现旧插件已经被覆盖，只能临时再拉一套旧源码重新编译。有备份的话，这一步完全可以省掉。

另一个收获是：版本升级反而是重新梳理工程结构的好时机。以前项目里堆了很多从旧教程复制来的配置，也不知道每个字段到底干什么用。借着这次迁移，我把settings.json从头到尾理了一遍，删掉了一批无效字段，整个工程的启动速度和稳定性反而比升级前更好了。

如果你问我要不要升级到1.3.1，我的建议是：非必要不升级。老版本如果跑得稳定，不要为了追新而追新。但如果你确实需要新版本的数据同步特性、更规范的C++接口，或者想给以后的功能扩展打基础，那按这篇文章的流程走一遍，半天到一天时间足够完成。最关键的就三件事：备份、清缓存、逐个迁移接口。做好这三件，版本升级就是个体力活。