Ubuntu 18.04安装ROS Melodic完整避坑指南

1. 装 ROS 之前先把这些事想清楚1.1 为什么很多人卡在安装这一步先说个现象。我见过太多人在 ROS 入门的第一周就放弃了不是被机器人学劝退的而是被安装过程折磨到崩溃。终端里刷出几百行报错、rosdep update 卡在百分之十几不动、装完发现找不到 roscore 命令……这些场景我全经历过。所以这篇笔记不讲机器人理论只讲一件事怎么在 Ubuntu 18.04 上把 ROS Melodic 装好、装对、装完能顺利跑起来。如果你正在看这篇笔记大概率是以下三种人之一刚接触 ROS 的在校学生、准备用 ROS 做课题或比赛的研究生、以及工作中需要把机器人原型跑起来的工程师。不管你是哪一种这篇文章的目标都很一致——跟着步骤走完你的电脑上会出现一个能正常启动的 ROS Melodic 环境还能顺利跑通一个最简单的发布订阅例子。我自己装 ROS 的次数应该超过二十次了从最早的 Indigo 到后来的 Kinetic、Melodic 再到 Noetic踩过的坑攒了一箩筐。Melodic 这个版本被问得最多因为它对应 Ubuntu 18.04而这个系统版本直到今天还有大量教学机器和旧设备在用。官方文档给的是英文步骤看着挺简洁但实际执行的时候总会在某个节点炸掉尤其是网络相关的问题。这篇文章把我在多次装机过程中验证过的完整流程整理出来每一步都解释清楚为什么要这么做遇到问题也能按图索骥。1.2 为什么选 Melodic 而不是更新的版本ROS 的版本和 Ubuntu 系统是严格绑定的不是你想装哪个就装哪个。Melodic 对应 Ubuntu 18.04 BionicNoetic 对应 Ubuntu 20.04 Focal。如果你的系统已经是 20.04 或更高理论上装 Noetic 更合适但如果你用的是 18.04能选的主流版本就只有 Melodic。从实际体验来看Melodic 是 ROS 1 系列里相当成熟稳定的一个版本。它发布在 2018 年经过了多年的社区验证网上能搜到的教程、开源代码、论文配套代码大多基于这个版本。很多高校的 ROS 课程、开源机器人项目比如一些移动底盘、机械臂的控制代码都默认你用的是 Melodic。虽然 ROS 1 的官方支持已经停止但社区积累的资料多到根本看不完对于学习来说反而是个优势。再有就是兼容性问题。很多已有的功能包、驱动、第三方库只适配 Melodic 的依赖关系换到新版本就可能编译报错。如果你在做课题或者复现别人的工作跟着对方的版本走是最稳妥的。我见过不少同学为了用新版本去装 Noetic结果发现某个功能包没有 Noetic 版本又灰溜溜地换回 Melodic。先确认你手上的项目需要什么版本再决定装什么这个顺序别搞反了。1.3 安装方式的取舍desktop-full 还是精简版ROS 的官方安装方式主要分几种desktop-full、desktop、ros-base。翻译成人话就是全家桶、常规桌面版、光杆司令。我的建议是除非你的磁盘空间真的紧张到只剩几个 GB否则直接装 desktop-full。这个版本包含了 ROS 的核心功能、常用的可视化工具 Rviz、仿真工具 Gazebo、各种导航和感知相关的功能包还有大量调试用的命令行工具。一次装齐后面学习的时候基本不用再补装什么。有些人喜欢先装 ros-base用到什么功能再补什么。听起来很省事但实际操作中你会不断遇到找不到某个头文件命令不存在这类问题每次都要停下来搜教程补装依赖非常打断学习节奏。装 desktop-full 多占几个 GB 的磁盘换来的是后面几个月不折腾依赖这笔账很划算。另外要注意Melodic 的环境需要 Python 2.7 的支持。这一点很多人忽略后面会专门讲它对系统环境的影响尤其是电脑上装了 Anaconda 的同学这是我见过最多的翻车原因之一。2. 安装前的环境准备2.1 先花五分钟确认系统版本装 ROS 之前第一件事是确认你的 Ubuntu 版本。很多人买了电脑或者虚拟机镜像之后压根不知道自己装的是什么版本等到安装过程报错才反应过来系统不对。打开终端输入下面的命令cat /etc/os-release看一下 VERSION 那一行是不是 18.04.x。如果是 16.04那就要装 Kinetic 而不是 Melodic如果是 20.04对应的是 Noetic。版本不对的话要么换系统镜像重新装要么老老实实换对应的 ROS 版本不存在跨版本安装的捷径。还有一种情况是用 WSL 或者 Docker 来装 ROS。WSL 2 配合 Ubuntu 18.04 的发行版是可以跑 Melodic 的但是图形界面Rviz、Gazebo需要额外配置显示转发新手容易卡住。虚拟机则要注意给足内存和 CPU至少 4GB 内存、双核处理器起步不然后面跑 Gazebo 的时候会卡得怀疑人生。我自己习惯用 VMware 开虚拟机来测试不同版本的 ROS只要配置给够和物理机上安装没有太大区别。2.2 网络环境检查这一步比想象中重要ROS 的安装过程需要从 Ubuntu 的软件源服务器和 ROS 官方服务器下载大量软件包。如果你的网络访问这些服务器很慢安装过程就会变得极其痛苦。尤其是 rosdep update 那一步卡上半个小时都不奇怪。我的做法是安装前先测试一下到目标服务器的连通性。打开终端试一下ping -c 4 archive.ros.org如果延迟很高或者直接丢包建议先把 Ubuntu 的软件源换成国内镜像源ROS 的软件源也可以换成镜像站。换源的方式很简单打开软件和更新设置在下载自那里选择其他站点然后从列表里挑国内的镜像地址点击选择服务器后它会自动刷新索引。这一步很多人觉得无所谓实际上非常关键。我在帮同学排查安装失败的时候超过一半的问题都出在网络上面。你想想安装 ROS 需要拉取几百个软件包如果每个包都要超时重试时间成本直接翻好几倍。把源换好安装过程会流畅很多。2.3 清理历史残留避免新旧环境打架如果你之前装过某个 ROS 版本但没装成功或者卸载得不干净系统里可能残留了一些配置文件和环境变量。这些残留物会在新安装的时候捣乱出现各种奇怪的冲突。建议安装前执行一个清理命令把已有的 ROS 相关包全部清掉sudo apt purge ros-*然后清理依赖sudo apt autoremove这不一定会影响你后续安装——实际上 apt 在装新包的时候大概率能自动处理但干净的系统环境能让你更容易判断报错来自于安装过程本身而不是历史残留。我踩过最大的坑就是之前装了一半失败第二次重装的时候有些包已经装上了有些没装上结果系统处于一个半 ROS 状态跑什么都缺文件排查了半天才反应过来是残留问题。另外如果你的 ~/.bashrc 文件里以前写过和 ROS 相关的 source 语句也建议先打开看一眼把旧的行注释掉或者删掉。不然每次新开终端都会尝试加载一个根本不存在的环境文件终端一打开就是一行红字报错非常影响心情。3. 完整安装流程实录3.1 添加软件源把 ROS 的仓库地址告诉系统ROS 的软件包不在 Ubuntu 默认的软件源里需要手动添加 ROS 官方的软件源地址。官方文档给的是sudo sh -c echo deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main /etc/apt/sources.list.d/ros-latest.list这条命令会把 ROS 的软件源地址写入到 /etc/apt/sources.list.d/ros-latest.list 这个文件里。$(lsb_release -sc) 会自动获取你当前系统的版本代号比如 18.04 返回的是 bionic。如果网络访问官方源速度太慢可以换成国内镜像。比如用清华或者其他高校的镜像地址把上面的 packages.ros.org 替换成对应的镜像地址就行。这里我多说一句不管你用哪个源格式一定不要写错尤其是最后的 main 参数。写错了 apt 更新的时候会提示仓库格式有问题。添加完源之后执行sudo apt update正常情况下应该能看到大量的更新信息并且在列表里出现和 ROS 相关的条目。如果 apt update 报错先检查源地址是不是写错了再检查网络连接。这一步是后面所有操作的前提一定要确认通过之后再继续。3.2 添加密钥让系统信任这个软件源软件源是需要密钥认证的。ROS 官方提供了一个公钥系统要用它来验证从源下载的软件包确实是官方发布的。不加密钥的直接后果就是 apt update 的时候报一堆 NO_PUBKEY 错误让你根本没法继续。官方提供的方法是sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-key C1CF6E31E6BADE8866B172B4F42ED6FBAB17C654这条命令会从指定的密钥服务器拉取官方公钥并添加到系统信任列表里。如果你执行的时候提示连接超时可以试试其他密钥服务器比如sudo apt-key adv --keyserver hkp://pgp.mit.edu:80 --recv-key C1CF6E31E6BADE8866B172B4F42ED6FBAB17C654或者用国内速度更快的服务器。总之目标就一个让 apt 信任这个源。加完密钥之后最好再执行一次 sudo apt update确认没有密钥相关的报错。顺便提一嘴如果你用的系统版本比较新可能会看到 apt-key 的弃用警告。这是正常的Melodic 的年代 apt-key 还是主流方案警告不影响使用。3.3 安装 ROS 本体核心一行的命令密钥就位、源就位之后安装本体反而不难了。一条命令搞定sudo apt install ros-melodic-desktop-full这一步会开始下载并安装 ROS 的核心模块和大量工具包。根据网络速度不同可能需要十几分钟到一个小时。安装过程中会提示你确认磁盘空间占用输入 Y 回车即可。这里我想强调一个细节安装过程中如果某个包的下载失败apt 通常会在最后统一报错并提示你重试。别慌直接再执行一次安装命令就行apt 会跳过已经装好的包只补装失败的。我最多一次重试了三遍才全部装完但最终系统是好的不影响使用。安装完成后你可以检查一下关键组件是否存在dpkg -l | grep ros-melodic | wc -l这个命令会统计已安装的 ROS 包数量。正常情况下应该有好几百个如果只有寥寥几个说明安装过程有问题需要重新检查。3.4 初始化 rosdep管理依赖关系的必要步骤rosdep 是 ROS 用来管理功能包依赖的工具。当你要编译一个工作空间的代码时rosdep 会帮你检查这个代码用到了哪些第三方库并提示你安装缺少的依赖。没有 rosdep很多源码包你根本编译不过去。初始化分为两步。第一步sudo rosdep init这条命令会往 /etc/ros/ 目录下写入 rosdep 的初始化文件。如果提示command not found说明 rosdep 工具没有安装需要先手动安装sudo apt install python-rosdep python-rosinstall python-rosinstall-generator python-wstool build-essential装完再执行 sudo rosdep init。第二步是更新依赖索引rosdep update这步会从 ROS 官方服务器拉取所有功能包的依赖关系描述网络不好的时候非常容易卡住。如果 update 一直超时或者长时间没有反应可以考虑配置 rosdep 使用国内源。具体方法是修改 /etc/ros/rosdep/sources.list.d/20-default.list 文件把里面的地址替换成可用的国内地址。说实话rosdep update 是整个安装过程中最容易让人崩溃的一步。很多人卡在这里就放弃了但其实这一步就算暂时没成功ROS 的核心功能已经可以用了。你可以先跳过它继续后面的步骤等之后编译具体项目的时候再回来处理。我会在后面的排查清单里专门讲怎么处理这个问题。3.5 配置环境变量每次打开终端自动加载 ROSROS 装好之后系统还不会自动知道它的存在。你需要把 ROS 的环境变量加载脚本写入到 ~/.bashrc 文件里这样每次打开新终端ROS 的相关环境就自动配置好了。执行echo source /opt/ros/melodic/setup.bash ~/.bashrc source ~/.bashrc第一行把 source 语句追加到 bashrc第二行立即生效。配置完成之后可以验证一下echo $ROS_DISTRO如果输出 melodic说明环境变量配置成功。这一步千万不要跳过也别图省事只在当前终端里 source 一下。不然你新开一个终端ROS 命令全都找不到还以为自己没装好。我帮别人排查问题时至少有三次发现装好了但不能用的根源就是 bashrc 里没写那行 source。3.6 创建工作空间给后续项目安个家ROS 的项目代码组织在工作空间里。即使你现在只是学习阶段也建议把工作空间建好提前熟悉这个流程。官方推荐的创建方式是使用 catkin 工具mkdir -p ~/catkin_ws/src cd ~/catkin_ws/ catkin_make执行 catkin_make 的时候系统会编译工作空间中的功能包。新建的空白空间也会被初始化生成 build 和 devel 两个目录同时创建一个 devel/setup.bash 环境文件。之后你需要 source 这个文件echo source ~/catkin_ws/devel/setup.bash ~/.bashrc source ~/.bashrc注意 bashrc 里现在有两行 source一行加载系统级的 ROS 环境/opt/ros 路径下一行加载你自己的工作空间环境~/catkin_ws 路径下。顺序上系统级的在前、工作空间的在后这样才能让工作空间里的功能包覆盖同名系统包这是 ROS 的环境叠加机制。然后用一个命令验证 catkin 是否正常echo $ROS_PACKAGE_PATH正常的话输出里应该包含 /opt/ros/melodic/share 和 /home/你的用户名/catkin_ws/src 这两个路径。到这里ROS Melodic 的安装和环境配置就算彻底完成了。下面我们验证一下确保它真的能用。4. 验证安装跑通你的第一个 ROS 例子4.1 基础组件验证roscore 是试金石安装完成后最直接的验证方式就是启动 roscore。roscore 是 ROS 的核心服务相当于 ROS 系统的心脏所有节点之间的通信都要经过它。打开一个终端输入roscore第一次启动的时候你应该会看到一大堆日志信息包括 ROS 版本号、节点地址、服务地址等。看到最后一行类似 started core service [/rosout] 的输出说明 ROS 核心启动成功。如果这一步能通过你的 ROS 安装基本没问题。注意保持这个终端开着不要关掉后面的操作需要在另一个终端里进行。如果在启动 roscore 的时候报网络相关错误比如无法解析主机名之类通常是 /etc/hosts 文件的问题。虚拟机上比较常见需要手动把主机名解析到 127.0.0.1。这个问题我会在排查清单里详细说明。4.2 小乌龟示例ROS 版的 Hello World小乌龟turtlesim是 ROS 自带的入门演示程序装好 desktop-full 之后它就在系统里了。这个例子虽然简单但能直观地展示 ROS 的发布订阅机制是怎么运作的我推荐每个新手都至少跑一遍。保持 roscore 所在的终端开着新开一个终端输入rosrun turtlesim turtlesim_node一个窗口会弹出来里面有一只小乌龟和一个空荡荡的蓝色画布。然后再开一个终端输入rosrun turtlesim turtle_teleop_key这时你可以用键盘的方向键控制小乌龟在画布上移动。按方向键的时候teleop_key 节点会把按键信息发布成一个话题topicturtlesim_node 订阅这个话题并让乌龟动起来。这个例子背后对应的就是 ROS 最基本的通信模型一个节点发布数据另一个节点订阅数据。你还可以用下面的命令查看当前系统中正在运行的话题rostopic list用下面的命令查看某个话题的内容rostopic echo /turtle1/cmd_vel然后回到控制乌龟的终端按几个方向键你会在 echo 的终端里看到实时的速度指令数据在刷新。这一步能把话题通信这个概念从抽象的文字变成肉眼可见的实时数据流理解起来会容易很多。4.3 编译一个自己的功能包完整走一遍工作流跑通小乌龟只是验证了系统的核心功能如果要验证编译流程没问题最好自己建一个最简单的功能包然后编译一遍。这也是 PPT 上不会告诉你、但实际开发一定会用到的过程。先在工作空间的 src 目录下创建功能包cd ~/catkin_ws/src catkin_create_pkg test_pkg roscpp rospy std_msgs这个命令会生成一个名为 test_pkg 的功能包并声明它依赖 roscpp、rospy 和 std_msgs 这三个库。roscpp 是 C 客户端库rospy 是 Python 客户端库std_msgs 是标准消息定义。回到工作空间根目录编译cd ~/catkin_ws catkin_make如果看到类似 Finished processing test_pkg 的信息说明整个编译流程是通的。之后再使用 source ~/devel/setup.bash 的时候test_pkg 就已经在你的 ROS 环境里注册了。我见过不少同学学了一两个月 ROS从来没有自己建过功能包都是用课程提供的现成代码。等到课程设计要自己写程序的时候连 catkin_create_pkg 都不会用还得回头补。建议你现在就建一个空包走一遍流程花不了几分钟但能让你对整个开发流程有一个完整的感知。5. 踩坑实录我遇到过的八个典型问题5.1 添加密钥失败apt update 报 NO_PUBKEY这个问题的本质是信任链断裂——系统不认识这个软件源的签名拒绝让它安装任何东西。报错内容一般长这样W: GPG error: http://packages.ros.org/ros/ubuntu bionic InRelease: The following signatures couldnt be verified because the public key is not available: NO_PUBKEY ...处理思路是确认你用的是哪个密钥服务器换着试几个。有些服务器在国内访问不稳定多试几次总能成功。如果你用的是国内镜像源也可以直接去镜像站找对应的公钥文件下载后用 sudo apt-key add 导入。另外有些教程会让你用 --keyserver hkps://keyserver.ubuntu.com:443 这种带端口的写法。端口不同成功的概率也不同都值得试一试。5.2 rosdep update 卡住或者超时这是整个安装过程中最常见也最让人崩溃的问题没有之一。卡的位置通常在某个百分比阶段长时间不动或者直接报 timeout 错误。我的处理建议分三步走。第一步换网络环境试试看——比如用手机热点、换一个网络连接有机会直接解决。第二步配置国内源加速改 /etc/ros/rosdep/sources.list.d/20-default.list 文件把开头的 https://raw.githubusercontent.com 这类地址替换成可用的国内镜像地址。第三步如果实在搞不定可以先跳过这一步后面用到具体功能包的时候再回来处理。需要说明的是rosdep init 和 rosdep update 的作用是给系统建立一个依赖索引数据库没有这个数据库你编译别人的功能包时会缺少自动解析依赖的能力。但对学习阶段影响不大你可以先跑通基本流程等真正遇到编译需求的依赖再回来解决也不迟。5.3 打开新终端后 ROS 命令找不到了症状是一个终端里能用 roscore新开终端输入 rosversion 提示 command not found。这种情况十有八九是 ~/.bashrc 里没有写 source 语句或者写的路径不对。检查一下cat ~/.bashrc | grep source正常应该能看到一行 source /opt/ros/melodic/setup.bash。如果没有按前面 3.5 节的步骤补上即可。如果写了路径但提示文件不存在去 /opt/ros/ 目录下 ls 一下确认你的 ROS 是不是装在其他路径了。5.4 安装了 Anaconda 导致 Python 环境被搞乱这个坑我见得最多也是最容易踩的。ROS Melodic 基于 Python 2.7而 Anaconda 通常会把系统的 Python 默认指向它的 Python 3.x 环境。一旦 conda 环境被激活ROS 的很多工具会用错 Python 解释器出现各种诡异问题。典型报错是ImportError: No module named rospkg或者 import rospy 直接失败。解决方案很简单用 conda 的时候把 conda 的 base 环境停掉不激活任何 conda 环境再使用 ROS。具体配置方式是在 ~/.bashrc 里注释掉 conda 的初始化行或者在使用 ROS 的终端里先执行 conda deactivate。如果你确实需要在 conda 环境里用 ROS就需要把 ROS 的 PYTHONPATH 手动指到 Python 2.7 对应的目录还要注意不要用 pip 往 base 环境里乱装包。不过我的建议是学习阶段老老实实系统默认 Python别套 conda能省掉大量烦恼。5.5 虚拟机上运行特别卡顿如果你在虚拟机上装 ROS运行 Rviz 或者 Gazebo 时画面卡顿是常态不用太担心因为它本身就很吃图形性能。但卡到鼠标都拖不动就不是正常现象了需要优化配置。优化方向有这么几个第一虚拟机设置里把内存调大建议至少 4GB有条件给到 6GB 或 8GB第二开启 3D 加速VMware 和 VirtualBox 都有这个选项第三减少同时运行的重型程序别开着浏览器十几个标签页再跑仿真。另外启动 Gazebo 的时候加 --verbose 参数可以看到它到底在加载什么有些明显的报错信息会有提示。5.6 roscore 启动报网络地址错误在虚拟机上或者网络环境比较复杂的机器上roscore 启动时有时会报下面这种错误Unable to register with master node [http://localhost:11311]: master may not be running yet. Will keep trying.或者提示 ROS_HOSTNAME 和 ROS_MASTER_URI 配置有问题。绝大多数情况下这是 /etc/hosts 文件的问题。打开这个文件sudo vim /etc/hosts在里面加一行127.0.0.1 你的主机名把你的主机名替换成实际用户名对应的主机名用 hostname 命令可以查看。加上之后保存重启之后 roscore 应该就能正常起来了。这个问题本身不难但如果你不知道 hosts 文件的作用很容易在排查上绕好几个小时。5.7 安装过程中途失败重试一直报错前面提到过apt 安装失败后重试通常能解决问题但也存在一种情况某个包的依赖关系被破坏apt 提示你需要先修复。处理方式是sudo apt --fix-broken install这个命令会尝试自动修复损坏的包依赖。执行完之后再重新安装 ROS。如果这个方法解决不了可以考虑把所有 ROS 相关的包先清掉重新走一遍完整的安装流程。清理命令在 2.3 节里已经给过了。5.8 找不到 turtlesim 或者 rosrun 命令不存在有些精简安装只装了 ros-baseturtlesim 不在其中。解决方案是手动补装sudo apt install ros-melodic-turtlesim如果你用的是 desktop-full 但提示找不到 rosrun那问题就出在环境变量没配置好回去检查 3.5 节的内容。rosrun 位于 /opt/ros/melodic/bin 目录下确认这个路径是否在你的 PATH 环境变量里。6. 安装完成之后给新手的几条建议6.1 先把截图记录系统状态这个习惯养成安装过程中难免遇到问题。我的经验是报错信息截图保存下来这比向别人描述反正就是报错了要有效得多。很多问题你截图之后自己多看两眼往往就能发现一些线索比如某个路径写错了、某个包缺失了。就算自己解决不了把截图发出去别人一眼就能定位问题效率高得多。6.2 学习 ROS 的正确打开方式装好 ROS 只是万里长征第一步。接下来建议按这个顺序学先理解节点node、话题topic、服务service、消息message这四个核心概念然后自己写一个发布订阅的例子用 rospy 比 roscpp 上手快再试着用 Rviz 可视化一些数据最后再碰仿真和导航。写代码的时候记住一个原则先跑通再优化。ROS 项目涉及的概念多、层级深一次想理解所有细节是不现实的先让程序跑起来建立信心再逐步深入内部机制这个路径我验证过很多次对新手最友好。6.3 遇到问题的搜索技巧最后分享一个很实用的技巧。搜 ROS 报错的时候把报错信息里和你系统相关的路径、用户名、主机名之类的信息去掉再复制到搜索引擎里搜。比如usercomputer:~/catkin_ws$这种前缀要删掉搜索的关键词是核心报错语句。另一个技巧是搜索的时候加上版本号关键词比如melodic或者python2能过滤掉大量 Noetic 环境下的无效信息。ROS 的社区论坛answers.ros.org上面沉淀了大量历史问答很多你以为独一无二的问题其实早在几年前就有人问过并解决了耐心翻一翻比自己在代码里瞎猜要快得多。我在帮同事和新手同学排查安装问题的时候最深的感触是绝大多数安装失败都不是什么高深的技术难题而是环境和细节问题。源没配好、密钥没加、环境变量没写、Python 环境被 conda 占了翻来覆去就是这么几个原因。把这篇笔记里的步骤按顺序走一遍再对照排查清单看一遍你大概率能顺利拥有一台能跑 ROS Melodic 的机器。后续的学习笔记里我会继续更新工作空间搭建、话题通信实战和仿真工具使用这些内容到时候再一起聊。