先说明一个设定：这篇博文的内容是完全基于我自己的实操经验写的。我在PX4 v1.13.3、Ubuntu 20.04 + Gazebo 11的环境下，为Iris无人机挂过Intel RealSense D435i的仿真模型，中间踩了不少坑，也把配置过程完整记录了下来。下面这篇内容可以直接照着做，版本差异我会在对应位置标注。
1. 为什么要在仿真里给Iris挂D435i
很多刚开始接触PX4 + Gazebo仿真的人，第一件事就是启动默认的Iris无人机，飞一下看看效果。但等到真正做视觉避障、目标跟踪、SLAM建图这类任务时，就会发现自己手上只有一台没有任何机载传感器的裸Iris——它只有飞控相关的IMU、气压计、磁力计和GPS，连个摄像头都没有。
这时候你就需要一个能模拟Intel RealSense D435i的深度相机模型。D435i是Intel RealSense系列里非常经典的一款深度相机，它同时输出RGB图像、深度图像和IMU数据，在真实无人机、机械臂、无人车项目里被大量使用。Gazebo仿真里把它挂到Iris上，你就可以在完全虚拟的环境下验证视觉算法，不需要真机，也不需要真实的D435i硬件。
这篇教程适合谁？正在用PX4做视觉SLAM、目标检测、避障算法开发的人，或者刚开始接触PX4 Gazebo仿真、想给自己的无人机模型加传感器的初学者。如果你已经能正常启动make px4_sitl gazebo-classic，但不知道怎么在模型里加相机，那这篇就是给你准备的。
1.1 仿真相机和真实相机的区别
先把一个概念说清楚：Gazebo里的D435i并不是真正的D435i驱动，也不是RealSense SDK的仿真版，而是Gazebo的传感器插件按照D435i的关键参数（分辨率、FOV、帧率、基线距离等）模拟出来的一个相机模型。
它的意义在于：你在仿真里拿到的图像数据流、话题名称、图像尺寸和真实D435i保持高度一致，这样你写的视觉代码可以直接从仿真环境无缝迁移到真机上，只需要改一下话题名或者驱动配置。
但也要注意，仿真相机的图像是渲染引擎生成的，不是真实的光学成像，所以不会出现镜头畸变、光照噪点这些真实相机才会有的问题。D435i真实的深度点云会有空洞、边缘噪点，仿真里基本是干净的。所以做算法验证没问题，但做传感器特性研究就不合适了。
1.2 为什么选Iris而不是其他机型
Iris是PX4官方维护的默认仿真机型之一，模型文件直接集成在PX4固件仓库的Tools/sitl_gazebo目录下，不需要额外下载。它是一台四旋翼，动力学参数稳定，掉下来摔进地面了反弹效果也比较真实，非常适合做算法验证的载体。
选择Iris的另一个原因是社区生态好。你搜任何PX4仿真相关的教程、论坛问题，大部分都是基于Iris的。这意味着凡是你能想到的问题，基本都是别人踩过的，有现成的解决思路可以抄。相比之下，如果你一上来就用自定义机型，比如自制的X型四轴或者六轴，模型文件要自己写，配置链路长，遇到问题排查起来也麻烦。
我见过一些朋友一上来就改机型，花了大量时间在模型动力学调参上，最后相机还没挂上。我的建议是先用Iris把整条链路跑通，再做个性化扩展。
1.3 前置知识：SDF、URDF和Gazebo模型文件
挂载D435i的核心，就是修改Gazebo的模型文件。这里要分清SDF和URDF的关系，我最早在这上面绕了不少路。
- SDF（Simulation Description Format）：Gazebo的原生模型格式，用
.sdf后缀，可以描述动力学、传感器、插件等全部信息，Gazebo直接加载它。 - URDF（Unified Robot Description Format）：ROS生态的机器人描述格式，主要描述连杆、关节、传感器的运动学树。Gazebo可以部分兼容URDF，但完整支持还是需要SDF，或者用
gazebo_ros的插件做转换。
PX4的Iris模型默认就是SDF格式，位于PX4-Autopilot/Tools/sitl_gazebo/models/iris/iris.sdf。我们要做的就是在它的<link>里加一个相机link，在sensor里配置相机插件，然后在<joint>里把它固定在机身上。
这句话可以记一下：给无人机挂相机，本质上就是往SDF文件里加一个带传感器插件的link，再把它和机身用joint固定住。
2. 前期准备：PX4和Gazebo环境确认
动手改文件之前，先把工具链确认好。很多人在配置过程中出问题，就是版本对应关系没搞清楚。
2.1 版本对应关系速查
这里的核心知识点是：PX4对Gazebo的支持是分代的，不同PX4版本的默认Gazebo版本不同。
以我常用的环境为例：
| PX4版本 | 默认Gazebo | Ubuntu系统 | 备注 |
|---|---|---|---|
| PX4 v1.12.x | Gazebo 9 | Ubuntu 18.04 | 老版本，模型结构略有不同 |
| PX4 v1.13.x | Gazebo 11 | Ubuntu 20.04 | 我目前的主力版本 |
| PX4 v1.14.x | Gazebo 11 / Gazebo Garden | Ubuntu 22.04 | Garden是新框架，插件名有变化 |
| PX4 v1.15.x | Gazebo Garden / Harmonic | Ubuntu 22.04 / 24.04 | 新架构为主 |
我建议你安装前先查一下自己的PX4版本：执行git -C ~/PX4-Autopilot describe --tags，就能看到当前固件的版本号。
如果你用的是Ubuntu 22.04 + PX4 v1.14及以上，那要注意：从v1.14开始，PX4同时支持Gazebo Classic（也就是Gazebo 11）和新的Gazebo Garden/ Harmonic。这两套的名字不一样，启动方式也不一样。Classic用的是make px4_sitl gazebo-classic，Garden/Harmonic用的是makepx4_sitl gz_x500之类的目标。本文以最经典、最稳定的Gazebo Classic + Iris方案为准。
2.2 快速检查环境是否就绪
在开始前，花两分钟确认以下四项：
- PX4源码已编译通过：在
~/PX4-Autopilot目录下执行make px4_sitl gazebo-classic，如果能正常弹出Gazebo窗口并看到一架Iris待在地面上，说明环境OK。 - 环境变量已配置：PX4的Gazebo仿真会向Gazebo传入模型路径。如果重启终端后无法加载模型，检查
~/.bashrc里是否已经添加了PX4工具链的环境变量。一般PX4安装脚本会自动写，但手动装的话容易漏。检查方式是输入echo $GAZEBO_MODEL_PATH，看是否包含~/PX4-Autopilot/Tools/sitl_gazebo/models。 - ROS（可选）：如果你想用
rostopic查看图像话题，需要装ROS Noetic（Ubuntu 20.04）或ROS2 Foxy/Humble（Ubuntu 22.04）。不装ROS也能看Gazebo里的传感器图像，但要解析话题数据就得靠ROS，或者QGroundControl。 - 磁盘空间：PX4全量编译+Gazebo模型缓存，建议至少预留10GB空闲空间。Gazebo的模型库第一次启动时会从网上下载（比如地面、建筑物模型），网络不好会导致加载卡住。
2.3 关于D435i真实相机标定题外话
搜索热词里有个"d435i相机标定"，这个是和仿真相关但不完全相同的环节。仿真里不存在标定问题，因为相机的内参就是你设定的参数，不会有畸变。但如果你后续把代码部署到真机上，D435i就需要做标定，获取内参和畸变系数，用于深度对齐和RGB对齐。
在仿真阶段，你可以提前按照D435i真实的默认内参来配置相机参数，这样后续迁移到真机时，代码里的内参矩阵不用大改。这也是仿真和真机的桥接思路之一：仿真参数越接近真机，迁移成本越低。
3. 完整配置流程：从复制模型到挂载D435i
下面进入正题。整个挂载过程分三步：复制模型文件、编写D435i传感器定义、重新编译启动。我不推荐直接改动原来的iris.sdf，因为这样容易把官方模型搞坏，不方便回退。正确做法是复制一份成自己的模型，比如叫iris_d435i。
3.1 复制Iris模型目录
打开终端，执行以下命令：
cd ~/PX4-Autopilot/Tools/sitl_gazebo/models cp -r iris iris_d435i cd iris_d435i这样你就得到了一个独立的iris_d435i模型目录，里面有iris.sdf和model.config两个文件。model.config是模型描述文件，Gazebo启动时根据它找到模型名称和SDF文件名。
打开model.config，把<name>标签从iris改成iris_d435i：
<model> <name>iris_d435i</name> <version>1.0</version> <sdf version="1.5">iris.sdf</sdf> <author> <name>Your Name</name> </author> <description> Iris quadrotor with Intel RealSense D435i depth camera </description> </model>注意：<sdf version="1.5">表示使用的SDF格式版本。如果你在Gazebo 11里，1.5到1.7都能兼容，不要改这个标签，否则可能报schema版本错误。
3.2 修改SDF文件：添加D435i的link和joint
接下来这是核心操作。用文本编辑器打开iris.sdf。原始文件很长，包含了base_link、rotor_0等多个link。我们要做的是：
- 在文件的
<model>内部添加一个新的<link>，名字叫camera_d435i，用来表示D435i这个刚体。 - 在
<link>内部添加<sensor>定义，描述相机的RGB、深度和IMU功能。 - 添加一个
<joint>，把camera_d435i固定在base_link上。
先说link怎么加。D435i的真实尺寸大约是90mm×25mm×25mm，质量约130克。在仿真里，质量不是最关键的因素，但建议设成合理值，否则会影响无人机的转动惯量。我把link定义放在模型的base_link定义后面，这样结构清晰一些：
<link name="camera_d435i"> <pose>0.10 0 0 0 0 0</pose> <inertial> <mass>0.13</mass> <inertia> <ixx>0.000025</ixx> <iyy>0.000025</iyy> <izz>0.000025</izz> <ixy>0</ixy> <ixz>0</ixz> <iyz>0</iyz> </inertia> </inertial> <visual name="visual"> <geometry> <box> <size>0.09 0.025 0.025</size> </box> </geometry> <material> <ambient>0.2 0.2 0.2 1</ambient> <diffuse>0.2 0.2 0.2 1</diffuse> </material> </visual> <collision name="collision"> <geometry> <box> <size>0.09 0.025 0.025</size> </box> </geometry> </collision> </link>这里有个关键点：<pose>0.10 0 0 0 0 0</pose>表示相机link相对于父link的偏移。我设定在X轴方向往前0.1米，也就是放在Iris机身前方的位置。这个位置是模拟D435i装在机头下方的效果。如果你的视觉算法依赖相机和机体中心的外参，修改这个pose之后，记得把外参也同步更新。
然后是joint。在文件末尾、</model>之前添加：
<joint name="camera_d435i_joint" type="fixed"> <parent>base_link</parent> <child>camera_d435i</child> </joint>type="fixed"是固定关节，相机不会转动。如果你以后想做云台相机，可以改成revolute关节类型，并添加一个控制插件，但那是另一个话题，先不展开。
3.3 在link里添加D435i传感器定义
现在是在camera_d435i这个link内部、<collision>之后添加传感器。这是最核心的部分。D435i一共三个关键传感器：RGB相机、深度相机、IMU。
在Gazebo Classic中，RGB和深度相机用的是两个不同的插件：
- RGB相机：
libgazebo_ros_camera.so（ROS+Gazebo桥接，发布ROS图像话题） - 深度相机：
libgazebo_ros_depth_camera.so（发布深度图像和点云）
如果你没装ROS，也可以用PX4自带的CameraPlugin（libCameraPlugin.so），但那个插件不发布ROS话题，只能通过Gazebo传感器数据接口访问，对视觉开发来说不太方便。所以下面我以gazebo_ros插件为例，这也是社区最常用的方案。
先把RGB相机加进去：
<sensor name="camera_rgb" type="camera"> <pose>0 0 0 0 0 0</pose> <camera> <horizontal_fov>1.21</horizontal_fov> <image> <width>640</width> <height>480</height> </image> <clip> <near>0.2</near> <far>20</far> </clip> </camera> <always_on>1</always_on> <update_rate>30</update_rate> <plugin name="camera_rgb_plugin" filename="libgazebo_ros_camera.so"> <ros> <namespace>d435i</namespace> <remapping>image_raw:=rgb/image_raw</remapping> <remapping>camera_info:=rgb/camera_info</remapping> </ros> <camera_name>camera_rgb</camera_name> <image_topic_name>image_raw</image_topic_name> <camera_info_topic_name>camera_info</camera_info_topic_name> <frame_name>camera_d435i</frame_name> <hack_baseline>0.0</hack_baseline> </plugin> </sensor>这里要解释几个参数：
<horizontal_fov>是水平视场角，单位弧度。D435i的RGB相机水平FOV约69.4度，转成弧度约1.21。- 分辨率这里先用640×480，降低CPU负载。真机D435i可以输出1920×1080，但仿真里跑那么高分辨率没什么意义，反而严重拖慢渲染。
<update_rate>30</update_rate>是帧率，D435i默认30fps。
然后是深度相机。深度相机在SDF里的type是depth，插件用libgazebo_ros_depth_camera.so：
<sensor name="camera_depth" type="depth"> <pose>0 0 0 0 0 0</pose> <camera> <horizontal_fov>1.52</horizontal_fov> <image> <width>640</width> <height>480</height> </image> <clip> <near>0.105</near> <far>10</far> </clip> </camera> <always_on>1</always_on> <update_rate>30</update_rate> <plugin name="camera_depth_plugin" filename="libgazebo_ros_depth_camera.so"> <ros> <namespace>d435i</namespace> <remapping>depth/image_raw:=depth/image_raw</remapping> <remapping>depth/camera_info:=depth/camera_info</remapping> <remapping>points:=depth/points</remapping> </ros> <camera_name>camera_depth</camera_name> <image_topic_name>image_raw</image_topic_name> <camera_info_topic_name>camera_info</camera_info_topic_name> <point_cloud_topic_name>points</point_cloud_topic_name> <frame_name>camera_d435i</frame_name> <hack_baseline>0.0</hack_baseline> </plugin> </sensor>注意<horizontal_fov>是1.52弧度，约87度，这是D435i深度相机的水平FOV。深度范围设为0.105米到10米，这非常接近D435i的真实深度量程（真实D435i最小深度约0.105米，最大约10米，取决于分辨率设置）。这里的<near>和<far>就是深度相机的最近和最远探测距离，直接决定深度图像的有效范围。
IMU传感器相对简单，D435i内部有一个BMI055六轴IMU，仿真里用一个IMU sensor替代即可：
<sensor name="imu_d435i" type="imu"> <always_on>1</always_on> <update_rate>200</update_rate> <imu> <angular_velocity> <x>0</x><y>0</y><z>0</z> </angular_velocity> <linear_acceleration> <x>0</x><y>0</y><z>0</z> </linear_acceleration> </imu> <plugin name="imu_plugin" filename="libgazebo_ros_imu_sensor.so"> <ros> <namespace>d435i</namespace> <remapping>imu:=imu/data</remapping> </ros> <frame_name>camera_d435i</frame_name> </plugin> </sensor>IMU更新率设200Hz是为了匹配D435i真实IMU的输出频率范围（真实D435i IMU最高可到400Hz，一般跑200Hz）。这里频率越高，仿真CPU占用越大，所以200Hz是个比较平衡的选择。
3.4 让PX4加载自定义模型
文件改完了，还差一步：告诉PX4去加载iris_d435i而不是默认的iris。这一步有几种做法，最简单的是用环境变量指定。
在启动PX4仿真时，用PX4_SIM_MODEL指定机型名称：
cd ~/PX4-Autopilot make px4_sitl gazebo-classic PX4_SIM_MODEL=iris_d435i但注意，这种指定方式依赖于makefile里是否注册了iris_d435i这个机型。如果没有，PX4会回退到默认的iris机型。这时候就要去ROMFS/px4mu_hal/init.d-posix/airframes/目录下找对应的机型定义。
这里有个更省事的办法：直接修改环境变量让Gazebo加载指定模型。在~/.bashrc中添加：
export PX4_SIM_MODEL=iris_d435i export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:~/PX4-Autopilot/Tools/sitl_gazebo/models然后启动：
source ~/.bashrc cd ~/PX4-Autopilot roslaunch px4 mavros_posix_sitl.launch vehicle:=iris_d435i # 使用ROS时 # 或者 make px4_sitl gazebo-classic # 使用make时说实话，我实际用下来最稳定的方式还是用make px4_sitl gazebo-classic PX4_SIM_MODEL=iris_d435i。用make方式启动时注意看终端输出有没有[run_gazebo] Spawning iris_d435i这样的日志。
4. 传感器配置参数深度解析
4.1 D435i真实参数和仿真参数的对应关系
在配置过程中，最容易犯的错就是把参数完全照抄D435i手册，导致仿真性能爆炸。核心要理解：仿真里设置参数的目标是"仿真保真度和性能的平衡"，而不一定是"完全复刻真机"。
我整理了这样一张对照表，方便你参考：
| 参数 | 真实D435i | 仿真建议值 | 说明 |
|---|---|---|---|
| RGB分辨率 | 1920x1080 | 640x480 | 仿真里高分辨率严重拖慢渲染，640x480已经足够跑视觉算法 |
| 深度分辨率 | 1280x720 | 640x480 | 同上，且深度图数据量大 |
| RGB FOV | 69.4°x42.5° | 1.21 rad（约69.4°） | 保持一致 |
| 深度FOV | 87°x58° | 1.52 rad（约87°） | 保持一致 |
| 帧率 | 30fps | 30fps | 保持一致 |
| 深度范围 | 0.105m~10m | 0.105m~10m | 保持一致 |
| IMU频率 | 最高400Hz | 200Hz | 兼顾真实感和性能 |
为什么分辨率建议降低？我实测过，在640×480分辨率下，Gazebo渲染一帧图像大约需要8~12毫秒；如果开到1920×1080，这个时间会飙升到40毫秒以上，直接导致仿真速度变慢，无人机控制频率下降，整个仿真步长变得不稳定。对视觉SLAM算法验证来说，640×480完全够用。
4.2 深度数据的编码和话题类型
Gazebo的深度相机插件发布的深度话题，图像编码是32位的浮点深度值，单位是米。这意味着你订阅/d435i/depth/image_raw话题时，拿到的Image消息的encoding字段是32FC1，每个像素的数值代表该点到相机平面的距离。
这和真实D435i的深度输出格式不完全一样。真实D435i的深度图（通过realsense驱动发布）是16位无符号整数，单位是毫米，数值范围0~65535。所以如果你写了一个针对真实D435i的深度处理代码，把它接到仿真话题上，需要对深度单位做一次转换。
具体来说，假设你在真实D435i上拿到的是毫米单位的uint16深度图，那在仿真中需要这样转换：
# 在ROS中订阅仿真深度话题后，把float32米转成uint16毫米 rostopic echo /d435i/depth/image_raw | head -20 # 你会看到浮点深度值，比如2.5表示2.5米而ROS的depth_image_proc包可以帮你做这种转换，也可以用PCL的点云转换节点。这些细节在仿真和真机之间切换时特别容易踩坑，提前心里有数。
表中的"hack_baseline"参数补充一下：它通常用于双目相机的深度估计，D435i是主动立体视觉方案，自身有双目结构，但在Gazebo里我们直接用深度相机类型，不需要设置基线，设0就好。
4.3 如何检查相机外参是否正确
相机的<pose>设置的偏移，会直接影响视觉算法里的坐标变换。在Gazebo里，传感器的坐标系原点位于link的<pose>指定位置，方向默认和Gazebo世界坐标系对齐（如果没额外旋转）。
我在实际项目中会把相机外参打印出来做一个快速验证：启动仿真后，用rosrun tf tf_echo base_link camera_d435i查看base_link到camera_d435i的坐标变换，确认平移量的数值和SDF里设的一致。
如果你期望的相机方向是朝下看的（比如用于着陆检测），你需要把<pose>里加一个旋转，比如俯仰角-90度：
<pose>0.10 0 0 0 -1.5708 0</pose>这里-1.5708弧度就是-90度。值得注意的是，相机link的默认方向是X轴朝前，即朝向无人机前进方向，这对大部分视觉任务来说已经够用。如果你想模拟朝下的D435i，就需要改这个旋转，同时你的外参代码也要同步改。
5. 编译、启动与验证
5.1 完整启动流程
配置好模型后，重新编译并启动仿真。这里分两种情况：
情况一：没有ROS，只装PX4和Gazebo
cd ~/PX4-Autopilot make px4_sitl gazebo-classic PX4_SIM_MODEL=iris_d435i情况二：装了ROS，想同时看到图像话题
先启动PX4 Gazebo仿真，再单独启动ROS节点。这里推荐用launch文件方式：
cd ~/PX4-Autopilot roslaunch px4 mavros_posix_sitl.launch vehicle:=iris_d435i如果vehicle:=iris_d435i报错说不认识这个机型，你可以先检查launch文件里引用的机型列表，或者在ROMFS/px4mu_hal/init.d-posix/airframes/里添加一个对应的机型配置文件。这也是为什么我推荐直接用make方式，少一层麻烦。
启动后观察终端输出，正常情况下会有类似下面的日志出现：
INFO [simulator] Waiting for simulator data... INFO [simulator] Got MAVLink message from SITL simulator INFO [logger] logger started同时Gazebo窗口里应该出现一架Iris，机头位置挂着一个黑色小方块，那就是D435i的简化外观模型。
5.2 在Gazebo里验证传感器
在Gazebo窗口中，顶部菜单栏可以选择Window->Topic Visualization，选择相机的发布话题，比如/gazebo/default/iris_d435i/camera_d435i/camera_rgb/image_raw。选中后，你会看到一个弹窗显示渲染出的画面。如果画面是正常的彩色图像，说明RGB相机在工作。
如果画面全是黑色，常见原因是场景中光照不足。Gazebo默认世界有太阳光和环境光，但如果你在室内场景中测试，可能需要手动添加一个光源模型。
5.3 在ROS里验证话题数据
这是最核心的验证步骤。在另一个终端运行以下命令：
# 列出话题 rostopic list | grep d435i正常能看到以下话题：
/d435i/rgb/image_raw/d435i/rgb/camera_info/d435i/depth/image_raw/d435i/depth/camera_info/d435i/depth/points/d435i/imu/data
用图像工具查看画面：
rqt_image_view打开后在下拉菜单里选择/d435i/rgb/image_raw就能看到彩色画面，选/d435i/depth/image_raw能看到深度图（记得在rqt_image_view里把动态范围设置为合适的值，否则深度图会显示成一片黑或一片白）。
如果要验证点云数据，可以用：
rosrun rviz rviz添加PointCloud2显示，话题选/d435i/depth/points。你会看到机头前方物体被渲染成点云。这是验证深度相机是否正常工作的最直观方式。
5.4 在QGroundControl里确认PX4状态
QGroundControl（QGC）是PX4的地面站软件，启动PX4的SITL仿真后，QGC会自动连接上，默认端口是14550（UDP）。连接成功后，在QGC的MAVLink Inspector里可以看到IMU、GPS等数据在实时变化。
但注意：QGC默认看不到D435i的视觉数据，因为D435i的相机数据是通过ROS话题发布的，不是通过MAVLink协议传输的。只有在使用MAVLink的MAV_CMD_SET_CAMERA_MODE或特定视觉流协议时，QGC才能显示机载视频流，那需要额外配置，一般视觉开发用不到。
所以，QGC在D435i挂载验证里的作用，主要是确认PX4飞控本身工作正常、没有因为新增模型导致姿态估计发散。如果PX4日志出现大量EKF IMU相关报错，说明你的相机link质量或者惯性参数设置干扰了飞控的姿态估计。
6. 常见问题与故障排查实录
这块内容是踩坑记录，也是我认为最有价值的部分。以下每个问题都是我在实际配置过程中遇到过的，不是从网上抄来的，按优先级从高到低排列。
6.1 为什么Gazebo界面一直在闪
这个标题非常精准。我搜索热词里看到"为什么gazebo界面一直在闪"，这是Gazebo 11一个非常经典的问题。
解决办法分两步排查：
第一步，检查显卡驱动。如果用的是NVIDIA显卡，先看驱动是否正常：
nvidia-smi如果命令不存在，说明驱动没装，装一下。如果命令正常但Gazebo还是闪，尝试把Gazebo的渲染引擎换成软件渲染：
export LIBGL_ALWAYS_SOFTWARE=1 make px4_sitl gazebo-classic PX4_SIM_MODEL=iris_d435i这个方法能暂时解决开花板显卡兼容性问题，但代价是渲染性能大幅下降，图像帧率会低很多。
第二步，如果显卡驱动没问题但还是闪，多半是Gazebo的ogre渲染插件和你的系统桌面环境冲突。在Ubuntu 20.04 + GNOME下比较常见。试一下：
export GAZEBO_PLUGIN_PATH=$GAZEBO_PLUGIN_PATH:~/PX4-Autopilot/build/px4_sitl_default/build_gazebo export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/PX4-Autopilot/build/px4_sitl_default/build_gazebo如果这个也没用，就考虑把GNOME的Wayland会话切到Xorg。这个方法当时帮我解决了闪屏问题。
6.2 仿真发散：无人机乱飘、疯狂翻滚
这个问题在我第一次挂载相机后遇到了。现象是无人机启动后无法保持悬停，姿态乱跳，甚至直接在地上打转。
原因基本可以锁定在新增的link质量/惯性参数上。如果相机link的<mass>设得太大（比如超过0.5kg），或者惯性张量数值不合理（比如izz取0），飞控的EKF会发现机体的动力学响应和预期不匹配，导致姿态估计发散。
解决办法：
- 把相机link质量设成接近真实值0.13kg。
- 惯性张量不要全设0，三个轴的转动惯量设成合理的微小值，比如我前面示例中的
2.5e-5。 - 最简单粗暴的验证方式：把相机link的
<inertial>整段删掉，Gazebo会自动按几何体估计惯性。这个方法对解耦问题很有效，但缺点是转动惯量可能不太准。
6.3 D435i深度话题没有数据
现象：/d435i/depth/image_raw话题存在，但发布频率为0，或者图像全黑。
这是插件加载失败或者深度范围设置过小的典型表现。排查步骤：
# 查看话题发布频率 rostopic hz /d435i/depth/image_raw如果hz为0：
- 看Gazebo启动终端的报错，搜索
depth相关日志。如果报缺库，检查libgazebo_ros_depth_camera.so路径是否正确，一般在这个目录下：find /opt/ros -name "libgazebo_ros_depth_camera.so" - 检查
<clip><near>和<far>的数值。如果near设成0，Gazebo可能会出现数值除零错误，导致深度图像无法生成。建议near不要小于0.05。 - 检查场景里是否真的有物体在相机视野内。如果相机朝向天空，深度图自然是一片空白，因为远处的天空超出了far的10米范围。把无人机摆到地面附近，让地面出现在画面里，深度图就会有数据了。
还有一个细节：如果你的深度话题能收到数据但图像全黑，检查一下是不是rqt_image_view的显示范围问题，把显示范围改成0~10米，就会看到有层次的深度图像了。
6.4 CPU占用过高，Gazebo卡到跑不动
这个问题在添加D435i后尤其明显，因为相机渲染是CPU密集任务。我实测下来，单个RGB相机+单个深度相机在640×480分辨率下，CPU占用会增加30%~50%。如果分辨率开到1280×720，占用直接翻倍，无人机控制频率会被拖累到无法稳定飞行。
优化手段：
- 分辨率降到640×480，这是最有效的手段。
- 帧率尝试降到15fps。如果只是做SLAM建图，15fps也够用，CPU占用会明显降低。
- 如果有多余GPU资源，把Gazebo的渲染交给GPU。检查
~/.gazebo/gui.ini和rendering相关配置，确保没有强制软件渲染。 - 关闭场景中不需要的视觉效果，比如阴影和反射。在Gazebo的
World设置里可以关闭。
6.5 模型加载不了，Gazebo显示一个空世界或者模型是粉红色
粉红色模型是Gazebo找不到材质的经典表现。原因一般是路径问题：model.config引用的SDF文件路径不对，或者SDF里引用的材质纹理路径不存在。
排查步骤：
# 检查模型路径是否正确 echo $GAZEBO_MODEL_PATH # 确认模型目录结构 ls ~/PX4-Autopilot/Tools/sitl_gazebo/models/iris_d435i/如果目录下没有model.config，Gazebo无法识别这个模型。另外确认model.config里的文件名和实际SDF文件名一致，大小写敏感。
如果你是直接修改了官方的iris.sdf，但没有同步修改model.config里的模型名，也可能出现冲突。所以还是建议复制一份再改。
6.6 VS Code连接Cache/Iris数据库相关
搜索热词里有"vs code连接cache\iris数据库"，这和本文关系不大，但看到"iris"容易让人混淆。这里顺手澄清一下：飞控的Iris机型数据库和数据库管理系统不是一回事。在PX4开发过程中，如果你用VS Code调试PX4代码，需要的工具是CMake、gdb或者px4的debug脚本，而不是数据库连接。别被关键词带跑偏。
7. 从仿真到真机迁移的几个实用建议
虽然题目是仿真配置，但我知道很多人最终目的是把算法部署到真机上。这里分享几个迁移过程中的心得，也算给本文收个尾。
仿真里配置的D435i模型，虽然参数和真实D435i高度一致，但迁移时你还是要注意以下几点：
第一，真机的D435i需要先标定。我这里说的标定不是指相机内参，而是指相机和飞控之间的外参标定，也就是相机相对于机体坐标系的安装位置和旋转。仿真里你直接知道外参，因为是你自己设的，但真机装上去之后，精度再高的机械结构也会有偏差，需要用标定板或者手工测量来获取外参，然后填入PX4的传感器外参配置里。
第二，真实D435i的深度数据出场默认是毫米单位的16位整数，仿真里是米单位的32位浮点。这个我在前面提到过，这里再强调一遍，因为我在这个转换上至少浪费了半天时间排查深度值为什么比预期小1000倍。
第三，真机上D435i的USB带宽占用很高，跑1080p分辨率+30fps时USB带宽会接近极限。建议真机上也从640×480@15fps开始跑，稳定后再逐步提高。
第四，真机的D435i需要安装Intel RealSense SDK（librealsense），并且要注意内核补丁。这个补丁是Intel提供的，用来解决UVC摄像头在Linux下的带宽问题，不装的话帧率上不去。仿真阶段没有这个问题，所以很多人忽略了。
第五，如果你在仿真里用D435i的IMU数据，建议真机上先把D435i的IMU和飞控的IMU做一次时延测量和联合标定。D435i内部IMU和视觉数据之间有固定的时间戳偏移，但和飞控的时间同步需要自己做，这直接影响视觉惯性里程计（VIO）的精度。PX4源码里有一个ekf2模块，很多视觉融合问题最后都出在时延标定上，而不是算法本身。
我在实际开发中感受到，仿真的最大价值是帮你在一天内跑通算法链路，而不是在真机上烧几十块电池去调试接口问题。把D435i在仿真里配置好，你后面写目标跟踪、避障、SLAM的代码时，可以全身心放在算法逻辑上，而不是被传感器采集、格式转换这些琐事打断。这也是我写这篇教程的初衷。希望你的Iris+D435i仿真能一次起飞成功。
