1. MoveIt与ROS2环境搭建：从零开始，稳扎稳打
大家好，我是你们的机器人工程师老K。今天咱们正式开干——搭建MoveIt2的开发环境。
说实话，我见过太多同学卡在这一步。不是装不上，就是版本冲突，最后心态崩了。我自己也踩过不少坑，所以这一章我会把每个细节掰开揉碎了讲。你跟着我走，保证顺顺利利。
1.1 为什么选Ubuntu 22.04 + ROS2 Humble？
你可能要问：为什么非得是Ubuntu 22.04？我用20.04行不行？
嗯，这里要注意。MoveIt2官方对ROS2 Humble的支持是最完善的，而Humble又推荐在Ubuntu 22.04上运行。我去年帮一个客户迁移项目，他硬要在20.04上跑Humble，结果一堆依赖冲突，折腾了两天。所以，听我一句劝，别跟自己过不去。
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 LTS | 长期支持，稳定可靠 |
| ROS2 | Humble Hawksbill | 2024年5月前都受支持 |
| MoveIt2 | main分支（源码编译） | 最新特性，灵活可控 |
1.2 安装Ubuntu 22.04
这一步我就不啰嗦了，网上教程一大堆。我只提醒几个关键点：
- 磁盘分区： 建议给根目录至少50GB，因为后面要装的东西不少。
- 用户名： 别用中文，也别带空格。我习惯用
robot，简单好记。 - 软件更新： 装完后先跑一遍
sudo apt update && sudo apt upgrade -y，把系统更新到最新。
vim和git装上。后面你会经常用到它们。
1.3 安装ROS2 Humble
ROS2的安装其实很标准，但有几个坑我帮你提前填了。
首先，设置语言环境。这一步很多人会忘，但少了它后面编译会报错。
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8然后添加ROS2的软件源。我建议用中科大的镜像，速度快很多。
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null接下来安装ROS2 Humble桌面版。这个包包含了常用的工具和库。
sudo apt update
sudo apt install ros-humble-desktop -y装完之后，别忘了配置环境变量。我习惯把它加到 .bashrc 里，这样每次打开终端自动生效。
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc.bashrc换成.zshrc。我曾经帮一个同事排查了半天，结果发现他用的shell不一样。
验证一下安装是否成功：
ros2 run demo_nodes_cpp talker如果看到类似 [INFO] [xxx] [talker]: Publishing: 'Hello World: xxx' 的输出，恭喜你，ROS2装好了。
1.4 安装MoveIt2依赖
MoveIt2的依赖比较多，但别怕，一条命令搞定。
sudo apt install ros-humble-moveit -y等等，这里有个坑。这个命令安装的是预编译的MoveIt2，但我们后面要源码编译，所以还需要一些额外的开发工具。
sudo apt install python3-colcon-common-extensions python3-vcstool python3-rosdep -ycolcon是ROS2的编译工具，vcs用来管理多个代码仓库，rosdep负责安装依赖。这三个工具后面会频繁用到。
1.5 创建工作空间与源码编译
我个人习惯把工作空间放在 ~/ros2_ws 下。名字你可以自己定，但路径里别带中文。
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws接下来，我们要把MoveIt2的源码拉下来。这里我建议用官方提供的 moveit2.repos 文件，它会自动帮你把相关的仓库都下载好。
cd ~/ros2_ws
wget https://raw.githubusercontent.com/ros-planning/moveit2/main/moveit2.repos
vcs import src < moveit2.repos这一步会下载十几个仓库，包括moveit2核心、moveit2_tutorials、moveit_resources等。网速慢的话，可以去喝杯咖啡。
下载完成后，用 rosdep 安装系统依赖：
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -r -y这里要注意，rosdep init 只需要执行一次。如果提示 already initialized，直接跳过就行。
最后，开始编译。这一步最耗时，也最容易出问题。
cd ~/ros2_ws
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release --parallel-workers 4--parallel-workers 4 表示用4个线程并行编译。你可以根据自己电脑的CPU核心数调整，一般设为核心数的一半比较稳妥。
Could not find a package configuration file，多半是某个依赖没装全。别慌，看看报错信息里缺的是哪个包，然后用sudo apt install ros-humble-xxx装上就行。
编译成功后，你会看到类似这样的输出：
Summary: 42 packages finished [12min 35s]
1 package had stderr output: moveit_ros_planning看到 42 packages finished 了吗？这说明MoveIt2已经编译成功了。那个 stderr output 一般是警告信息，不影响使用。
1.6 环境验证：跑一个Demo
光说不练假把式。我们来跑一个MoveIt2自带的Demo，验证环境是否真的没问题。
首先，配置环境变量：
echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc然后启动Panda机械臂的Demo：
ros2 launch moveit2_tutorials demo.launch.py如果一切顺利，你会看到Rviz2界面弹出来，中间有一个Franka Emika Panda机械臂。你可以用鼠标拖拽它，或者用MotionPlanning面板规划运动。
- Rviz2能正常启动，没有报错
- 机械臂模型显示完整
- 可以拖拽并规划运动
我第一次跑通这个Demo时，心里那个激动啊。但后来发现，这只是万里长征第一步。后面还有更多挑战等着我们。
1.7 本章知识体系
为了让你对整个流程有个直观的认识，我画了一张流程图。它展示了从系统安装到Demo验证的完整链路。
这张图把整个流程串起来了。你可以看到，每一步都依赖上一步。所以，千万别跳步，也别图省事。我见过有人跳过依赖安装直接编译，结果折腾了一整天。
1.8 常见问题与解决
最后，我整理了几个我遇到过的高频问题，你如果碰到了可以直接查。
| 问题 | 原因 | 解决方法 |
|---|---|---|
colcon build 报错 ModuleNotFoundError: No module named 'catkin_pkg' |
缺少Python包 | pip3 install catkin_pkg |
| rosdep update 超时 | 网络问题 | 换用国内镜像，或设置代理 |
| Rviz2启动后没有机械臂模型 | 环境变量未配置 | 检查 source ~/ros2_ws/install/setup.bash 是否执行 |
| 编译时内存不足 | 并行线程太多 | 减少 --parallel-workers 数值，或增加swap |
好了，环境搭建就到这里。你跟着走一遍，应该不会有什么大问题。如果卡住了，别硬撑，回头看看是不是哪一步漏了。
记住，环境搭好了，后面才能跑得顺。磨刀不误砍柴工嘛。