这份文档按现象排查。先确认你使用的是 Ubuntu 20.04 + ROS 2 Foxy。代码尽量兼容 Ubuntu 24.04 和 26.04，但这两个系统没有完整测试。
先检查 extension 路径是不是加错了。应该添加 Pegasus 的 extensions 目录，不是 pegasus.simulator 子目录。
常见路径：
/home/<用户名>/PegasusSimulator/extensions/root/PegasusSimulator/extensions再检查 Pegasus 是否安装到了 Isaac Sim 自己的 Python 环境：
xxxxxxxxxxexport ISAACSIM_PYTHON=/path/to/isaac-sim/python.sh$ISAACSIM_PYTHON -m pip show pegasus.simulator如果没有输出，重新安装：
xxxxxxxxxxcd ~/PegasusSimulator/extensions/pegasus.simulator/path/to/isaac-sim/python.sh -m pip install -e pegasus.simulator安装 Pegasus 插件时应使用 Isaac Sim 自带的 Python，不应使用 conda Python 或系统 Python。Isaac Sim 查找插件时使用的是自己的 Python 环境。
先看 Pegasus UI 里的 PX4 路径。路径要指向 PX4-Autopilot 根目录，例如：
xxxxxxxxxx/home/<用户名>/PX4-Autopilot然后在终端检查 PX4 是否能单独编译：
xxxxxxxxxxcd ~/PX4-Autopilotmake px4_sitl_default none如果这里失败，应先处理 PX4 依赖或源码版本，再检查 Pegasus 配置。
按这个顺序查：
xxxxxxxxxx1. Isaac Sim timeline 是否正在播放2. Pegasus 是否选择了 PX4 backend3. PX4 SITL 进程是否启动4. QGC 是否已经打开5. MAVLink 端口是否被其他程序占用可以用下面命令看 PX4 进程：
xxxxxxxxxxps aux | grep px4 | grep -v grep如果 PX4 没启动，回到 Pegasus UI 检查 PX4 路径和 backend 配置。
QGC 的提示通常比终端更直接。常见原因：
不应跳过这些检查。应先确认官方 Iris 可以 arm，再替换为比赛无人机。
/fmu/* 话题先 source ROS 2 和 px4_msgs 工作空间：
xxxxxxxxxxsource /opt/ros/foxy/setup.bashsource ~/px4_ros_ws/install/setup.bash再查话题：
xxxxxxxxxxros2 topic list --no-daemon | grep /fmu如果没有输出，检查 Micro XRCE-DDS Agent：
xxxxxxxxxxMicroXRCEAgent udp4 -p 8888还要确认 PX4 侧 uXRCE-DDS Client 正在运行。没有 Agent，ROS 2 通常收不到 PX4 的 /fmu/out/* 数据，也发不进 /fmu/in/* 控制话题。
/fmu/*，但 /fmu/out/vehicle_local_position 没数据不同 PX4 / px4_msgs 版本的话题名可能不同。先查：
xxxxxxxxxxros2 topic list --no-daemon | grep vehicle_local_position可能出现：
xxxxxxxxxx/fmu/out/vehicle_local_position/fmu/out/vehicle_local_position_v1分别试：
xxxxxxxxxxros2 topic echo /fmu/out/vehicle_local_position --onceros2 topic echo /fmu/out/vehicle_local_position_v1 --once如果两个都没有数据，通常是 PX4 没有有效 local position，或者 XRCE-DDS 链路还没通。
run_control_menu.sh 报 Python 或 ROS 2 错误先退出 conda：
xxxxxxxxxxconda deactivate再运行：
xxxxxxxxxxcd /home/robot-a/Desktop/drone_training_github_release./run_control_menu.sh脚本默认使用 /usr/bin/python3，并优先 source：
xxxxxxxxxx/opt/ros/foxy/setup.bash如果你的 px4_msgs 不在 ~/px4_ros_ws，可以手动指定：
xxxxxxxxxxexport PX4_ROS_WS=/path/to/px4_ros_ws./run_control_menu.shPX4 不是收到一次目标点就进入 Offboard。它要求外部控制器持续发布 setpoint。
检查三件事：
xxxxxxxxxxros2 topic hz /fmu/in/offboard_control_moderos2 topic hz /fmu/in/trajectory_setpointros2 topic echo /fmu/out/vehicle_status --once如果话题频率断断续续，或者先切模式再发 setpoint，PX4 可能拒绝 Offboard。正确顺序是：
xxxxxxxxxx1. 等待 local position 有效2. 先持续发布 OffboardControlMode 和 TrajectorySetpoint3. 再发送切 Offboard 命令4. 再发送 arm 命令move 1 0 0 后无人机不动move 不是起飞命令。它只是在当前目标点基础上修改目标位置。
先执行：
xxxxxxxxxxstatustakeoff 1.0statusmove 1 0 0如果无人机已经通过 QGC 起飞，先用：
xxxxxxxxxxoffboardmove 1 0 0还要确认 PX4 当前已经进入 OFFBOARD，并且 local position 有数据。
控制菜单使用 PX4 local / NED 坐标：
xxxxxxxxxxx = Northy = Eastz = Down所以上升是 z 变小，不是变大。
例子：
xxxxxxxxxxtakeoff 1.0 # 目标 z = current_z - 1.0move 0 0 -0.2 # 上升约 0.2mmove 0 0 0.2 # 下降约 0.2m如果把 ENU 的 z=+1 直接发给 PX4，飞机通常会往下走。
px4_msgs 版本不匹配典型现象：
/fmu/out/vehicle_status 变成 /fmu/out/vehicle_status_v3。/fmu/out/vehicle_local_position 变成 /fmu/out/vehicle_local_position_v1。PX4 v1.14.x 推荐使用：
xcd ~/px4_ros_ws/srcgit clone --branch release/1.14 https://github.com/PX4/px4_msgs.gitcd ~/px4_ros_wssource /opt/ros/foxy/setup.bashcolcon build --symlink-installsource install/setup.bash如果你换了 PX4 版本，px4_msgs 分支也要一起换。
Ubuntu 20.04 常见原因是缺 libfuse2：
xxxxxxxxxxsudo apt updatesudo apt install -y libfuse2然后重新授权并启动：
xxxxxxxxxxcd ~/Downloadschmod +x QGroundControl.AppImage./QGroundControl.AppImage如果仍然打不开，再检查 AppImage 是否有执行权限。
run_import_asset.sh 默认会找常见 Isaac Sim 路径。如果你的 Isaac Sim 不在默认位置，手动指定：
xxxxxxxxxxexport ISAACSIM_BIN=/path/to/isaacsimexport PEGASUS_EXTENSION=/path/to/PegasusSimulator/extensions/pegasus.simulatorcd /home/robot-a/Desktop/drone_training_github_release./run_import_asset.shISAACSIM_BIN 应该指向 Isaac Sim 启动程序，不是 Python，也不是安装目录。
这通常不是 ROS 2 控制代码的问题。先用官方 Iris 验证 Pegasus、PX4、QGC 链路。如果 Iris 能飞，但比赛无人机不能飞，重点查 USD 和 Pegasus 绑定：
/World/quadrotor 是否存在。/World/quadrotor/body 是否是刚体。能显示只说明 USD 加载成功。能飞还需要 Pegasus 找到可控制的机体和旋翼结构。
遇到问题时，不应直接修改代码。建议按以下顺序排查：
xxxxxxxxxx1. Isaac Sim 能否启动2. Pegasus 插件是否启用3. 官方 Iris 能否通过 QGC 起飞4. 是否能看到 /fmu/out/* 话题5. 是否能读取 local position6. 控制菜单能否 status7. takeoff 1.0 是否进入 Offboard 并起飞8. move 是否改变目标点9. 再换比赛无人机资产前一步未通过时，不应跳到下一步。按顺序检查可以更快判断问题所在层级。