EGO-swarm集群路径规划环境搭建全攻略：从ROS配置到多机仿真调试-平芜编程栈

1. 为什么集群路径规划要从环境搭建开始啃

搞集群路径规划的人，十个里有八个卡在第一步——环境搭不起来。EGO-swarm 这套东西在学术圈和工程圈都挺火，它解决的是多无人机在复杂三维环境里协同飞行、实时避障、保持队形的问题。听起来很酷对吧？但如果你连编译都过不了，后面那些花哨的集群编队、动态避障、轨迹优化全是空中楼阁。

我自己第一次搭 EGO-swarm 的时候，整整耗了三天。第一天卡在 ROS 版本不匹配，第二天卡在 Eigen 和 PCL 的版本冲突，第三天好不容易编译过了，跑仿真的时候无人机直接原地抽搐。后来我才明白，这个项目的环境依赖链条特别长，从 ROS 的版本选择、C++ 编译器的版本、到各种数学库的精确版本，任何一个环节出问题都会导致连锁反应。

这篇文章适合谁看？如果你正在做多机器人集群、无人机编队、或者任何涉及 EGO-planner 系列算法的项目，而且你用的是 Ubuntu + ROS 这套技术栈，那这篇内容就是给你写的。我会把整个环境搭建过程拆开揉碎，告诉你每一步为什么这么做、哪些地方容易翻车、以及翻车之后怎么救回来。不是那种复制粘贴命令的教程，而是让你真正理解这套环境的内在逻辑。

先说清楚 EGO-swarm 到底是什么。它是浙大 FAST 实验室开源的一套集群规划框架，核心思想是把单机的 EGO-planner 扩展到多机场景。每架无人机独立规划自己的轨迹，但通过一个轻量级的通信机制共享位置信息，从而在局部避障的同时实现全局的集群行为。它的优势在于计算量小、实时性好，单机规划器可以在几毫秒内完成轨迹重规划，非常适合资源受限的机载平台。

但正因为它是科研项目，代码的工程化程度参差不齐，依赖管理基本靠 README 里那几行说明。而 README 往往假设你已经是一个熟练的 ROS 开发者，很多坑它默认你会自己填。这就是为什么很多人搭环境搭到怀疑人生。

2. 系统版本与 ROS 发行版的选择逻辑

2.1 Ubuntu 版本不是随便选的

EGO-swarm 官方推荐的是 Ubuntu 18.04 + ROS Melodic，或者 Ubuntu 20.04 + ROS Noetic。这两个组合有什么区别？核心在于 C++ 标准库的版本和 PCL 的版本。

Ubuntu 18.04 自带的是 GCC 7.5，默认 C++ 标准是 C++14。Ubuntu 20.04 自带 GCC 9.4，默认 C++ 标准是 C++17。EGO-swarm 的代码里用了一些 C++14 的特性，比如std::make_unique，在 C++17 下编译也没问题，但有些第三方库在 C++17 下会有警告甚至报错。

我个人的建议是：如果你是新装机，直接上 Ubuntu 20.04 + ROS Noetic。原因很简单，Noetic 是 ROS 1 的最后一个版本，社区支持到 2025 年，各种依赖包的安装脚本最完善。Melodic 虽然也能用，但很多 PPA 源已经停止维护了，装个 PCL 都要折腾半天。

但如果你实验室的机器全是 18.04，那也别折腾重装系统，Melodic 也能跑通，只是后面装依赖的时候要多留个心眼。

2.2 ROS 安装的两种路径

ROS 的安装方式主要有两种：apt 安装和源码编译。对于 EGO-swarm 来说，必须用 apt 安装，不要尝试源码编译 ROS。原因在于 EGO-swarm 依赖的很多 ROS 包（比如cv_bridge、tf2）在源码编译环境下容易出现 ABI 不兼容的问题，而 apt 安装的二进制包是经过测试的，稳定性有保障。

安装 ROS Noetic 的标准流程：

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' sudo apt install curl curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - sudo apt update sudo apt install ros-noetic-desktop-full

这里有个细节：desktop-full包含了 Gazebo、RViz、以及各种感知和导航的包，体积大概 2GB 左右。如果你磁盘空间紧张，可以只装ros-noetic-desktop，但后面跑仿真的时候还得补装 Gazebo 相关的包，反而更麻烦。所以一步到位装desktop-full是最省事的。

安装完之后，别忘了初始化rosdep：

sudo rosdep init rosdep update

rosdep是 ROS 的依赖管理工具，EGO-swarm 的很多依赖都是通过它来安装的。如果你在国内网络环境下rosdep update失败，可以换用国内镜像源，或者多试几次。这个命令失败是常态，成功了才是意外。

2.3 环境变量的配置陷阱

很多教程会告诉你把source /opt/ros/noetic/setup.bash加到.bashrc里，但没告诉你的是：如果你同时有多个 ROS 工作空间，.bashrc里的 source 顺序会影响环境变量的优先级。

我的做法是在.bashrc里只 source 系统 ROS，工作空间的 source 手动执行。这样每次打开终端，环境是干净的，不会因为某个工作空间的setup.bash覆盖了系统变量而导致奇怪的编译错误。

echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc source ~/.bashrc

验证 ROS 是否安装成功：

roscore

如果能看到started core service [/rosout]，说明 ROS 核心没问题。按Ctrl+C退出。

3. EGO-swarm 的依赖链条与编译顺序

3.1 核心依赖库的版本要求

EGO-swarm 的依赖可以分为三类：ROS 包、数学库、以及可视化工具。我把它们整理成了一张表，方便你对照检查。

依赖库	版本要求	作用	安装方式
Eigen	3.3.7 以上	线性代数运算	apt 或源码
PCL	1.10 以上	点云处理	apt
OpenCV	4.2 以上	图像处理与可视化	apt
Armadillo	9.0 以上	矩阵运算（部分模块）	apt
NLopt	2.6 以上	非线性优化	apt
ROS Noetic	完整版	通信框架	apt

Eigen 的版本特别关键。EGO-planner 的核心优化问题大量使用了 Eigen 的稀疏矩阵求解器，如果版本低于 3.3.7，某些 API 不存在，编译会直接报错。Ubuntu 20.04 的 apt 源里 Eigen 版本是 3.3.7，刚好满足要求。但如果你用的是 18.04，apt 里的 Eigen 是 3.3.4，需要手动升级。

检查 Eigen 版本：

pkg-config --modversion eigen3

如果输出小于 3.3.7，就需要从源码安装：

wget https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.tar.gz tar -xzvf eigen-3.4.0.tar.gz cd eigen-3.4.0 mkdir build && cd build cmake .. sudo make install

源码安装的 Eigen 会覆盖 apt 版本，头文件安装在/usr/local/include/eigen3。这时候需要确保 CMake 能找到新版本，可以在 CMakeLists.txt 里显式指定include_directories(/usr/local/include/eigen3)。

3.2 创建工作空间与源码拉取

EGO-swarm 的代码托管在 GitHub 上，直接 clone 到工作空间的src目录：

mkdir -p ~/ego_swarm_ws/src cd ~/ego_swarm_ws/src git clone https://github.com/ZJU-FAST-Lab/ego-planner-swarm.git

clone 完成之后，不要急着编译。先检查一下代码的分支和依赖声明。EGO-swarm 的主分支是master，但有时候作者会推送一些实验性的分支，这些分支的依赖可能不完整。建议 checkout 到最新的稳定 tag。

查看可用 tag：

cd ego-planner-swarm git tag

选择一个最近的 tag，比如v1.0，然后：

git checkout v1.0

接下来安装rosdep依赖：

cd ~/ego_swarm_ws rosdep install --from-paths src --ignore-src -r -y

这个命令会自动读取每个包的package.xml，安装缺失的依赖。如果一切顺利，你会看到一堆All required rosdeps installed successfully。但现实往往不顺利，常见的报错是某些包找不到，比如nlopt或者armadillo。这时候需要手动安装：

sudo apt install libnlopt-dev libarmadillo-dev

3.3 编译过程中的典型报错与修复

编译 EGO-swarm 用的是catkin_make，但直接跑catkin_make大概率会失败。我总结了几种最常见的报错和对应的修复方法。

报错一：fatal error: Eigen/Dense: No such file or directory

这说明编译器找不到 Eigen 的头文件。即使你装了 Eigen，如果 CMake 没有正确配置 include 路径，也会报这个错。解决方法是在工作空间的CMakeLists.txt里添加：

include_directories(/usr/include/eigen3)

或者更通用的写法：

find_package(Eigen3 REQUIRED) include_directories(${EIGEN3_INCLUDE_DIR})

报错二：undefined reference to 'pcl::search::KdTree'

这是 PCL 链接错误，通常是因为 PCL 的组件没有全部链接。在CMakeLists.txt里，确保find_package(PCL REQUIRED)之后，链接了所有需要的组件：

find_package(PCL REQUIRED COMPONENTS common io search kdtree) include_directories(${PCL_INCLUDE_DIRS}) link_directories(${PCL_LIBRARY_DIRS}) target_link_libraries(your_target ${PCL_LIBRARIES})

报错三：error: 'make_unique' is not a member of 'std'

这是 C++ 标准版本的问题。std::make_unique是 C++14 引入的，如果你的编译器默认用 C++11，就会报这个错。解决方法是在CMakeLists.txt里设置：

set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON)

报错四：内存不足导致编译中断

EGO-swarm 的编译过程非常吃内存，尤其是traj_utils和plan_manage这两个包，单个编译单元可能占用 2GB 以上的内存。如果你的机器内存小于 8GB，建议用catkin_make -j2限制并行编译的线程数，或者增加 swap 空间。

sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

编译成功后，你会看到[100%] Built target的提示。这时候先别高兴太早，编译通过只是第一步，运行起来才是真正的考验。

4. 仿真环境启动与常见运行问题

4.1 启动脚本的调用顺序

EGO-swarm 的仿真启动涉及多个 launch 文件，调用顺序有讲究。正确的顺序是：

启动 Gazebo 仿真环境
启动单机规划器
启动集群通信节点
启动 RViz 可视化

对应的命令：

# 终端1：启动 Gazebo roslaunch ego_planner swarm.launch # 终端2：启动 RViz roslaunch ego_planner rviz.launch

swarm.launch这个文件里其实已经包含了 Gazebo 的启动、无人机的 spawn、以及规划器的初始化。但如果你直接跑这个 launch 文件，可能会遇到 Gazebo 卡在启动界面不动的情况。这通常是因为 Gazebo 在下载模型文件，而国内网络访问 Gazebo 的模型库很慢。

解决方法是在启动前设置 Gazebo 的模型路径为本地路径：

export GAZEBO_MODEL_PATH=~/.gazebo/models:$GAZEBO_MODEL_PATH

或者提前把需要的模型下载到本地。EGO-swarm 用到的模型主要是sun、ground_plane、以及一些简单的障碍物，这些在 Gazebo 的默认模型库里都有。

4.2 无人机原地抽搐的根因分析

仿真跑起来之后，最常见的问题是无人机在原地抖动，或者直接飞不起来。这个问题我遇到过三次，每次的原因都不一样。

原因一：控制频率不匹配

EGO-swarm 的规划器输出的是位置指令，而 Gazebo 里的无人机模型需要速度指令或者姿态指令。如果规划器的输出频率和控制器的工作频率不匹配，就会出现指令堆积或者指令丢失，导致无人机抖动。

检查方法：用rostopic hz /drone_0_planning/pos_cmd查看规划指令的发布频率。正常情况下应该是 100Hz 左右。如果频率忽高忽低，说明规划器的计算时间不稳定，可能是某个优化问题的求解时间过长。

原因二：坐标系变换错误

EGO-swarm 涉及多个坐标系：世界坐标系、无人机机体坐标系、相机坐标系、以及规划器的局部坐标系。如果某个坐标系变换写错了，规划器算出来的轨迹在 Gazebo 里就会完全错位。

排查方法：在 RViz 里添加TF显示，检查各个坐标系之间的变换关系是否正确。特别要注意world到drone_0的变换，以及drone_0到drone_0_camera的变换。

原因三：物理引擎参数不合理

Gazebo 的默认物理引擎参数（比如max_step_size和real_time_update_rate）可能不适合无人机仿真。如果max_step_size太大，物理仿真会不稳定，导致无人机抖动。

调整方法：在 Gazebo 的启动文件里修改物理引擎参数：

<physics type="ode"> <max_step_size>0.001</max_step_size> <real_time_update_rate>1000</real_time_update_rate> </physics>

4.3 集群通信的调试技巧

EGO-swarm 的集群行为依赖于无人机之间的位置共享。如果通信出了问题，每架无人机就会变成"瞎子"，各自为战，集群行为完全消失。

调试通信的第一步是确认每架无人机都在发布自己的位置信息：

rostopic list | grep drone

你应该能看到类似/drone_0_visual_slam/odom、/drone_1_visual_slam/odom这样的话题。然后用rostopic echo检查数据是否正常：

rostopic echo /drone_0_visual_slam/odom/pose/pose/position

如果数据正常，但集群行为还是不对，那可能是通信的订阅关系有问题。EGO-swarm 用一个叫swarm_bridge的节点来转发无人机之间的位置信息。检查这个节点是否正常运行：

rosnode info /swarm_bridge

如果swarm_bridge节点不存在，说明 launch 文件里没有启动它，或者启动失败了。查看 launch 文件里的相关配置，确保swarm_bridge的launch-prefix没有设置成screen或者log，否则你看不到它的输出。

5. 从单机到集群的调试策略

5.1 先用单机验证规划器

在调试集群之前，一定要先确保单机规划器能正常工作。EGO-swarm 的代码库里有一个单机的 launch 文件，通常叫single_drone.launch或者run_in_sim.launch。先用这个文件跑通单机，确认无人机能起飞、能避障、能到达目标点。

单机调试的时候，重点关注这几个话题：

/drone_0_planning/pos_cmd：规划器输出的位置指令
/drone_0_planning/bspline：规划出的 B 样条轨迹
/drone_0_planning/grid_map/occupancy：局部占据栅格地图

如果pos_cmd有输出但无人机不动，检查 Gazebo 里的控制器是否订阅了正确的话题。如果bspline有输出但pos_cmd没有，说明规划器的轨迹优化环节出了问题，可能是优化问题的约束设置太严格，导致求解失败。

5.2 逐步增加无人机数量

单机跑通之后，不要一下子启动五架无人机。先启动两架，确认它们能互相避让，再增加到三架、四架。每增加一架，都要重新检查通信和规划是否正常。

两机调试的时候，把两架无人机放在相邻的位置，给它们设置交叉的飞行目标。观察它们在相遇时是否能互相避让。如果两架无人机直接撞上了，说明通信没有生效，或者避障的膨胀半径设置得太小。

膨胀半径在advanced_param.xml里配置，参数名通常是inflate_radius或者obstacle_inflate_size。默认值一般是 0.3 到 0.5 米，对于室内仿真来说够用了。但如果你的无人机尺寸比较大，或者飞行速度比较快，需要适当增大这个值。

5.3 日志分析与性能瓶颈定位

EGO-swarm 的规划器会在终端输出大量的日志信息，包括每次重规划的时间、优化问题的求解状态、以及轨迹的代价。这些日志是定位性能瓶颈的关键。

如果你发现规划器的计算时间超过了控制周期（通常是 10ms），无人机就会出现明显的延迟和抖动。常见的原因包括：

局部地图的点云数量太多，导致 KdTree 搜索变慢
优化问题的维度太高，求解器迭代次数过多
代码里有不必要的拷贝操作，增加了内存开销

优化方法：在grid_map模块里降低点云的分辨率，或者限制局部地图的范围。在plan_manage模块里调整优化问题的权重参数，减少迭代次数。

我自己的经验是，把局部地图的分辨率从 0.1 米降到 0.2 米，规划时间能减少 30% 左右，而避障效果几乎没有下降。这个取舍在实时性要求高的场景下非常值得。

6. 环境搭建中的几个关键决策点

6.1 用不用鱼香 ROS 一键安装

网上有很多人推荐用鱼香 ROS 的一键安装脚本来装 ROS，确实省事。但我的建议是：如果你只是跑个简单的 demo，用一键安装没问题；但如果你要搭 EGO-swarm 这种依赖复杂的项目，最好还是手动安装。

原因在于一键安装脚本会修改系统的源列表和环境变量，有时候会引入一些不必要的包，或者覆盖掉你之前配置好的环境。EGO-swarm 对环境的纯净度有一定要求，特别是 Eigen 和 PCL 的版本，如果被脚本改乱了，后面排查起来非常痛苦。

6.2 源码编译还是二进制安装

EGO-swarm 本身必须源码编译，这个没得选。但它的依赖库，比如 Eigen、PCL、OpenCV，能用 apt 就用 apt，不要源码编译。源码编译这些库不仅耗时，而且容易和系统里的其他库产生冲突。

唯一可能需要源码编译的是 NLopt，因为 apt 里的版本有时候太旧。但 NLopt 的编译很简单，依赖也少，十分钟就能搞定。

6.3 仿真环境用 Gazebo 还是 AirSim

EGO-swarm 官方支持 Gazebo，也有人在 AirSim 上跑通过。如果你只是做算法验证，Gazebo 足够了，而且配置简单。如果你需要更真实的视觉仿真，比如跑 VINS 或者 ORB-SLAM，那可以考虑 AirSim。

但 AirSim 的配置复杂度比 Gazebo 高一个数量级，而且和 ROS 的接口不如 Gazebo 成熟。我建议先用 Gazebo 把算法跑通，等算法稳定了再考虑换仿真平台。

7. 一些让我少走弯路的实操习惯

搭环境这件事，最怕的就是"一次成功"。因为一次成功意味着你没有踩过坑，下次换个机器或者换个版本，你还是不知道怎么处理。我现在的习惯是：每搭一次环境，就把所有的命令和报错记录下来，形成一个自己的"环境搭建日志"。

这个日志里不仅记录成功的命令，更重要的是记录失败的尝试和失败的原因。比如"尝试用 apt 安装 Eigen 3.4，失败，因为 Ubuntu 20.04 的源里只有 3.3.7"，这种信息比成功的命令更有价值。

另外，我强烈建议用 Docker 来管理 EGO-swarm 的环境。虽然 Docker 里的 GUI 显示需要额外配置，但一旦配好，环境就是可复现的。你可以在任何机器上拉取镜像，几分钟就能跑起来，不用再经历一遍编译的痛苦。

Docker 的配置要点是：把 X11 的 socket 挂载到容器里，设置DISPLAY环境变量，并且确保容器里的用户有权限访问 X11。具体的 Dockerfile 和运行脚本，我下次再单独写一篇。

还有一个习惯是：在编译之前，先用catkin_make -j1单线程编译一次。虽然慢，但能确保每个编译单元的报错信息都能完整显示，不会因为并行编译导致报错信息交错在一起。等单线程编译通过了，再用-j4或者-j8加速。

最后说一个关于调试的心态问题。EGO-swarm 的环境搭建确实麻烦，但这个过程本身就是在帮你理解这套系统的架构。每解决一个依赖问题，你就对这套系统的模块划分多了一分了解。等你把环境搭通了，后面调算法的时候，你会发现自己对代码的理解比那些直接用别人配好的环境的人深得多。

这个系列后面还会写规划器的参数调优、集群编队的实现细节、以及如何把仿真里跑通的算法部署到真机上。环境搭建只是第一关，但这一关过了，后面的路就好走多了。

EGO-swarm集群路径规划环境搭建全攻略：从ROS配置到多机仿真调试