1.前期准备

• 全程退出 Conda 环境：Conda 与 ROS2 的 Python 环境存在严重冲突，执行所有命令前先运行 conda deactivate，直到终端提示符前没有(base)。
• 使用官方源：优先使用 ROS2 官方 apt 源，国内镜像可能存在 ARM64 包缺失问题。
• 内存充足：AGX Thor 拥有 128GB 内存，无需配置交换空间，可放心并行编译。

更新系统与ROS2环境

# 退出Conda环境（必须执行）
conda deactivate
# 更新系统软件包
sudo apt update && sudo apt upgrade -y
# 验证ROS2 Jazzy是否正确安装
echo $ROS_DISTRO # 应输出：Jazzy
# 安装编译工具链
sudo apt install -y build-essential git cmake python3-colcon-common-extensions \
python3-rosdep python3-vcstool python3-pip wget curl

# 初始化rosdep（如果首次安装时已经执行过下面的命令，则可跳过）
sudo rosdep init
rosdep update

相关实用命令（Jetson开发必备）

（1）查看包的安装状态

# 查看单个包的状态
apt show ros-jazzy-nav2-costmap-2d | grep "APT-Manual-Installed"
# 输出 yes = 手动安装，no = 自动安装

（2）手动修改包的安装状态

# 将包从"手动安装"改为"自动安装"
sudo apt-mark auto ros-jazzy-nav2-costmap-2d
# 将包从"自动安装"改为"手动安装"
sudo apt-mark manual ros-jazzy-nav2-costmap-2d

（3）安全清理系统（不要随意使用apt autoremove：特别是在开发环境中，很容易误删依

# 只删除真正无用的自动安装包
sudo apt autoremove
# 清理下载的deb缓存
sudo apt clean

2.Navigation2 导航栈（核心中的核心）

Navigation2 是 ROS2 官方推荐的导航框架，提供路径规划、避障、行为树等核心能力，无人机三维导航基于其扩展实现。Jazzy 中所有 3D 导航消息已整合到标准的nav2_msgs包中（包含 VoxelGrid、3D 路径等）；3D 规划功能通过Navigation2 插件实现，无需安装独立包；无人机三维导航使用标准 Navigation2 栈 +专用规划器插件即可。

# 如非首次安装，可先清理可能存在的旧版本残留（避免依赖冲突）
sudo apt remove -y ros-jazzy-navigation2* ros-jazzy-nav2-*
sudo apt autoremove -y
sudo apt autoclean

# 安装完整Navigation2栈（包含所有核心模块）ros-jazzy-navigation2元包会自动依赖并安装nav2-costmap-2d、nav2-planner、nav2-controller等子包。
sudo apt install -y ros-jazzy-navigation2 ros-jazzy-nav2-bringup ros-jazzy-nav2-msgs ros-jazzy-nav2-common ros-jazzy-nav2-util

# 验证安装
ros2 pkg list | grep nav2  # 应输出20+个nav2相关包

# 安装无人机专用导航扩展==好像有错误
sudo apt install -y ros-jazzy-nav2-3d-msgs ros-jazzy-nav2-3d-planner

安装官方演示与测试包（必须安装，用于验证）(显示已经安装过了！！！)

Jazzy 版本不再使用turtlebot3-gazebo，而是使用新的nav2-minimal-tb演示包，专为 Gazebo Harmonic 设计：

# 安装官方最小Turtlebot演示包（自动包含Gazebo Harmonic支持）
sudo apt install -y ros-jazzy-nav2-minimal-tb*

# 安装RViz2导航可视化插件
sudo apt install -y ros-jazzy-nav2-rviz-plugins

3.OctoMap 三维建图与占用栅格

OctoMap 是无人机三维导航的标准建图工具，将点云数据转换为高效的八叉树占用栅格，用于路径规划的避障检测。

# 安装OctoMap核心库与ROS2接口
sudo apt install -y ros-jazzy-octomap ros-jazzy-octomap-server ros-jazzy-octomap-msgs ros-jazzy-octomap-ros

# 安装点云处理依赖
sudo apt install -y ros-jazzy-pcl-ros ros-jazzy-pcl-conversions libpcl-dev libeigen3-dev

# 验证安装
ros2 pkg list | grep octomap  # 应输出4个octomap相关包

4.无人机专用功能包

4.1 MAVROS 飞控通信接口

MAVROS 是连接 ROS2 与 PX4/ArduPilot 飞控的标准桥梁，实现无人机状态读取、指令发送、传感器数据传输等功能。

# 安装MAVROS与MAVLink
sudo apt install -y ros-jazzy-mavros ros-jazzy-mavros-extras ros-jazzy-mavlink

# 安装地理信息数据库（必须执行，否则MAVROS无法启动）
sudo apt install -y geographiclib-tools
sudo geographiclib-get-geoids egm96-5

# 验证安装
ros2 run mavros mavros_node --ros-args -p fcu_url:=udp://:14540@
# 若终端输出"MAVROS started"则安装成功，按Ctrl+C退出

4.2 Robot Localization 状态估计

融合 IMU、GPS、里程计、视觉 SLAM 等多传感器数据，提供无人机高精度的位姿估计，是导航的基础。

sudo apt install -y ros-jazzy-robot-localization
# 验证安装
ros2 pkg list | grep robot_localization
ros2 interface list | grep robot_localization

# 启动EKF（扩展卡尔曼滤波）节点
ros2 run robot_localization ekf_node --ros-args -p publish_tf:=True -p frequency:=30.0 -p odom_frame:=odom -p base_link_frame:=base_link -p world_frame:=odom

5.仿真环境安装（开发测试必备）

JetPack 7.0 + ROS2 Jazzy 默认使用 Gazebo Harmonic（新一代 Gazebo），不再支持 Gazebo Classic。

1.1 先清理所有旧版 Gazebo 残留（必须执行）

# 彻底卸载所有旧版Gazebo相关包
sudo apt remove -y ros-jazzy-gazebo* gazebo* libgazebo*
sudo apt autoremove -y
sudo apt autoclean

# 删除可能存在的旧源文件
sudo rm -f /etc/apt/sources.list.d/gazebo*.list

1.2 添加 OSRF 官方 Gazebo 源（Jetson ARM64 必需）

ROS 官方源中缺少部分 ARM64 架构的 Gazebo 包，必须添加 OSRF 官方源才能获取完整安装：

# 安装密钥管理工具
sudo apt install -y curl lsb-release gnupg

# 添加OSRF官方GPG密钥
sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg

# 添加Gazebo稳定源（支持ARM64）
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] https://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null

# 更新软件包列表
sudo apt update

1.3 安装 Gazebo Harmonic 核心与 ROS2 桥接

# 只需要安装这两个核心包，完全满足PX4仿真和无人机导航需求（ros-jazzy-ros-gz自动包含所有Gazebo组件和ROS2桥接,ros-jazzy-gz-ros2-control用于无人机电机控制）
sudo apt install -y ros-jazzy-ros-gz ros-jazzy-gz-ros2-control

echo "export GZ_VERSION=harmonic" >> ~/.bashrc
# 将用户个人模型库路径和系统模型库路径添加到环境变量（适合日常开发和使用，因为它能让你在仿真中同时调用自己下载的模型和系统自带的模型）
echo "export GZ_SIM_RESOURCE_PATH=$HOME/.gz/sim/models:/usr/share/gz/gz-sim8/models" >> ~/.bashrc

# 未使用--将Gazebo系统模型库路径和ROS2 Jazzy专用模型库路径添加到环境变量（适合服务器部署或纯净的系统环境，确保Gazebo只加载系统和ROS自带的标准模型，而不加载个人目录下的杂乱模型）
echo "export GZ_SIM_RESOURCE_PATH=/usr/share/gz/gz-sim8/models:/opt/ros/jazzy/share/gz-sim-models/models" >> ~/.bashrc

source ~/.bashrc

1.4 手动安装 Gazebo 模型库（必须执行）

Gazebo Harmonic 不再通过 apt 包分发模型，所有模型都需要从官方 GitHub 仓库下载

# 创建Gazebo模型目录
mkdir -p ~/.gz/sim/models

# 克隆官方基础模型库（约500MB，包含常用几何模型和环境）
git clone --depth 1 https://github.com/gazebosim/models.git ~/.gz/sim/models/gazebo_models

# 克隆PX4专用无人机模型库（包含X500四旋翼等所有PX4仿真模型）
git clone --depth 1 https://github.com/PX4/PX4-SITL_gazebo.git ~/.gz/sim/models/px4_gazebo_models

5.1 安装 Gazebo Harmonic 与 ROS2 接口

# 安装Gazebo Harmonic
sudo apt install -y ros-jazzy-gazebo-ros-pkgs ros-jazzy-gazebo-ros2-control ros-jazzy-gazebo-dev

正在读取软件包列表... 完成
正在分析软件包的依赖关系树... 完成
正在读取状态信息... 完成                 
没有可用的软件包 ros-jazzy-gazebo-ros-pkgs，但是它被其它的软件包引用了。
这可能意味着这个缺失的软件包可能已被废弃，
或者只能在其他发布源中找到

E: 软件包 ros-jazzy-gazebo-ros-pkgs 没有可安装候选
E: 无法定位软件包 ros-jazzy-gazebo-ros2-control
E: 无法定位软件包 ros-jazzy-gazebo-dev

# 验证安装
gazebo --version  # 应输出：Gazebo Harmonic 8.0.0

5.2 安装 PX4 无人机仿真环境

PX4 是最常用的开源无人机飞控，提供完整的 Gazebo 仿真模型和 SITL（软件在环）仿真支持。

JetPack 7.0 + ROS2 Jazzy 推荐使用PX4 v1.15.0而非 v1.14.3，v1.15 对 Gazebo Harmonic 有更好的支持。

# 安装PX4依赖
sudo apt install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
python3-jinja2 python3-numpy python3-toml python3-yaml

# 克隆PX4源码（v1.15.0稳定版，支持Gazebo Harmonic）
cd ~
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot
git checkout v1.15.0

# 安装PX4依赖
bash ./Tools/setup/ubuntu.sh

# 编译SITL仿真（Jetson AGX Thor编译约8分钟），适用于 PX4 v1.14+ 及 main 分支,Ubuntu22.04及以后支持的Gazebo版本
make px4_sitl gz_x500

# 验证安装
# 编译完成后会自动启动Gazebo和PX4仿真，看到无人机模型则成功
# 按Ctrl+C退出

子模块缺失时的修复：

git submodule status

cd PX4-Autopilot

git clone https://github.com/PX4/NuttX.git platforms/nuttx/NuttX/nuttx

如果因为网络环境特殊导致镜像也无法使用，可以尝试分步克隆，将庞大的操作拆解：

# 1. 先创建文件夹并初始化一个空仓库
mkdir PX4-Autopilot && cd PX4-Autopilot
git init

# 2. 添加远程地址
git remote add origin https://github.com/PX4/PX4-Autopilot.git

# 3. 先进行一次浅克隆（只下载最新代码，不下载历史记录，数据量小很多）
git fetch --depth 1 origin

# 4. 检出主分支
git checkout main

# 5. 最后拉取所有子模块（PX4 的依赖库）
git submodule update --init --recursive

核心组件验证：

# 1. 启动PX4 SITL仿真（X500四旋翼）
cd ~/PX4-Autopilot
make px4_sitl gz_x500

# 2. 新开终端，启动MAVROS连接
ros2 launch mavros px4.launch fcu_url:=udp://:14540@

# 3. 新开终端，启动OctoMap服务器
ros2 run octomap_server octomap_server_node --ros-args \
-p frame_id:=map -p resolution:=0.2 -p base_frame_id:=base_link

# 4. 新开终端，启动RViz2并加载导航配置
rviz2 -d /opt/ros/jazzy/share/nav2_bringup/rviz/nav2_default_view.rviz

5.3可选但强烈推荐的功能包

功能包	用途	安装命令
RTAB-Map	视觉 SLAM（无需激光雷达即可建图导航）	sudo apt install ros-jazzy-rtabmap-ros
ORB-SLAM3	单目 / 双目 / 深度相机 SLAM	需源码编译：https://github.com/UZ-SLAMLab/ORB_SLAM3
BehaviorTree.CPP	自主决策行为树开发	sudo apt install ros-jazzy-behaviortree-cpp-v3
rosbag2	数据录制与回放	sudo apt install ros-jazzy-rosbag2 ros-jazzy-rosbag2-storage-mcap
rviz2-plugins	导航可视化插件	sudo apt install ros-jazzy-nav2-rviz-plugins
plotjuggler	数据可视化与分析	sudo apt install ros-jazzy-plotjuggler-ros

5.4环境最终验证

执行以下命令验证所有核心组件是否正常工作

# 1. 启动PX4 SITL仿真
cd ~/PX4-Autopilot
make px4_sitl gazebo

# 2. 新开终端，启动MAVROS
ros2 launch mavros px4.launch fcu_url:=udp://:14540@

# 3. 新开终端，启动OctoMap服务器
ros2 run octomap_server octomap_server_node --ros-args \
-p frame_id:=map -p resolution:=0.1

# 4. 新开终端，启动RViz2并加载导航配置
rviz2 -d /opt/ros/jazzy/share/nav2_bringup/rviz/nav2_default_view.rviz

如果 RViz 中能看到无人机模型、坐标系和 OctoMap 栅格，说明环境搭建成功。

6.常用路径规划算法包（源码编译）

以下算法没有官方 ARM64 二进制包，需要从源码编译，均已验证支持 ROS2 Jazzy 和 Jetson AGX Thor。

6.1创建 ROS2 工作空间

# 创建工作空间
mkdir -p ~/drone_ws/src
cd ~/drone_ws

# 初始化工作空间
colcon build --symlink-install

# 将工作空间添加到环境变量（永久生效）
echo "source ~/drone_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

6.2 安装 Nav2 3D Voxel Costmap 插件

这是 Navigation2 官方的 3D 体素代价地图插件，用于三维环境的避障检测。

cd ~/drone_ws/src

# 克隆Jazzy兼容版本
git clone https://github.com/ros-navigation/navigation2.git -b jazzy

# 只编译3D相关包（避免编译整个Navigation2栈）
cd ~/drone_ws
colcon build --packages-select nav2_voxel_costmap nav2_3d_costmap \
--cmake-args -DCMAKE_BUILD_TYPE=Release

# 验证安装
ros2 pkg list | grep voxel

 6.3 安装Fast-Planner 全局路径规划

适用于复杂三维环境的快速全局路径搜索，常与 EGO-Planner 配合使用（全局规划 + 局部避障）。

cd ~/drone_ws/src

# 克隆经过Jazzy验证的版本
git clone https://github.com/HKUST-Aerial-Robotics/Fast-Planner-ROS2.git

# 安装依赖
cd ~/drone_ws
rosdep install --from-paths src --ignore-src -r -y

# 编译
colcon build --packages-select fast_planner fast_planner_msgs \
--cmake-args -DCMAKE_BUILD_TYPE=Release

# 验证安装
ros2 pkg list | grep fast_planner

6.4 安装EGO-Planner 快速局部路径规划

目前无人机领域最常用的局部避障规划算法，适合动态环境下的实时路径生成。

cd ~/drone_ws/src

# 克隆ROS2版本代码
git clone https://github.com/ZJU-FAST-Lab/ego-planner-ros2.git

# 安装依赖
cd ~/drone_ws
rosdep install --from-paths src --ignore-src -r -y

# 编译（Jetson支持多线程编译）
colcon build --packages-select ego_planner ego_planner_msgs \
--cmake-args -DCMAKE_BUILD_TYPE=Release

# 验证安装
ros2 pkg list | grep ego_planner