入门指南

本节将帮你搭建运行教程所需的环境。我们将创建一个 colcon 工作区，下载最新的 MoveIt 源代码，并从源码进行构建，以确保你获得最新的修复和改进。

根据你的 CPU 速度和可用内存，从源码构建 MoveIt 可能需要 20-30 分钟。如果你的系统性能有限，或者只是想更快上手，请参考我们的 Docker 指南。

安装 ROS 2 和 colcon

MoveIt 2 目前支持多个 ROS 版本，安装其中任意一个即可。我们主要支持在 Ubuntu 22.04 或 24.04 上安装 ROS，其他平台在稍作修改后也可能适用。如果你是初学者，建议在 Ubuntu 24.04 上使用最新的稳定版 ROS（Jazzy），以获得最顺畅的体验。

Rolling Ridley - Rolling 开发版
Jazzy Jalisco - 最新 LTS 版本 - 2024 年 5 月
Humble Hawksbill - 受支持的 LTS 版本 - 2022 年 5 月

在按照 ROS 2 安装教程操作时，很容易遗漏某些步骤。如果你在后续步骤中遇到错误，建议回过头来检查 ROS 2 是否安装正确。用户经常遗漏的一步是 source ROS 2 的安装环境。请务必 source 你所安装的 ROS 版本：

source /opt/ros/jazzy/setup.bash

注意：与 ROS 1 的 setup 脚本不同，ROS 2 的 setup 脚本不会自动切换当前使用的 ROS 版本。这意味着如果你之前 source 了其他版本的 ROS（包括在 .bashrc 中设置的），构建时就会报错。要解决此问题，请修改 .bashrc 中 source 的内容，然后重新打开一个终端。

安装 rosdep 以安装系统依赖：

sudo apt install python3-rosdep

安装 ROS 2 后，请确保更新到最新的包：

sudo rosdep init
rosdep update
sudo apt update
sudo apt dist-upgrade

安装 Colcon（ROS 2 的构建系统）以及 mixin：

sudo apt install python3-colcon-common-extensions
sudo apt install python3-colcon-mixin
colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
colcon mixin update default

安装 vcstool：

sudo apt install python3-vcstool

创建 Colcon 工作区并下载教程 {#create_colcon_workspace}

运行教程需要先创建一个 colcon 工作区：

mkdir -p ~/ws_moveit/src

下载 MoveIt 和教程的源代码

进入你的 Colcon 工作区，拉取 MoveIt 教程源码。其中 <branch> 替换为对应分支，例如 ROS Humble 使用 humble，最新教程版本使用 main：

cd ~/ws_moveit/src
git clone -b <branch> https://github.com/moveit/moveit2_tutorials

接下来下载 MoveIt 其余部分的源代码：

vcs import --recursive < moveit2_tutorials/moveit2_tutorials.repos

导入命令可能会提示你输入 GitHub 凭据。你可以一直按回车跳过（忽略 “Authentication failed” 错误）。

构建 Colcon 工作区

首先，移除之前安装的所有 MoveIt 二进制文件：

sudo apt remove ros-$ROS_DISTRO-moveit*

以下命令会从 Debian 包安装工作区中缺失的所有依赖。此步骤将安装 MoveIt 及其所有依赖：

sudo apt update && rosdep install -r --from-paths . --ignore-src --rosdistro $ROS_DISTRO -y

接下来构建你的 Colcon 工作区：

cd ~/ws_moveit
colcon build --mixin release

此构建可能需要较长时间（20 分钟以上），具体取决于你的 CPU 速度和可用内存（建议 32 GB）。

警告：部分包在构建时需要高达 16 GB 的内存。默认情况下，colcon 会尝试同时构建尽可能多的包。如果你的计算机内存不足，或者构建经常失败，可以在上述 colcon 命令后附加 --executor sequential 来逐个构建，或附加 --parallel-workers <X> 来限制并行构建数量。对于内存更有限的机器，还可以尝试运行 MAKEFLAGS="-j4 -l1" colcon build --executor sequential。

如果一切顺利，你应该会看到 “Summary: X packages finished” 消息（X 可能为 50）。如果遇到问题，请检查你的 ROS 安装是否正确。

设置 Colcon 工作区

Source Colcon 工作区：

source ~/ws_moveit/install/setup.bash

可选：将上述命令添加到你的 .bashrc：

echo 'source ~/ws_moveit/install/setup.bash' >> ~/.bashrc

注意：在 ~/.bashrc 中自动 source setup.bash 并非必需。同时使用多个 Colcon 工作区的高级用户通常会跳过这一步，但为了简单起见，我们建议初学者这样做。

下一步

干得好！

接下来，我们将按照 RViz 快速入门教程，使用 RViz 交互式运动规划插件来可视化机器人。