鱼香ROS一键安装：从ROS2环境搭建到Gazebo与micro-ROS实战

直接进入正题。如果你在搜索引擎里输入过“ros2安装”这四个字那你大概率已经见过不少二十分钟教你把ROS2跑起来的教程也大概率经历过装到一半软件源报错、依赖冲突、ros-core装完发现缺了一堆包、source完环境变量下次开机又失效这种事。我当年第一次装ROS2的时候光是在虚拟机里处理libgl1-mesa-dev和python3-colcon-common-extensions的依赖问题就花了一整个晚上最后还是靠同事扔给我一个现成的Docker镜像才进了门。后来接触到鱼香ROS一键安装脚本才明白一个道理ROS2本身不复杂复杂的是装ROS2的这个环境。这套一键脚本做的事情并不神奇但它把“换源、补依赖、选版本、配环境变量、装仿真工具链”这些琐碎步骤整合成了几个选择题让新手能把精力从“折腾安装”挪到“跑通Demo”上去。这篇文章就围绕三个核心话题展开鱼香ROS一键安装怎么用、装完ROS2后怎么把Gazebo仿真跑起来、以及怎么通过micro-ROS让MCU和ROS2真正对话。不管你是刚从Ubuntu接触ROS2的学生还是工作中需要快速验证机器人算法的工程师这套流程都能直接抄作业。主流程开始先从“为什么市面上大家都在喊一键安装”说起。1. 传统安装ROS2的痛点为什么大家都在喊“一键安装”1.1 一场由软件源和依赖引发的持久战ROS2的安装路径官方其实写得非常清楚。以Ubuntu 22.04 ROS2 Humble为例标准步骤是sudo apt update sudo apt install curl gnupg lsb-release 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 $(source /etc/os-release echo $UBUNTU_CODENAME) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null sudo apt update sudo apt upgrade sudo apt install ros-humble-desktop看着没有几步但实际跑下来你会发现几个现实问题。第一packages.ros.org这个官方软件源在部分网络环境下响应速度不稳定apt update刷到一半超时是常有的事。第二ros-humble-desktop这个包会拉进来上百个依赖其中和Python相关的、和图形界面相关的、和编译工具链相关的包缺一不可任何一个被本地已有的旧版本顶住apt就会抛出一串“无法修正错误因为您要求某些软件包保持现状”这样的提示新手看到基本就懵了。第三装完Redis、Nginx之类的常见软件后再装ROS2经常遇到mesa或者ffmpeg的版本冲突这时候你不会想自己去编译一遍底层库的。我当时在虚拟机上遇到的问题更具体装完ros-humble-desktop之后启动rviz2直接段错误排查半天才发现是VMware的3D加速和OpenGL渲染库不兼容。这种问题官方文档是永远教不了你的因为它和你的具体环境强相关。1.2 环境变量和版本选择坑在看不见的地方就算你顺利装完了ROS2本体等待你的还有环境变量配置。不知道有多少新手卡在这一句上echo source /opt/ros/humble/setup.bash ~/.bashrc这句话逻辑很简单但实际遇到的坑版本很多。比如有人用的是zsh往~/.bashrc里写就没意义比如有人在/opt/ros下同时装了foxy和humble两个版本写死一个版本后另一个就废了再比如你明明source了工作空间的install/setup.bash但忘记让它顺序在ROS基础环境之后导致自定义消息找不到类型。另一个公认的坑是ROS2版本和Ubuntu版本的对应关系。Ubuntu 20.04装ROS2 Foxy、Ubuntu 22.04装ROS2 Humble、Ubuntu 24.04装ROS2 Jazzy这是官方测试过的组合。但网上大量旧教程还停留在Ubuntu 18.04 Melodic的写法你在Ubuntu 22.04上照着敲大概率直接抱错。做一键脚本的开发者们把这些对应关系、换源逻辑、依赖补齐逻辑打包在一起本质上解决的是“新手不知道自己在踩坑”的问题。1.3 一键安装到底省了什么所以鱼香ROS一键安装省的不是那几条命令而是省掉了以下这些隐性成本官方源访问慢或失败时的镜像切换逻辑预判当前系统应该装哪个ROS2版本的决策流程缺失编译工具链、Python依赖、colcon插件时的一次性补齐环境变量的自动配置与验证对常见虚拟机、容器、树莓派环境的兼容处理。你可以把它理解成一个“ROS2环境安装的引导程序”它知道你的系统是什么版本、缺少什么依赖、需要什么工具然后按顺序给你补齐。下面我拆一下这套脚本的底层逻辑。2. 鱼香ROS一键安装脚本不是黑魔法先看它执行时做了什么2.1 脚本的核心理念选择大于配置使用鱼香ROS一键安装时你会先看到一个交互菜单里面会有类似“1. 一键安装ROS(支持ROS和ROS2)”这样的选项。选完后它会继续问你“检测到Ubuntu 22.04是否安装ROS2 Humble”你选是然后脚本就开始自动跑。这个交互过程中脚本实际做的事情是探测系统环境通过lsb_release -a或读取/etc/os-release判断当前Ubuntu版本从而决定给你装对应版本的ROS/ROS2。这一步很关键很多新手不知道自己22.04装不了Melodic但脚本知道。配置软件源把ROS官方源或镜像源写进/etc/apt/sources.list.d/并导入对应的gpg key。考虑到国内网络环境脚本通常会在官方源和国内镜像源之间做选择或者直接让用户选。更新与依赖补齐执行apt update并安装python3-pip、python3-colcon-common-extensions、python3-rosdep、build-essential、cmake、git、wget等基础工具。很多人后期编译micro-ROS、Gazebo插件时才发现缺这些一键脚本在源头上就给你装掉了。安装ROS2本体执行sudo apt install ros-humble-desktop或者ros-humble-ros-base你可以根据自己需求选择完整桌面版还是精简版。自动配置环境变量向~/.bashrc写入source /opt/ros/humble/setup.bash部分版本还会检测你当前用的shell是bash还是zsh做对应处理。可选安装rosdep安装并初始化rosdep工具这一步对于后期编译源码包几乎是必需的因为rosdep能用来自动解析ROS包的依赖。2.2 补一条rosdep init 的坑很多人以为一键安装跑完就万事大吉但第一次用源码编译一个ROS2工作空间时还是会碰到ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/osx-homebrew.yaml]: Failed to download target platform data for rosdep如果你是自己手工安装的ROS2大概率会卡在这。因为rosdep init需要从raw.githubusercontent.com拉取配置文件这个地址在部分网络环境下访问不稳定。鱼香ROS一键安装帮你把rosdep初始化好后往往还会顺手处理好这个source的问题或者在脚本菜单里额外提供一个“修复rosdep”的选项。所以我的看法是新手用一键脚本装的不只是ROS还有后面一条龙开发环境的铺垫。2.3 ROS2版本和Ubuntu版本的对应关系如果你的系统是Ubuntu 22.04那么对应的ROS2版本就是Humble Hawksbill。如果你手头是Ubuntu 20.04那么默认带的就是Foxy Fitzroy。这里值得多说一句老项目还在用Foxy新项目尽量跟随Humble或更新版本因为Foxy在2023年就已经EOL了官方不再维护。Ubuntu版本对应ROS2发行版支持状态Ubuntu 20.04Foxy Fitzroy已停止维护Ubuntu 22.04Humble Hawksbill维护中使用最广Ubuntu 24.04Jazzy Jalisco较新逐步普及我给新人的建议很简单如果硬盘上还没有重要数据直接装Ubuntu 22.04然后用一键脚本装Humble。社区资料最多、第三方包兼容性最好、遇到问题搜解决方案最方便。Humble是目前ROS2生态里最值得投入的版本没有之一。3. 实操从空Ubuntu到Turtle冒烟完整跑通一遍3.1 装系统后我建议你先做三件事在运行一键脚本之前有几个前置动作是脚本帮不了你的需要自己确认清楚。第一确认网络稳定。脚本安装过程中要下载大量软件包如果网络断断续续很容易留下半成品的依赖状态。我建议你直接连有线网络或者在Wi-Fi信号稳定的地方操作。第二检查磁盘空间。用下面的命令看一眼df -h/根分区至少留出15GB可用空间。ROS2完整桌面版加上Gazebo和micro-ROS工具链实际占用很容易突破10GB。第三更新系统。在跑安装之前执行sudo apt update sudo apt upgrade -y一个系统更新到一半的Ubuntu比全新系统更容易触发依赖冲突。别跳这一步。3.2 正式运行一键安装脚本打开终端执行wget http://fishros.com/install -O fishros . fishros这里要解释一下为什么用的是. fishros而不是bash fishros。脚本里可能有需要影响当前shell环境变量的内容用source方式执行可以确保环境变量直接注入到你当前的终端会话中。如果你用bash fishros跑脚本内部设置的环境变量只对子shell有效跑完当前终端还是拿不到。脚本跑起来之后你会看到彩色菜单界面。第一次安装我一般建议选择:选择“安装ROS”然后选ROS2系统检测到Ubuntu 22.04后选择安装Humble完整版也就是带desktop选项的那个如果脚本询问是否使用镜像源或默认源根据自己的网络情况选即可国内网络直接选镜像源通常更快。中间过程不需要过多干预它会自动跑完apt安装、环境变量写入等步骤。安装完成后新开一个终端检查环境是否生效ros2 --version如果输出类似ros2 0.9.2说明ROS2环境已经就绪。到这一步很多人会直接收到一份“安装完成”的提示但验证环境还差点意思继续往下走冒烟测试。3.3 跑通第一个ROS2 Demoturtlesim新手验证ROS2是否装好我最推荐的方式是启动turtlesim。它自带可视化界面能直观验证ROS2的节点通信、话题机制、命令行工具是否全部正常。ros2 run turtlesim turtlesim_node正常情况下会弹出一个蓝色背景的窗口中间有一只小乌龟。然后再开一个终端ros2 run turtlesim turtle_teleop_key用键盘的上下左右方向键可以控制乌龟移动。如果乌龟动了说明节点创建正常话题通信正常图形界面渲染正常命令行工具链正常。这里有几个常见问题的快速判断如果第二个终端跑turtle_teleop_key时说找不到包说明turtlesim没有装。在Ubuntu 22.04 Humble下可以单独装sudo apt install ros-humble-turtlesim。如果龟窗口打开了但键盘控制没反应检查你是不是把两个程序跑在同一个终端里了。它们必须分别在两个独立终端中运行。如果窗口闪退或者出现段错误大概率是图形渲染问题这个我在下一章结合Gazebo一起说。3.4 工作空间和colcon这一步决定你后续能不能自己写功能包turtlesim跑通后你还需要验证colcon这个编译工具是否可用。ROS2的源码包都是用colcon构建的。我的建议是直接创建一个最小工作空间试编译mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build如果colcon没装或者环境变量没配对你会看到command not found。这时候回到一键脚本的菜单重新选择安装基础工具链的选项即可。colcon build跑完后工作空间里会生成install目录。记得source它source install/setup.bash在你正式编写自己的ROS2功能包之前先确保这条链路是通的。4. Gazebo仿真环境最容易被忽略的“另一个世界”4.1 你到底该用哪个Gazebo很多新手在装完ROS2后想跑Gazebo仿真结果被两个名字搞晕了Gazebo Classic和Ignition/gz-sim。简单梳理一下区别Gazebo Classic就是我们常说的老版Gazebo在Ubuntu 22.04上对应的是gazebo这个apt包版本是11.x。它和ROS2 Humble的集成通过ros-humble-gazebo-ros-pkgs实现。gz sim / Ignition新一代的仿真器在Ubuntu 22.04上对应的发行版是Fortress命令行工具名是ign gazebo。ROS2 Humble里对应的集成包是ros-humble-ros-ign。如果你只是想跑一个带机器人的仿真环境、加载URDF模型、发布激光雷达和里程计数据直接走Gazebo Classic路线更省事示例多、资料多、排查问题容易。如果你要做流体、多物理场、更高级的传感器仿真再考虑gz sim。我不建议新手一上来就两个都装环境变量和插件之间的干扰会把你直接劝退。4.2 通过apt安装Gazebo Classic并跑通第一个世界Ubuntu 22.04 ROS2 Humble下安装命令sudo apt install ros-humble-gazebo-ros-pkgs sudo apt install gazebo第一条命令会安装Gazebo的ROS2插件和启动文件第二条命令安装Gazebo Classic本体。装完后试启动gazebo如果一切正常你会看到一个空的世界里面有地面和天空。然后验证ROS2和Gazebo的桥梁是否工作。另开终端ros2 topic list正常情况下能看到一些固定话题其中可能包括/gazebo/link_states、/gazebo/model_states这些话题。如果能看到说明Gazebo已经把仿真状态发布到了ROS2网络里。这就是“仿真环境”并入“ROS2计算图”的标志。4.3 VMware里Gazebo闪屏我验证过的几种处理方案开头我就提到过VMware里跑Gazebo闪屏问题很典型。现象是Gazebo窗口打开后不断闪烁或者只有鼠标移动时画面才刷新有的还带着明显的撕裂感。先说明原因这是客户机图形加速和Gazebo的OpenGL渲染不兼容导致的结果。VMware默认开启“加速3D图形”但在某些Linux桌面环境下这个加速反而让渲染线程崩溃或混乱。处理方案按优先级排序关闭VMware的3D加速。在虚拟机设置 - 显示器 - 取消勾选“加速3D图形”。这个方法对Gazebo Classic的闪屏问题最有效。降低渲染画质。在Gazebo里点击Window - Lighting把shadows关掉这在老显卡驱动下也能明显改善闪烁。使用软件渲染强制模式。启动Gazebo时加参数export LIBGL_ALWAYS_SOFTWARE1 gazebo通过环境变量强制OpenGL走软渲染虽然性能会下降但至少不闪了。如果你用的是Workstation Pro 16或17可以更新open-vm-tools和虚拟机显卡驱动到最新部分情况下闪屏问题在新驱动里被修复。我用过最稳妥的组合是“关闭3D加速 软件渲染”。在这个组合下跑ROS2和Gazebo Classic速度说不上快但稳定至少不会被画面闪烁逼疯。如果你用的是VirtualBox遇到同类问题时LIBGL_ALWAYS_SOFTWARE1同样是最快的救急手段。4.4 加载模型时最容易踩的三个坑Gazebo装好、空世界能打开之后很多人下一步就是加载一个机器人模型文件比如panda机械臂或者其他机器人。这里有几个高频坑值得提前说。第一模型路径问题。Gazebo默认去~/.gazebo/models/找模型而ROS2包中的模型通常在/opt/ros/humble/share/目录下。如果没有把模型路径加入GAZEBO_MODEL_PATH就会报[Err] [ModelDatabase.cc:1039] Failed to open model。解决方案export GAZEBO_MODEL_PATH/opt/ros/humble/share/gazebo-ros-pkgs/models:$GAZEBO_MODEL_PATH第二URDF和SDF的区别。ROS2里机器人描述文件常用URDF格式但Gazebo Classic加载的是SDF格式。哪怕你在一个SDF文件里嵌套了URDF也很容易因为版本语法差异导致模型加载一半就崩了。我的建议是用ros2 run urdf_to_gazebo之类的转换工具或者直接用现成的SDF示例文件起步。第三spawn实体时坐标不对。用ros2 service call /spawn_entity gazebo_msgs/SpawnEntity加载机器人时经常出现“模型加载了但看不到或者说模型碰撞体积和视觉体积错位”的问题。这时候先检查SDF文件里的pose标签是否设了非零值再检查模型是否放置在地面以下。太多人把模型放在y0z-0.1的位置结果直接被地面埋掉一半。5. micro-ROS实战让MCU和ROS2真正对话5.1 为什么ROS2生态里要专门搞一个micro-ROS这个问题的答案用过一次串口通信就会立刻明白。ROS2节点跑在Linux系统上内存和CPU随便用但机器人底层总得有单片机控制电机、读取编码器、采集IMU数据吧。STM32、ESP32这类MCU跑不了完整的ROS2运行时所以micro-ROS做了这样一个桥梁MCU作为micro-ROS Client节点通过串口或WiFi连接主机上的micro-ROS Agent以XRCEDDS-XRCE协议通信。对ROS2计算图来说MCU就是一个普通的ROS2节点你可以直接ros2 topic echo看它发布的数据对MCU来说它只承担了最轻量的通信协议栈。说白了micro-ROS解决了两个事一是把MCU接入ROS2网络的协议开销降到最低二是让上层算法不用关心底层数据到底来自Linux进程还是单片机引脚。5.2 在ROS2中安装micro-ROS Agentmicro-ROS Agent的运行环境在Ubuntu主机上。最推荐的方式是下载预编译包但为了保证和当前ROS2版本的兼容性我都走源码编译路线。步骤如下。先创建工作空间并克隆micro-ROS相关源码mkdir -p ~/microros_ws/src cd ~/microros_ws git clone -b humble https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup cd src/micro_ros_setup rosdep update rosdep install --from-paths . --ignore-src -y cd ~/microros_ws colcon build source install/local_setup.bash注意如果你用的是ROS2 Humble-b humble分支必须对应。这里如果ROS环境变量没配置好会在rosdep install阶段报很多“找不到依赖”的错所以建议把前面的环境变量source都确认一遍再动手。接着构建Agentros2 run micro_ros_setup create_agent_ws.sh ros2 run micro_ros_setup build_agent.sh source install/local_setup.bash编译成功后启动Agentros2 run micro_ros_agent micro_ros_agent udp4 --port 8888这个时候Agent就在UDP 8888端口上监听了。如果板子是通过串口连接命令改为ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0 -b 115200这一步需要注意Linux下访问串口需要权限把当前用户加到dialout组能省掉后面一堆麻烦sudo usermod -aG dialout $USER5.3 给ESP32刷micro-ROS固件我用ESP32做demo比较多因为便宜、WiFi能力强、不用额外买调试器。micro-ROS官方工具链也支持一条龙创建固件工作空间。ros2 run micro_ros_setup create_firmware_ws.sh firmware esp32 ros2 run micro_ros_setup configure_firmware.sh transport udp ros2 run micro_ros_setup build_firmware.shconfigure_firmware.sh执行时脚本会通过图形化或命令行交互方式问你Agent的IP地址和端口。注意这里填的IP是Ubuntu主机的IP不是ESP32自己的IP。如果ESP32和主机在同一个局域网下直接用udp4通信最简单。烧录时用ESP-IDF的idf.py flash命令或者用Arduino IDE直接选串口烧录。我一直建议新手用ESP-IDF的micro-ROS例程走一遍熟悉流程之后再考虑Arduino库方式。板子启动后如果一切正常你会在Agent的终端里看到类似这样的日志[2025-01-01|12:00:00.000] [info] Session established此时在主机上ros2 topic list如果能看到/micro_ros_arduino_node_publisher或者自己定义的节点话题那就说明MCU已经作为ROS2节点挂在计算图里了。这一步的成就感非常强——你手上那块单片机现在真的变成ROS2的一个活节点了。5.4 我踩过的micro-ROS坑乱波特率和IP填错第一坑串口通信时Agent和固件里的波特率必须完全一致。我遇到过很多次Agent启动命令里写-b 115200但固件里配的是921600两边都没报错但就是没有任何数据通信。排查方法很简单用screen /dev/ttyUSB0 115200看串口是否有乱码有乱码就说明波特率对不上或者Agent没启动。第二坑UDP通信时IP会变。尤其是ESP32走WiFi时如果路由器分配的IP变了Agent就找不到设备了。建议在路由器上给ESP32固定静态IP或者直接在代码里写固定IP。我后来把所有基于ESP32的micro-ROS demo都改成了AP模式ESP32自己开热点主机直连避免整个局域网调度的不确定性。第三坑rosdep update失败导致无法构建micro-ROS setup。这个很关键在构建micro_ros_setup之前先跑一次rosdep update如果发现从GitHub拉取失败就检查是不是网络代理问题。鱼香ROS一键安装会在这一步替你缓存好rosdep配置这个恩情等你编译micro-ROS时会还上的。6. 安装跑通之后我建议你马上做的三件事6.1 把常用路径和环境变量固化下来一键脚本帮你安装了ROS2本体但你的个人工作环境还缺一些固化动作。比如我习惯把以下内容写进~/.bashrcsource /opt/ros/humble/setup.bash source ~/ros2_ws/install/setup.bash export GAZEBO_MODEL_PATH$GAZEBO_MODEL_PATH:/opt/ros/humble/share/gazebo-ros-pkgs/models这样每次打开终端ROS2环境和工作空间环境自动就绪不用每次手动source。有人担心多个版本ROS2共存的问题我的建议是你日常开发只用Humble别在.bashrc里同时source多个版本否则ros2命令指向哪个版本完全不可控。真要测试其他版本时用Docker隔离干净利落。6.2 跑一个带传感器的机器人仿真再进micro-ROS很多新手直接把micro-ROS板子接上就跑话题但实际上最完整的练手路径应该是先在Gazebo里跑一个带雷达和IMU的机器人仿真看它发布的数据流然后编写一个只订阅雷达话题的Python节点最后把同样的消息定义放到micro-ROS板子上让板子直接发送雷达数据。这条链路走通后你对“自底向上的机器人通信”会有很直观的理解而不只是停留在“装个环境跑一下demo”的程度。6.3 给自己建一个排错清单最后说点实操层面的心得。安装类的问题大多有固定答案但我发现新手反复踩的坑其实很集中。我给自己的团队整理过一份mini排错清单这里共享出来ros2: command not found优先查~/.bashrc里是否source了setup.bash再查ROS2是否真的装到了/opt/ros/humble/下。启动gazebo闪退先试LIBGL_ALWAYS_SOFTWARE1 gazebo再查显卡驱动不要一上来就重装。rosdep update超时检查对GitHub的连通性必要时配好代理或直接在鱼香ROS菜单里选“修复rosdep”。micro-ROS的Agent连不上板子先确认串口设备是/dev/ttyUSB0还是/dev/ttyACM0再检查波特率是否一致最后查防火墙是否挡了UDP端口。编译自己的功能包报ament_cmake相关错误确认ros-humble-ament-cmake已安装且colcon build是在工作空间根目录执行的。这个清单看起来平淡无奇但能帮你省下的排查时间可能比一键安装本身还多。我个人在实际操作中的体会是鱼香ROS一键安装是进入ROS2世界的快车道但它解决的是“起步”问题不是“所有”问题。装好环境只是开始真正让你成长的是跑Gazebo仿真时的模型坐标调试、是micro-ROS板子联网时的IP排查、是第一次在rviz2里看到自己写的节点数据完整流动起来的那一刻。希望这篇指南能帮你把环境这关快速迈过去把时间花在更有价值的机器人开发本身。