这一期Airsim动态，不聊那些炫酷的视觉算法，先讲一个最基础但也最容易让人卡壳的事：把AirSim和ROS真正“接上”。AirSim是微软开源的无人机/汽车仿真环境，底层跑在Unreal Engine上，而ROS是机器人领域最常用的中间件框架。问题是，AirSim并不会主动把画面、里程计、GPS发布成ROS话题，ROS节点也不可能直接调用AirSim的虚幻世界接口。中间的桥梁，就是标题里说的这个ROS Wrapper。这篇就记录我从环境准备、编译、启动到排障的完整过程，适合那些正准备把AirSim接入ROS做感知、规划或控制仿真，又不想在接口上浪费太多时间的朋友。
1. wrapper这个“包装器”，到底在AirSim和ROS之间干了什么
很多第一次接触AirSim ROS Wrapper的人，会把wrapper理解成一个“驱动包”，装上就能用。理解其实不够准确。它更像是一个“翻译官+快递员”，把AirSim私有通道上的数据，翻译成ROS世界里的标准消息，再分发到对应的话题上；同时把ROS侧发来的控制指令，翻译成AirSim能听懂的RPC请求。
1.1 一个Simulator、两个世界：RPC协议与ROS话题
AirSim本身并不依赖ROS。它在Unreal Engine里完成物理仿真、相机渲染、激光雷达扫描，对外提供的是一套基于TCP Socket的RPC服务，默认监听本机41451端口，消息序列化走MsgPack。你可以用官方Python SDK，也可以用C++ SDK去连这个RPC服务，拿图像、拿状态、发指令。
ROS那边则是另一套逻辑：所有数据都抽象成topic、service、tf这些概念。一个用ROS写的自动驾驶算法，只知道去订阅/airsim_node/vehicle_1/odom，它不知道也根本不需要知道RPC协议和MsgPack是什么。
ROS Wrapper做的事情，就是把这两套世界缝起来。它内部创建一个RPC客户端，连上AirSim；拿到传感器数据后封装成ROS消息，发布到以/airsim_node/vehicle_1/...开头的话题下。同时它订阅ROS侧的控制话题，把TwistStamped、PoseStamped这类指令转换成AirSim的RPC调用。也就是说，wrapper本质上就是一个运行在ROS环境里的“桥接节点”。
1.2 为什么不直接写Python脚本，还要用官方Wrapper
有这个疑问很正常。我刚上手AirSim时，直接用Python API写过一个桥接脚本：循环里调client.getImage()、client.getMultirotorState()，再用rospy.Publisher发出去。小demo跑通没问题，但一旦传感器多了就开始难受。
官方Wrapper的价值主要体现在几个方面：
- 多传感器同步：图像、IMU、里程计、GPS是一套完整的状态快照，不是各发各的。
- 多机支持：通过
vehicle_name参数区分，同一份仿真环境里跑多台车/无人机，每个wrapper实例只对指定的那台车辆操作。 - 性能更好：C++/RPC客户端比Python逐帧回调要高不少，尤其在640x480以上分辨率，多路相机同时出图，Python脚本的瓶颈很明显。
- 参数化配置：可以用ROS的参数服务器动态配置，接入现有launch体系，方便和大系统整合。
当然，如果你只是临时验证一个思路，Python脚本也够。但一旦你的算法要同时用到多路图像、点云、TF坐标，你就会觉得官方wrapper把脏活累活全包了是件多省心的事。
1.3 ROS1和ROS2：两套包装器并存
还有个常见误解是“一个wrapper包，ROS1和ROS2都能用”。实际上AirSim仓库里ros/目录给ROS1，ros2/目录给ROS2，两套代码之间存在不少差别：构建系统一个是catkin_make，一个是colcon build；消息类型和launch方式也不一样。后面我会先以ROS1 Noetic版为主线讲，再单独说说ROS2 Humble版的情况，因为两者遇到的问题并不完全相同。
2. 动手前先对“版本日历”：这套组合我踩过的最少
安装这种带ROS依赖的工程，最怕的就是版本错位。我见过太多人一上来就git clone然后直接编译，报错了再回头查版本，结果最后发现是ROS版本和Ubuntu版本不匹配。这一步别偷懒。
2.1 系统和ROS版本怎么选
AirSim支持的ROS版本跟ROS官方LTS走。我这几年用下来，比较稳的组合是：
| 操作系统 | ROS版本 | AirSim目录 | 推荐度 |
|---|---|---|---|
| Ubuntu 18.04 | ROS Melodic | ros/ | 能用，但环境偏老 |
| Ubuntu 20.04 | ROS Noetic | ros/ | 最推荐，资料最多，坑最少 |
| Ubuntu 22.04 | ROS2 Humble | ros2/ | 新项目推荐，但Wrapper问题要自己多踩 |
| Ubuntu 24.04 | ROS2 Jazzy | ros2/ | 部分版本支持，不建议折腾 |
如果你跟我一样是拿来做算法验证，不要在一台机器上同时装ROS1和ROS2。不是反对多版本共存，而是每次都要小心翼翼地去source不同环境，很容易乱。我早期在20.04上装了Noetic后又装Foxy，结果每次开终端都要确认一遍环境变量，后来重装了系统，才彻底消停。
2.2 ROS安装的两种方式
ROS本体安装，我最常用还是官方apt源，一步步按官方wiki来。但国内网络环境有时候拉取apt源会很慢，或者出现“无法定位软件包”之类的问题。这时候社区里的一键安装脚本就很有用，比如不少人提到的小鱼一键安装。这类脚本本质上是替你把apt sources.list、rosdep这些步骤串起来，省去手动配源的麻烦，但它只解决ROS主体安装，AirSim本身的依赖还得自己处理，别指望一条命令全搞定。装完ROS后务必确认rosversion -d能正常输出，再继续。
2.3 AirSim源码编译与UE环境
AirSim本身需要编译，这个不能跳过。先克隆仓库：
git clone https://github.com/microsoft/AirSim.git cd AirSim ./setup.sh ./build.shsetup.sh负责下载UE依赖和Python包，build.sh编译AirSim的核心库。这里注意，build.sh只是编译库文件，不会生成一个可运行的UE项目。你还需要一份AirSim模拟器环境，也就是一个编译好的Unreal工程。最省事的办法是直接用官方release里的Blocks示例环境，或者自己按文档生成一个UE4/UE5工程。For wrapper调试来说，Blocks就够用了，没必要自己搭一个地图。
编译过程中setup.sh会在根目录拉两个UE插件版本（比如4.27或5.x），需要科学网络环境的人可能会卡住。这里我不展开网络问题，只说一句：如果setup脚本拉取依赖失败，优先检查网络源和代理配置，这是最常见的卡点。
2.4 冒烟测试：先让模拟器自己跑起来
别急着编译wrapper。先做一次“模拟器冒烟测试”，确认AirSim本身能跑、RPC端口能连上，否则后面Wrapper连不上你根本不知道是模拟器的问题还是Wrapper的问题。
方法是：启动Blocks模拟器，然后在另一个终端里运行官方Python脚本：
pip install airsim python3 -c "import airsim; c = airsim.MultirotorClient(); c.confirmConnection(); print('RPC OK')"如果这行脚本能输出RPC OK，说明AirSim的RPC服务正常，端口无误。如果这里就飘红，先别往下走，去查模拟器进程和防火墙。这个测试只需10秒钟，但能帮你把后面一整轮排障时间省掉。
3. 编译AirSim ROS Wrapper（ROS1 Noetic版）完整操作
假设你已经完成了ROS Noetic安装、模拟器能正常启动、Python SDK能连上RPC。现在正式进入wrapper的编译环节。
3.1 认识ros目录里的包结构
AirSim源码里的ros/目录，本身就是一个完整的Catkin工作空间源码目录，里面包含的包大致有：
airsim_ros_pkgs：元包，负责依赖声明。airsim_ros：核心实现，wrapper节点和消息定义都在这里。airsim_ros_tutorials：示例脚本，包括怎么发控制指令的demo。
如果你打开airsim_ros的CMakeLists.txt，会发现它依赖AirSim的C++库，还需要roscpp、std_msgs、geometry_msgs、sensor_msgs、nav_msgs等常规ROS包。这些依赖在ROS Noetic桌面版安装时一般已经带上，缺哪个补哪个就行。
3.2 创建工作空间与符号链接
source /opt/ros/noetic/setup.bash mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src ln -s ~/AirSim/ros airsim_ros_pkgs这里我用的是符号链接而不是直接cp。好处是以后AirSim仓库更新，wrapper代码也会同步更新，不需要手动重复拷贝。如果你用的是catkin_make，直接执行：
cd ~/catkin_ws catkin_make如果偏好catkin build，也可以，逻辑一样，但需要先pip install catkin-tools。我建议新手直接用catkin_make，少装一样是一样。
3.3 让CMake找到AirSim库
编译时最典型的报错是：
Could not find a package configuration file provided by "AirSim"这是因为wrapper的CMakeLists.txt里执行了find_package(AirSim REQUIRED)，但CMake不知道去哪里找AirSim的配置文件。AirSim编译完成后，在~/AirSim/cmake目录下应该能看到AirSimConfig.cmake之类的文件。你需要在构建时把路径告诉CMake：
cd ~/catkin_ws catkin_make -DAirSim_DIR:PATH=$HOME/AirSim/cmake如果这个目录下没有找到配置文件，大概率是前面./build.sh没跑完整，回头重新编译AirSim。还有一种办法是把AirSim路径挂进CMAKE_PREFIX_PATH：
export CMAKE_PREFIX_PATH=$HOME/AirSim/cmake:$CMAKE_PREFIX_PATH然后再跑catkin_make。
3.4 编译报错三连：缺路径、缺包、缺依赖
把我在编译过程中遇到的三个报错直接列出来，你们对照处理：
报错1：找不到AirSim配置办法上面已经写了，传-DAirSim_DIR:PATH。注意，如果你在catkin_make里传参，后续每次重新编译都要带，所以我更习惯把它写进环境变量，一劳永逸。
报错2：找不到msgpack相关头文件Wrapper的RPC底层依赖msgpack-c。可以通过系统包安装：
sudo apt install libmsgpack-dev然后重新编译。有些老版本还要求Python侧的msgpack-rpc-python，顺手也装一下：
pip install msgpack-rpc-python报错3：geographiclib库缺失GPS消息里需要地理坐标转换，编译时会依赖GeographicLib。装上就行：
sudo apt install libgeographic-dev编译成功后会生成devel/setup.bash，source一下：
source ~/catkin_ws/devel/setup.bash rospack find airsim_ros_pkgs如果最后一行输出了包路径，wrapper编译这关就算过了。
4. 启动Wrapper并验证数据流：从话题到图像再到控制
编译通过只是开始，真正跑通数据流才算是“装好了”。这一节我希望你跟我一样，按顺序做一遍，不要跳。
4.1 先写一个能跑的最小settings.json
AirSim在启动时会读取settings.json，这个文件的路径通常在~/Documents/AirSim/settings.json（Linux下是/home/<用户名>/Documents/AirSim/settings.json）。我第一次没配置直接启动，结果Wrapper能连上，但摄像头话题就是空。后来才发现是相机没在settings里开。
一个能跑通的最小配置长这样：
{ "SettingsVersion": 1.2, "SimMode": "Multirotor", "ClockSpeed": 1, "RpcPort": 41451, "CameraDefaults": { "CaptureSettings": [ { "ImageType": 0, "Width": 640, "Height": 480, "FOV_Degrees": 90, "CompressMode": 0 } ] }, "Vehicles": { "vehicle_1": { "VehicleType": "SimpleFlight", "AutoCreate": true } } }几个关键点：RpcPort必须和Wrapper连接端口一致；CompressMode设为0，也就是未压缩图像，能让后面图像话题的排查省掉一大半麻烦；AutoCreate设为true，启动模拟器时会自动创建vehicle_1这架无人机。
4.2 启动顺序和launch命令
顺序很重要：先启动模拟器，等世界加载完，再启动ROS节点。因为Wrapper节点在启动时会立刻尝试连接RPC端口，模拟器没起来就会大量刷“连接失败”日志。虽然它内部有重连机制，但看着那一屏红字真没必要。
模拟器启动后，新建一个终端，加载ROS环境后执行：
source /opt/ros/noetic/setup.bash source ~/catkin_ws/devel/setup.bash roslaunch airsim_ros_pkgs airsim_node.launch如果一切正常，终端里会出现节点注册信息，不会刷红色报错。多车场景下，可以用参数指定车辆名：
roslaunch airsim_ros_pkgs airsim_node.launch vehicle_name:=vehicle_14.3 rostopic list里应该看到什么
启动成功后，另开终端执行：
rostopic list你应该能看到一组以/airsim_node/vehicle_1/开头的话题，大致包括：
/airsim_node/vehicle_1/odom：里程计/airsim_node/vehicle_1/gps：GPS定位/airsim_node/vehicle_1/imu：惯性测量单元/airsim_node/vehicle_1/camera_1/RGB：可见光相机图像/airsim_node/vehicle_1/camera_1/Segmentation：分割图/airsim_node/vehicle_1/camera_1/Depth：深度图/airsim_node/vehicle_1/lidar_1/PointCloud2：激光雷达点云（如果settings里开了雷达）
看到这些话题存在，说明Wrapper已经成功订阅了AirSim的数据流，剩下的就是验证内容正确性。
4.4 最小验证：看图+发速度指令
先验证图像：
rosrun rqt_image_view rqt_image_view /airsim_node/vehicle_1/camera_1/RGB如果能看到模拟器机载相机的画面，整个数据链路已经从“AirSim -> RPC -> Wrapper -> ROS话题”完整打通了。
再验证控制链路。在ROS侧发布一个速度指令，看模拟器里的无人机是否响应。需要注意，很多版本的Wrapper启动时并不会自动开启API控制，需要先调相关服务或通过Python SDK执行enableApiControl。我习惯先在Python侧确认：
import airsim client = airsim.MultirotorClient() client.enableApiControl(True) client.armDisarm(True) client.takeoffAsync().join()起飞后再回到ROS侧发布指令：
rostopic pub -1 /airsim_node/vehicle_1/cmd_vel geometry_msgs/TwistStamped "{header: auto, twist: {linear: {x: 1.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}}"如果无人机往前飞了，控制链路也通了。到这里wrapper才算是真正“安装完成”。
5. 安装和调试中的四个坑，每个都不只花了一小时
这个部分才是本文真正的精华。下面每个问题都是我在实际操作中踩过的，不是文档里能翻到的。
5.1 RPC连不上：先ping，再查端口，最后看启动顺序
Wrapper日志里报RpcClient exception，或者Python脚本confirmConnection()直接挂，别急着怀疑wrapper配置。我总结了一个“三层排查法”：
第一层，模拟器进程是否还在：ps aux | grep AirSim。有时候UE工程会因为崩溃留下僵尸进程，或者你启动的是另一个不相关的项目。
第二层，端口是否在监听：netstat -tlnp | grep 41451。如果端口没起来，说明AirSim的RPC服务没启动成功，去查settings.json里的RpcPort是不是和预期一致。
第三层，用Python SDK实测连接：client.ping()。如果Python都连不上，基本跟wrapper无关，问题在模拟器侧；反过来说，Python能连上而wrapper连不上，那才需要去看wrapper的环境变量和版本。
还有一个特别容易忽略的顺序问题：先在settings.json里写了RpcPort，但模拟器是在修改前启动的，端口还是旧值。改完配置一定重启模拟器。
5.2 find_package找不到AirSim：CMake路径问题
这个我在第3.3节提过，但值得单独说。很多人在编译时报错后，会跑到网上去搜“AirSim find_package失败”，结果搜到一堆不相关问题。
我的排查经验是：先看看~/AirSim/cmake目录下到底有没有配置文件。如果没有，说明./build.sh没跑完，或者中途报错但你没注意到。这时候重新执行./build.sh，盯到最后一个输出。如果目录里有配置文件但编译还是找不到，多半是catkin_make没有把这个路径传给CMake，老老实实加上-DAirSim_DIR:PATH=$HOME/AirSim/cmake再编译一次。
5.3 图像有话题但黑屏或灰屏
这个话题让我一度以为相机坏了。启动模拟器后从UE窗口看一切正常，但ROS侧图像就是灰蒙蒙一片，或者rqt_image_view里提示解码失败。
根本原因是图像编码类型没对上。AirSim输出的图像如果设成CompressMode: 0，是原始的BGR/RGB数据，话题类型一般是sensor_msgs/Image；但有些版本默认会开压缩，此时图像数据是JPEG编码的，ROS侧可能需要订阅compressed后缀的话题，或者先通过image_transport做解压。
如果你想省心，在settings.json里把CompressMode设为0，订阅原始图像话题。这样虽然带宽大一些，但最少坑。
5.4 多机场景下所有飞机都在动同一个
多机仿真时，wrapper如果每个车都开着默认vehicle_name，结果就是所有数据都在读第一个车，发指令也会串台。解决方法是每个车辆单独启动一个launch，并显式指定vehicle_name。同时settings.json里每个车辆都得有独立的命名：
"Vehicles": { "vehicle_1": { "VehicleType": "SimpleFlight", "AutoCreate": true }, "vehicle_2": { "VehicleType": "SimpleFlight", "AutoCreate": true } }然后分别在两个终端里：
roslaunch airsim_ros_pkgs airsim_node.launch vehicle_name:=vehicle_1 roslaunch airsim_ros_pkgs airsim_node.launch vehicle_name:=vehicle_2这样两个wrapper节点会分别连接各自的RPC客户端，数据和控制互不干扰。这个习惯从单机阶段就要养成，别等上车队了再改。
5.5 附加：TF和坐标系
如果你的算法需要用到tf，注意wrapper发布的是从world到vehicle_1的TF关系。如果后续你在Rviz里看不到模型或坐标错乱，优先检查wrapper是否启动了TF发布，以及坐标系名称是不是和你算法里写的一致。这一类问题不是安装范畴，但会让你以为“wrapper没装好”。
6. 换到ROS2（Humble）版Wrapper的差异体验
如果你的项目起点就是ROS2，比如用的Humble，AirSim仓库里对应的ros2/目录就是另一套玩法了。
6.1 构建方式和启动命令
ROS2版不再用catkin_make，而是用colcon。工作空间创建方式类似：
source /opt/ros/humble/setup.bash mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src ln -s ~/AirSim/ros2 airsim_ros_pkgs cd ~/ros2_ws colcon build启动时也用ROS2的格式：
source install/setup.bash ros2 launch airsim_ros_pkgs airsim_node.launch.py话题列表大体沿用/airsim_node/vehicle_1/...的命名，控制指令发布工具从rostopic pub换成ros2 topic pub。
6.2 QoS与图像话题的坑
ROS2和ROS1最大的区别之一是QoS策略。ROS1里订阅者和发布者只要话题名对上就行，ROS2里还要求QoS兼容。我第一次在ROS2版里用rqt_image_view看图像，话题明明在却没有图像，折腾半天发现是订阅端的QoS Profile和发布端不匹配。
这种问题的排查思路是：用ros2 topic info /话题名 --verbose查看发布者的QoS参数，然后在订阅时显式设置reliability、durability等参数。如果你只是自己用，把两者都设成best_effort和volatile基本能解决90%的“有话题没数据”问题。
6.3 我的取舍建议
虽然我上面吐槽了ROS2版的一点问题，但如果是从零开始的项目，我还是建议直接用ROS2 Humble。原因为不是ROS1不够好，而是新的算法库、新的学习资料都在向ROS2迁移，AirSim的ROS2 wrapper也在持续迭代。只是你要有心理准备：遇到问题时，网上可参考的讨论确实比ROS1版少。我自己的习惯是：跑通ROS1版作为“翻译器”对照，再在ROS2版里做正式开发。
另外，ROS2版的Wrapper在启动后会涉及节点的生命周期管理，有时候你会看到节点状态不是active，数据不输出，需要手动调用相关接口激活。不同分支行为不一样，遇到时先查版本，别急着重编译。
装wrapper这件事，难吗？其实不难，但它的坑都在细节里。只要你按着“先验证AirSim，再编译wrapper，最后验证数据流”的顺序走，大部分问题都能提前挡掉。我个人的经验是：永远保留一个能跑通的最小settings.json，别随便把官方的复杂配置全塞进去；编译前多花10分钟确认依赖和版本，比编译挂了再一条条谷歌省太多时间。wrapper跑起来之后，你就可以专心做真正想做的事了——无论是接感知算法、写控制策略，还是拖一群无人机做多机实验。
