企业官网建设流程全解析

从ROS1切到ROS2，再顺手把MoveIt换成MoveIt2，这个过程中我花掉的时间，比预期多了差不多一倍。最典型的一个场景就是笛卡尔轨迹规划：明明在MoveIt1里写得好好的MoveGroupInterface接口，到了ROS2不光头文件路径变了，连消息类型都从geometry_msgs::Pose变成了geometry_msgs::msg::Pose，编译直接给你一大堆红色报错。后来我索性换了个思路，用Panda机械臂把整套流程从零完完整整过了一遍，环境搭建、笛卡尔路径规划、添加障碍物避障、轨迹执行，每一步都跑通并留下了代码。这篇文章就是那条已经趟平的路，目标很直接：让你在Ubuntu 22.04 + ROS2 Humble环境下，用MoveIt2驱动Panda机械臂按笛卡尔waypoint运动，同时学会正确地把障碍物“塞”进规划场景里，做出一条真正能避开障碍的轨迹。

1. 为什么是Panda + MoveIt2：笛卡尔避障选型时的几个现实问题

1.1 MoveIt2和MoveIt1的差距不在名字，而在底层

很多从ROS1迁移过来的人第一反应是“MoveIt2就是换个ROS2接口”，实际上远不止如此。MoveIt2在Humble中的版本已经是2.5.x，接口全面转向ROS2风格：节点用rclcpp::Node::SharedPtr传递，消息类型全部带上msg命名空间，参数系统从ROS1的param server换成了ROS2的参数接口，Action从actionlib换成了rclcpp_action。这些变化让老的MoveIt1代码基本无法直接编译。

但MoveIt2的长期支持状态其实比很多人想象的好。Humble的ros-humble-moveit二进制包已经非常成熟，官方维护的教程也都在Humble上跑通了。对于做机械臂应用开发的工程师来说，现在入ROS2 + MoveIt2是合适的时间点，没有必要再守着Foxy或者老MoveIt1不放。

1.2 为什么拿Panda做示例

Panda（Franka Emika Panda）在MoveIt社区里几乎是“教科书级”的存在。原因有三：第一，它是7自由度机械臂，冗余自由度多，避障时有更多关节空间可以选择，比6自由度机械臂更容易规划出绕行路径；第二，MoveIt资源库直接维护了它的全套配置，URDF、SRDF、控制器配置、demo launch文件都齐全，装完就能跑，不用自己写模型文件；第三，社区里所有教程、截图、示例代码几乎都用Panda，你遇到问题时搜到的资料最多。

更重要的是，Panda的配置结构很标准，你照着它的格式换成自己的URDF，基本只需要改模型路径和规划组名，其他逻辑完全可以复用。所以拿Panda做实战并不是“只会Panda”，而是“通过Panda学会通用流程”。

1.3 笛卡尔避障为什么比关节空间规划更麻烦

机械臂最常见的规划方式是关节空间规划，OMPL里的RRT、PRM这些算法都属于这一类。它只要求给定起点和终点的关节位置，中间过程由采样器在关节空间里随机搜索，只要找到一条无碰撞路径就算成功。好处是搜索空间大、容易找到解，坏处是末端执行器走的轨迹不可控，可能是一条奇怪的弧线。

笛卡尔路径则不一样。它要求末端执行器沿着一条直线或者圆弧“走位”，这意味着路径上每一个中间点都必须做逆运动学求解，把末端位姿转换成关节位置，然后再做碰撞检测。任何一个中间点不可达、或者该点处机械臂与障碍物碰撞，整条路径就会在那一截断掉，返回的完成比例fraction就会下降。这就是笛卡尔避障的本质难点：路径被严格约束在任务空间，规划器没有太多“绕路”的自由，只能靠你提供合理的中间waypoint或者调整障碍物配置。

2. 环境搭建与验证：从一键安装到Demo跑通的完整链路

2.1 最小安装清单

环境我推荐Ubuntu 22.04 + ROS2 Humble，这也是目前MoveIt2支持最稳定的组合。安装MoveIt2本身不复杂，直接装二进制包：

sudo apt install ros-humble-moveit sudo apt install ros-humble-moveit-resources-panda-moveit-config

第二条装的是Panda的MoveIt配置包，里面包含了URDF、SRDF、launch文件和控制器配置。如果你只是想先跑官方的教程Demo，这两个包就够了。

网上流行的一键安装脚本能帮你把ROS2和MoveIt2一起装好，省去折腾环境的痛苦，但我的建议是装完以后手动敲一遍apt list --installed | grep moveit，确认一下版本号，免得后面排查问题时分不清是版本不匹配还是配置错误。

2.2 启动Demo后应该检查什么

装好后，开两个终端分别执行：

# 终端1 source /opt/ros/humble/setup.bash ros2 launch moveit_resources_panda_moveit_config demo.launch.py # 终端2 source /opt/ros/humble/setup.bash ros2 node list

ros2 node list至少能看到/move_group这个节点。move_group是MoveIt2的核心节点，它负责加载规划器、维护规划场景、处理规划请求和轨迹执行。如果这个节点没起来，后面所有代码都白搭。

在RViz2界面里，把机器人模型拖动一下，再点Plan，应该能规划出一条关节空间轨迹并执行，机械臂模型会跟着动起来。这一步确认了最基本的“规划-执行”链路没问题，再往下才谈得上笛卡尔路径和避障。

如果你之前用过MoveIt1，建议在启动后额外执行：

ros2 param get /move_group planning_plugin

正常会返回类似ompl_interface/OMPLPlanner的值。确认用的是OMPL规划器，后面对照参数调整时才不会蒙圈。

2.3 为什么不建议一上来就编译源码

很多教程喜欢让你从源码编译MoveIt2，说是为了调试方便。我的观点是：除非你要改MoveIt2源码本身，否则直接用二进制包能省下大量时间。源码编译要拉一堆依赖、处理版本冲突、编译半小时起步，而二进制包已经打过包、做过测试，稳定性远超自己编的版本。等你把应用跑通了，再决定要不要源码编译也不迟。

2.4 关于Gazebo仿真的一些提醒

MoveIt2自带的demo launch不上Gazebo，机械臂的“执行”走的是FakeController，轨迹会直接体现在RViz2的模型上，没有物理仿真。如果你要做Gazebo仿真，需要额外装：

sudo apt install ros-humble-gazebo-ros ros-humble-gazebo-ros2-control

然后在launch里加载Gazebo的空世界、把Panda的URDF转成gazebo能读的格式，并配置ros2_control的hardware interface。这一步涉及的内容比MoveIt2本身还多，建议先把RViz2这条链路跑熟，再考虑Gazebo。

3. 笛卡尔路径在MoveIt2里的实现逻辑：waypoint、eef_step与碰撞检查

3.1 三个入口的取舍

在我实际调研MoveIt2笛卡尔路径时，发现社区里能用的入口其实有三个，很多人搞不清区别：

我平时做项目优先用C++接口。原因是computeCartesianPath这个方法从MoveIt1到MoveIt2变化最小，API也很稳定，网上资料多，出了问题好查。moveit_py在Humble里虽然能跑，但版本之间API差异大，尤其是笛卡尔路径相关的方法，不同版本可能完全不同。如果你用Python，要有随时查源码的准备。

3.2 computeCartesianPath的参数到底是什么意思

computeCartesianPath的典型调用是：

double fraction = move_group.computeCartesianPath( waypoints, // std::vector<geometry_msgs::msg::Pose> eef_step, // 末端步长，单位米 jump_threshold,// 关节跳跃阈值 trajectory, // 输出，moveit_msgs::msg::RobotTrajectory avoid_collisions // 是否做碰撞检测 );

waypoints是一串末端位姿。相邻两个位姿之间，MoveIt2的平移部分做线性插值，旋转部分做球面插值（SLERP），这样能保证姿态过渡平滑。

eef_step是每步采样时末端走过的距离，单位是米。0.01意味着每采样一个路径点，末端移动1厘米。这个值越小，路径越精细，但计算量成倍增加，规划时间变长。我做Panda这类桌面机械臂，常用0.005到0.01之间，足够平滑也不至于卡顿。

jump_threshold是允许的“关节跳跃”阈值，单位是弧度/秒？实际它不是直接的速度，而是相邻采样点之间关节位置的突变量限制。0表示不做限制，允许关节瞬时改变位置。大多数场景设0就行，因为算法本身会做后处理优化。

avoid_collisions设为true时，规划器会在每个采样点调用FCL（柔性碰撞库）做碰撞检测。这个参数就是避障的关键开关。

3.3 fraction的深层含义：规划失败还是路径被截断

computeCartesianPath的返回值fraction表示路径的完成比例，取值范围0到1。很多人一看到fraction小于1就以为规划失败，其实不准确。fraction为0.85的真实含义是：规划器成功生成了前85%的路径点，从第85%的位置开始，某个waypoint的IK解不出来，或者发生了碰撞，所以后面的路径被截断了。

这里有个实际判断技巧：如果fraction在0.9以上，可以直接执行，剩下的由控制器微调；如果fraction在0.5左右，说明路径大概率被某个障碍物明显拦截，这时候要先检查障碍物位置和路径之间的关系，再考虑加绕行点。我在第5章的代码里会演示这个判断逻辑。

4. 把障碍物告诉规划器：PlanningScene Interface的正确用法

4.1 你要修改的是move_group手里的那张“地图”

MoveIt2里，所有和几何环境相关的信息都存在于规划场景PlanningScene中。它包含机器人模型、周围障碍物的碰撞几何、允许碰撞矩阵等信息。move_group节点维护这份规划场景，每次规划请求发出后，规划器在当前的规划场景上做碰撞检测。因此避障的第一步，不是修改规划器参数，而是把障碍物正确写进规划场景。

向规划场景添加障碍物的标准接口是PlanningSceneInterface。它会把CollisionObject消息发给move_group节点，move_group再更新内部的PlanningScene。

4.2 CollisionObject消息的几个关键字段

一个完整的moveit_msgs::msg::CollisionObject消息，最常用的字段是：

• id：障碍物名字，必须唯一，后续删除或修改时靠id定位。
• header.frame_id：障碍物所在的坐标系，比如panda_link0或world。
• primitives：基础几何体列表，支持BOX、SPHERE、CYLINDER等。
• primitive_poses：每个几何体的位姿，相对于frame_id。
• operation：ADD、REMOVE、APPEND等操作类型。

有个容易踩的坑是header.frame_id的选择。我建议始终用move_group.getPoseReferenceFrame()获取当前规划参考坐标系，而不是凭感觉写world或者base_link。Panda的配置里，base_link与panda_link0往往重合，但如果你的机械臂模型自定义过，写错坐标系会导致障碍物出现在完全错误的位置，RViz2里看起来就是“根本不在机器人旁边”。

obstacle.header.frame_id = move_group.getPoseReferenceFrame();

4.3 ADD和ATTACH的区别

PlanningSceneInterface除了applyCollisionObject，还有attachCollisionObject和detachCollisionObject。这两组操作的含义不同：

• applyCollisionObject（ADD）：把障碍物放在场景中的固定位置，比如桌面上的箱子、墙面的围栏。它不会跟随机械臂运动。
• attachCollisionObject：把物体附着到某个机械臂连杆上，典型场景是抓取。物体附着上去后，会随末端执行器一起运动，碰撞检测也会把物体与机械臂本体的碰撞关系排除。

在第5章的示例里，我们只需要固定障碍物，所以用applyCollisionObject就够了。但你要知道记忆里还有ATTACH这条路，做抓取任务时会用到。

还有一个实操细节：applyCollisionObject是异步的，add之后立刻发起规划请求，move_group可能还没来得及更新场景，导致碰撞检查没有生效。稳妥做法是add之后等几百毫秒：

rclcpp::sleep_for(std::chrono::milliseconds(500));

等规划场景刷新完再规划，后面代码里我会保留这个sleep，别删。

5. 代码实战：Panda绕过柱状障碍完成直线轨迹的完整实现

5.1 新建一个功能包

先在工作空间里建包：

mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src ros2 pkg create panda_cartesian_demo --build-type ament_cmake --dependencies rclcpp moveit_ros_planning_interface geometry_msgs moveit_msgs shape_msgs

package.xml里的<depend>标签会自动加上这些依赖。然后写CMakeLists.txt，把可执行文件加进去：

add_executable(cartesian_avoidance src/cartesian_avoidance.cpp) ament_target_dependencies(cartesian_avoidance rclcpp moveit_ros_planning_interface geometry_msgs moveit_msgs shape_msgs ) install(TARGETS cartesian_avoidance DESTINATION lib/${PROJECT_NAME} )

5.2 核心代码：笛卡尔路径绕障

下面这段代码就是整个文章的核心。逻辑分为三步：第一步添加一个柱状障碍物，第二步构造一条会撞到它的直线路径，第三步通过waypoint绕行方案绕过障碍物并执行。

#include <rclcpp/rclcpp.hpp> #include <moveit/move_group_interface/move_group_interface.h> #include <moveit/planning_scene_interface/planning_scene_interface.h> #include <geometry_msgs/msg/pose.hpp> #include <moveit_msgs/msg/collision_object.hpp> #include <shape_msgs/msg/solid_primitive.hpp> #include <thread> #include <chrono> int main(int argc, char** argv) { rclcpp::init(argc, argv); auto node = std::make_shared<rclcpp::Node>("panda_cartesian_avoidance"); // move_group接口内部依赖action通信，需要spin executor auto executor = std::make_shared<rclcpp::executors::SingleThreadedExecutor>(); executor->add_node(node); std::thread([&executor]() { executor->spin(); }).detach(); using moveit::planning_interface::MoveGroupInterface; using moveit::planning_interface::PlanningSceneInterface; MoveGroupInterface move_group(node, "panda_arm"); PlanningSceneInterface planning_scene_interface; // ========== 1. 添加柱状障碍物 ========== moveit_msgs::msg::CollisionObject pillar; pillar.id = "central_pillar"; pillar.header.frame_id = move_group.getPoseReferenceFrame(); shape_msgs::msg::SolidPrimitive box; box.type = shape_msgs::msg::SolidPrimitive::BOX; box.dimensions.push_back(0.1); // x box.dimensions.push_back(0.1); // y box.dimensions.push_back(0.35); // z geometry_msgs::msg::Pose box_pose; box_pose.position.x = 0.45; box_pose.position.y = 0.0; box_pose.position.z = 0.175; // 半高，让柱体从桌面向上长 pillar.primitives.push_back(box); pillar.primitive_poses.push_back(box_pose); pillar.operation = moveit_msgs::msg::CollisionObject::ADD; planning_scene_interface.applyCollisionObject(pillar); // 等待move_group刷新规划场景 rclcpp::sleep_for(std::chrono::milliseconds(500)); // ========== 2. 构造笛卡尔路径 ========== std::vector<geometry_msgs::msg::Pose> waypoints; auto current_pose = move_group.getCurrentPose().pose; // 起点：当前姿态 waypoints.push_back(current_pose); // 目标点：移动到柱子正上方的前方区域 geometry_msgs::msg::Pose goal_pose = current_pose; goal_pose.position.x = 0.60; goal_pose.position.y = 0.0; goal_pose.position.z = 0.45; // 如果直接用goal_pose做直线规划，路径会从柱体中间穿过， // avoid_collisions=true时fraction会大幅降低。 // 绕行方案：先抬升到柱体上方，再横向移动，最后下降。 geometry_msgs::msg::Pose wp1 = current_pose; wp1.position.z = 0.65; geometry_msgs::msg::Pose wp2 = wp1; wp2.position.x = goal_pose.position.x; geometry_msgs::msg::Pose wp3 = goal_pose; waypoints.push_back(wp1); waypoints.push_back(wp2); waypoints.push_back(wp3); // ========== 3. 规划并执行 ========== moveit_msgs::msg::RobotTrajectory trajectory; double fraction = move_group.computeCartesianPath( waypoints, // 路径点 0.01, // eef_step 末端步长1cm 0.0, // jump_threshold 不做关节跳跃限制 trajectory, // 输出的轨迹 true // 开启碰撞检测 ); RCLCPP_INFO(node->get_logger(), "Cartesian path fraction: %.2f", fraction); if (fraction < 0.9) { RCLCPP_WARN(node->get_logger(), "路径完成度太低，请检查障碍物位置与waypoint是否合理"); rclcpp::shutdown(); return 1; } moveit::planning_interface::MoveGroupInterface::Plan plan; plan.trajectory_ = trajectory; auto result = move_group.execute(plan); if (result == moveit::core::MoveItErrorCode::SUCCESS) { RCLCPP_INFO(node->get_logger(), "轨迹执行成功"); } else { RCLCPP_ERROR(node->get_logger(), "轨迹执行失败，错误码: %d", result.val); } rclcpp::shutdown(); return 0; }

5.3 代码背后的路径思路

这段代码里最关键的设计，是waypoints序列从“一条直线”变成“三段折线”。从起点先竖直抬升到0.65m，这高过了柱体顶面（0.175 + 0.175 = 0.35m），所以水平方向上即使从柱体上方飞过也不会碰撞；然后再水平移动到目标x位置；最后俯冲到目标点0.45m高度。

这就是笛卡尔避障的核心技巧：不要指望MoveIt2自动绕开障碍物，而是把你对环境的理解转化成waypoint。规划器负责的只是“在已给路径点之间做无碰撞的笛卡尔插值”。

5.4 编译与运行

cd ~/ros2_ws colcon build --packages-select panda_cartesian_demo source install/setup.bash # 终端1：启动Panda demo source /opt/ros/humble/setup.bash ros2 launch moveit_resources_panda_moveit_config demo.launch.py # 终端2：运行避障程序 source ~/ros2_ws/install/setup.bash source /opt/ros/humble/setup.bash ros2 run panda_cartesian_demo cartesian_avoidance

如果一切正常，RViz2里会先出现一个灰色柱体，然后机械臂末端先升起来，水平移过柱子，再落下来，整个过程流畅无碰撞。

6. 实测中我踩过的四个坑位与排查链路

6.1 坑一：fraction莫名变低，机械臂走了一半就停

这是最常遇到的问题。你可能发现fraction只有0.5左右，机械臂执行时只走了一小段就停止。

我的排查链路是：

1. 先打印fraction，确认低于阈值。
2. 在RViz2里打开MotionPlanning插件的“Planned Path”显示，看看规划出的轨迹断在什么位置。
3. 如果有显示，把avoid_collisions参数临时改成false，重新规划一次。如果改成false之后fraction变成1.0，说明路径本身没问题，问题一定出在碰撞环节。
4. 检查障碍物的位置和机器人当前位置，确认路径确实被障碍物截断了。
5. 最直接的解决方式是调整waypoints，加绕行点，不要走直线。

很多人在第4步就放弃了，只顾着把障碍物位置挪开，其实一旦你确认了“障碍物挡路”，正确思路不是去除障碍物，而是调整路径让它绕开。

6.2 坑二：RViz2里看不到障碍物

代码明明applyCollisionObject了，RViz2里就是不显示，规划也没有避障效果。

排查链路：

1. 确认frame_id正确。如果panda_link0和world的位置关系和我们想的不一样，障碍物会出现在很远的地方，规划自然不受影响。
2. 在终端订阅规划场景：

ros2 topic echo /planning_scene

如果消息里能看到central_pillar的几何数据和ADD操作，说明move_group已经收到了，问题多半在RViz2显示设置。 3. 检查RViz2的MotionPlanning插件面板，确认“Scene Geometry”和“Show Robot Visual”都勾选了。 4. 确认添加障碍物后确实等了足够时间。不等500毫秒就立刻规划，可能move_group还没来得及把新场景同步到可视化端。

6.3 坑三：execute之后机械臂毫无反应

这种情况通常不是MoveIt2规划出了问题，而是执行端没有做好准备。

先检查：

ros2 topic info /panda_arm_controller/joint_trajectory

正常执行Panda的demo.launch.py后，这个topic应该有发布者和订阅者。如果在ros2 topic info里只见Publisher、不见Subscription，说明没有东西在执行轨迹。MoveIt2的demo默认用FakeController，它只会把轨迹广播出来，本身不驱动真实电机——RViz2里的机械臂模型之所以会动，是RViz2显示端订阅了这个topic然后更新模型位姿。

如果确实没有订阅者，最常见原因是你没有把demo.launch.py完整启动起来，只单独跑了move_group节点。确认启动命令用的是ros2 launch moveit_resources_panda_moveit_config demo.launch.py，而不是手动启动单个节点。

6.4 坑四：时间戳问题导致规划失败

在笛卡尔规划里，即使你把header.frame_id写对了，如果Pose的header.stamp没有设置，或者use_sim_time参数不一致，move_group可能会认为坐标信息过期，拒绝规划。

Panda的demo.launch.py默认use_sim_time:=false。如果你在Gazebo环境里跑，记得保持所有节点的use_sim_time一致。在代码里构造Pose时，我习惯不显式设stamp，让tf2使用最新变换；如果确实需要指定，用rclcpp::Time(0)表示“最新可用”，避免指定一个过去时间导致TF等待报错。

下面是四个坑的速查表：

7. 从固定障碍到动态避障：进阶方向与真实系统迁移

7.1 动态避障的本质：从离线场景到实时更新

第5章的代码针对的是静态障碍物：场景固定，规划一次就行。但实际机器人应用中，更多场景是障碍物会动，比如人走过来、传送带上工件在移动。这时候避障策略要从“规划一次”变成“持续重规划”。

机械臂动态避障的主流方案是“感知-地图-规划”闭环：用RGB-D相机或者激光雷达采集点云，通过八叉树地图（Octomap）把点云更新到规划场景中，MoveIt2的PlanningSceneMonitor订阅这张地图，每一帧规划时都基于最新场景做碰撞检测。八叉树的好处是内存可控、更新增量高效，移动机器人导航里也常用它做环境表示。

这里要顺便说清楚一点：机械臂的笛卡尔避障和移动机器人的DWA动态窗口法不是一回事。DWA是在速度空间里采样候选轨迹，然后选一条避开障碍物的局部路径，核心是“速度采样+代价评估”；机械臂笛卡尔避障则是在任务空间或者关节空间里搜索满足无碰撞约束的路径，核心是“逆运动学+碰撞检测”。两者目标相同，但几何空间和算法思路完全不同。如果你要从移动机器人避障转过来做机械臂避障，别把DWA的思路硬套。

7.2 从MoveIt2的demo到Gazebo真机仿真

很多读者会问：“你的代码在RViz2里跑通了，放到Gazebo里能用吗？”答案是能，但要额外配置。

MoveIt2 demo默认的FakeController只是把轨迹发布出来，不产生物理反馈。Gazebo里要驱动Panda，需要：

1. 把Panda的URDF/Xacro加载到Gazebo世界。
2. 在URDF里加ros2_control描述，定义joint_state_broadcaster和joint_trajectory_controller。
3. 用gazebo_ros2_control插件作为hardware interface，让MoveIt2的轨迹真正作用于Gazebo里的关节。

运行方式也从原来单纯的MoveIt demo，变成“先启动Gazebo + controller manager，再启动MoveIt2，让MoveIt2连接controller manager执行轨迹”。这中间时间同步问题特别容易出现，记得控制端和MoveIt2的use_sim_time要保持一致，Gazebo里一般设true，RViz2里也要同步开启。

7.3 我的一点实际经验

如果你也是刚从ROS1的MoveIt1迁过来，我建议别急着在公司机器人或者复杂模型上折腾，先在Panda这套官方配置上把“添加障碍物 -> 笛卡尔规划 -> 执行”这条链路彻底跑通。这条链路一打通，你手里就有了一个完全可控的实验环境，后面换URDF、改规划组、接深度相机，都是在同一个框架里加东西而已。

还有个小技巧：调试笛卡尔路径时，不要每次都用真实机器人试错，学会先用RViz2的虚拟模式把fraction和路径形状看清楚。虚拟环境里确认没问题了，再上Gazebo或真机，能省下大量现场排查时间。我在实际项目里踩过几次“现场执行卡住”的坑，事后复盘基本都是虚拟环境里没把障碍物位置调准，这个习惯帮我省了不少返工成本。