ROS 这套东西第一次装的人几乎都会在同一个地方卡住——不是不会写代码而是连环境都没跑起来。Ubuntu 上装 ROS 或 ROS2官方文档给的步骤看着挺清楚真照着敲十有八九会在 apt 源、GPG 密钥、rosdep 初始化这几步上翻车最后对着满屏红字怀疑人生。这篇就聊一件事在 Ubuntu 上用一键安装脚本把 ROS 或 ROS2 装上并且装完是真能跑起来的那种。关键词就四个——ROS、Ubuntu、ROS2、一键安装但背后的细节远不止这四个词能概括。不管你是刚买完新电脑准备入门 ROS2 的学生还是手里那台老虚拟机重装了三遍还没配好环境的工程师下面这些内容应该都能帮你少走几个晚上的弯路。1. 手工装 ROS 的人到底卡在哪几个环节1.1 官方步骤看着只有四行实际每行都有雷ROS 官方文档的安装流程提炼出来就四步配置软件源、导入密钥、apt 更新、安装桌面版。听起来很简洁但真正动手的时候每一步都可能出问题。第一步配源官方给的是直接echo一行 deb 地址到/etc/apt/sources.list.d/。问题在于这行地址指向的是境外服务器国内网络环境下 apt update 经常卡在Waiting for headers然后超时。有人会想到换成国内镜像但换源又有讲究——ROS 的包在 Ubuntu 主源里是没有的必须单独指向 ROS 的镜像仓库而且不同 Ubuntu 版本对应的 codename 不一样写错一个字母就是 404。第二步导入密钥这一步现在官方改成了把 GPG 公钥下载到/usr/share/keyrings/目录再引用。如果网络不通下载下来的是个空文件或者 HTML 错误页apt 就会报NO_PUBKEY。更坑的是这个错误不会在第一步暴露而是等到你 apt update 的时候才炸出来很多人根本想不到问题出在密钥上。第三步 apt update 报错第四步安装包名写错比如把ros-humble-desktop写成ros-humble-desktop-full后者在 ROS2 里根本不存在。这四步之间环环相扣任何一步失败都会导致后面全错。1.2 真正拖时间的不是安装是 rosdep装完二进制包其实只是开始。ROS 的很多功能包依赖一堆系统库这些依赖靠 rosdep 工具来解析和安装。而 rosdep 的初始化需要从境外地址拉取一份索引文件这一步在国内网络下成功率极低。我见过太多人的进度条停在这里sudo rosdep init卡住不动或者报ERROR: cannot download default sources list from ...。网上流传的解决方案五花八门有手动改 hosts 的有找别人拷贝索引文件的还有直接放弃 rosdep 手动装依赖的。这些办法都能用但都属于「治标」而且换个系统就得重来一遍。这就是为什么社区里会有人专门做一键安装脚本——它不是偷懒而是把上面这些零散的、依赖网络环境的、容易出错的步骤打包成一个可以重复执行的东西。1.3 一键脚本解决的其实是「可重复性」问题从工程角度看环境搭建最重要的不是快而是可重复。你在一台机器上折腾三小时装好了换个虚拟机或者重装系统同样的坑还得再踩一遍。一键脚本的价值就在于它把「我这次是怎么装成功的」这个经验固化成了代码。所以下面要聊的这套方法核心不是让你少敲几行命令而是让你有一套能稳定复现的安装路径。2. 鱼香 ROS 一键安装脚本的执行逻辑拆解2.1 脚本是怎么判断你该装哪个版本的社区里流传最广的 ROS 一键安装方案是鱼香 ROS 提供的那套脚本运行方式通常是这样一行wget http://fishros.com/install -O fishros . fishros它跑起来之后会先做系统探测读取/etc/os-release里的VERSION_ID和VERSION_CODENAME判断你当前是 Ubuntu 18.04、20.04、22.04 还是 24.04。然后根据版本给出可选的 ROS 发行版列表。这个探测逻辑很关键。因为 ROS 发行版和 Ubuntu 版本是强绑定的你在 20.04 上想装 Humble脚本会直接告诉你装不了——Humble 只支持 22.04。反过来在 22.04 上装 Noetic 也不行Noetic 是 ROS1 的最后一个版本只支持到 20.04。脚本把这个对应关系内置进去了相当于帮你挡掉了一类很常见的错误。2.2 换源、密钥、依赖三件事的先后顺序有讲究脚本内部做的事情拆开看主要三块。第一块是换源。它会把/etc/apt/sources.list里的 Ubuntu 主源替换成国内镜像同时把 ROS 自己的源也指向国内镜像。这里有个细节换源必须在导入密钥之前或者同时做因为密钥和源是需要配对的。如果你的 deb 行里写的是signed-by/usr/share/keyrings/ros-archive-keyring.gpg但密钥文件没下来apt 会直接拒绝这个源。第二块是密钥。脚本会把 ROS 的 GPG 公钥下载并放到指定位置然后确认文件大小正常。有些版本还会做一次apt-key的兼容处理。第三块是依赖。安装主包之外脚本通常会顺带装上python3-colcon-common-extensionscolcon 构建工具、python3-rosdep、python3-vcstool这些开发必备组件。这些包在 ROS2 的工作流里是刚需但官方入门文档往往只在很靠后的章节才提到新手很容易漏。2.3 一键安装和官方 apt 安装装出来的东西一样吗这是很多人关心的问题脚本装的和我手动 apt 装的是不是同一个东西。答案是核心二进制包完全一样来源都是同一个 ROS 镜像仓库只是包的版本可能因为镜像同步时间略有差异。脚本做的事情本质上是「帮你执行 apt 命令」它不会引入第三方修改过的 ROS 二进制。真正的区别在于周边配置对比项官方手动安装一键脚本安装ROS 二进制包官方源同一官方源国内镜像apt 源地址需手动配置脚本自动写入国内镜像GPG 密钥需手动下载脚本自动处理rosdep 初始化常失败用国内替代方案环境变量手动写 .bashrc脚本可代写可重复性依赖个人记录一条命令重跑需要说明的是rosdep 这块脚本用的是国内的替代实现。因为原版 rosdep 的索引托管在境外国内访问不稳定社区做了个叫 rosdepc 的版本接口和命令基本一致只是把索引源换成了国内地址用rosdepc init和rosdepc update代替原命令即可。功能上覆盖了绝大多数常见依赖少数冷门包可能需要手动补。提示如果你所在的环境完全无法访问境外地址用国内替代版的 rosdep 是唯一可行的路径。但如果你的网络本身没问题用官方 rosdep 兼容性会更好两者不冲突可以都留着。3. Ubuntu 版本和 ROS 发行版的对应关系选错就白装3.1 三个主流 LTS 版本的适配清单这一块是安装前必须确认的第一件事我把它整理成表装之前对着看一下能省很多时间。Ubuntu 版本代号可用 ROS1可用 ROS2LTS建议18.04bionicMelodicDashing / Eloquent太老新项目不建议20.04focalNoeticFoxy学 ROS1 或老项目维护用22.04jammy无Humble当前最稳首选24.04noble无Jazzy新生态在补齐中Humble 是目前 ROS2 生态里支持最广的 LTS 版本文档、教程、第三方包基本都是围绕它写的。Jazzy 虽然更新但很多第三方功能包还没跟上如果你要跑机械臂、导航这类依赖较多的项目Humble 会更省心。ROS1 的情况比较特殊Noetic 已经是终点官方不再有新版本。如果你的项目是基于 ROS1 的比如很多老教程里的 turtlesim、navigation那就只能在 20.04 上装 Noetic或者用 Docker 隔离一个 20.04 环境。3.2 虚拟机、ARM 板子、WSL 的特殊注意点虚拟机装 ROS 是最常见的翻车场景。问题主要出在图形加速上RViz2 和 Gazebo 这类需要 OpenGL 的工具在 VMware 或 VirtualBox 里默认可能跑不起来表现是窗口全黑或者直接闪退。处理办法是在虚拟机的显示设置里勾选「加速 3D 图形」并把显存调到 128MB 以上。如果还是不行可以强制软件渲染export LIBGL_ALWAYS_SOFTWARE1代价是帧率会明显下降跑 Gazebo 会卡但至少能看到画面调试小场景够用。真要跑复杂仿真还是建议物理机装双系统或者用带显卡直通的环境。ARM 平台比如树莓派、Jetson上ROS 的 apt 包有一部分是预编译好的有一部分需要源码编译。一键脚本在 ARM 上不一定能完整跑通因为脚本里的很多包是给 x86_64 准备的。这类平台建议确认架构后再选安装方式必要的话用 Docker 镜像官方和社区都有针对 ARM 的镜像可用。WSL2 下装 ROS2 是可行的但有两个坑一是 WSL 默认不带完整的 systemd某些服务启动方式不一样二是 GUI 需要额外配置 X server。这两点在 WSLg 出现之后改善很多Windows 11 上基本开箱能用。4. 从裸机到 ros2 topic list 跑通的完整操作链路4.1 动手前的系统自检在跑任何脚本之前先花两分钟确认几件事。第一确认系统版本和架构lsb_release -a uname -m输出里主要是看Release是不是你预期的版本uname -m是不是x86_64。如果是aarch64那就要按 ARM 的思路处理。第二确认磁盘空间。ROS2 桌面版完整安装加上后续编译的工作空间建议至少留 30GB 空闲。df -h看一眼根分区。第三确认 apt 本身是健康的sudo apt update sudo apt upgrade -y这一步如果就报错先把 apt 的问题解决掉别急着跑 ROS 脚本。常见问题是之前换过源但格式写错或者有残留的第三方 PPA 冲突。跟 ROS 无关的报错先把它们清理干净。4.2 执行一键脚本的完整交互过程准备工作做完就可以跑脚本了wget http://fishros.com/install -O fishros . fishros注意前面那个点号它表示在当前 shell 里执行不是开子进程。这样脚本设置的某些环境变量才能影响到你当前的终端会话。跑起来之后会出现交互菜单大致流程是选择安装类型ROS 还是 ROS2脚本检测系统版本给出可选发行版选择是否更换系统源和 ROS 源选择是否安装 rosdep 替代版选择是否安装桌面版还是基础版这里有几个选择建议。换源如果是在国内网络环境选是如果系统源本来就是配置好的公司内网源选否避免把内网源覆盖掉。桌面版和基础版的区别在于桌面版带 RViz2、demo 节点、教程包基础版只有核心通信库。学习阶段选桌面版做精简部署的时候选基础版。整个安装过程视网络情况大概 10 到 30 分钟。中途 apt 会有大量输出滚动不用紧张只要不出现红色的E:开头错误就说明在正常推进。4.3 装完后的验证动作别跳过安装结束先做环境变量加载source /opt/ros/humble/setup.bash然后立刻验证ros2 topic list如果这条命令没有报command not found而是返回了/parameter_events和/rosout两个话题说明核心通信层已经跑起来了。这是最基本的健康检查。接下来做一个更完整的验证开两个终端。终端 A 跑发布者ros2 run demo_nodes_cpp talker终端 B 跑订阅者ros2 run demo_nodes_py listener如果终端 B 持续打印I heard: [Hello World: N]说明 C 和 Python 两套节点、话题通信、DDS 中间件全都是通的。这个测试比单看ros2 topic list更有说服力因为它实际验证了跨语言的消息传递。如果你装的是 ROS1 Noetic验证方式换成roscore # 终端 A rosrun turtlesim turtlesim_node # 终端 B rosrun turtlesim turtle_teleop_key # 终端 C终端 C 里用方向键能控制小乌龟移动就说明 ROS1 环境完整可用。注意turtlesim 默认在 ROS 的turtlesim包里一键脚本装的桌面版会包含它。如果提示找不到包说明装的是基础版需要补装ros-noetic-turtlesim或对应的 ROS2 版本。4.4 那行 source 到底该放哪这是个小细节但踩的人特别多。source /opt/ros/humble/setup.bash只对当前终端有效新开一个终端就失效了。所以标准做法是写进~/.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc但这里有个进阶点如果你后面建了自己的工作空间工作空间的setup.bash也要 source而且顺序不能反。正确顺序是先 source 系统的再 source 工作空间的source /opt/ros/humble/setup.bash source ~/ros2_ws/install/setup.bash原因是工作空间的 setup 脚本会基于当前已加载的环境做叠加如果系统的没先加载工作空间里的某些变量就会缺。ROS2 的工作空间 setup 脚本内部其实会自动去 source 系统的那份所以一般不会出错但理解这个叠加关系对排查环境问题很有帮助。另外如果你同时在用 ROS1 和 ROS2千万不要把两个 source 都写进 .bashrc否则后面一个会覆盖前面一个的环境变量导致命令混乱。需要切换的时候手动 source 更安全。5. 装完之后最常遇到的四类问题5.1 包拉不下来先分清是 DNS 还是镜像问题apt update卡住或者报Could not resolve八成是 DNS 问题。先测一下ping -c 3 archive.ubuntu.com如果域名解析不了改/etc/resolv.conf加一个可用的 DNS 服务器。如果解析正常但连接超时那就是镜像地址的问题检查/etc/apt/sources.list和/etc/apt/sources.list.d/下的 ROS 源文件确认域名和路径写对了。还有一种情况是Hash Sum mismatch这是镜像同步延迟导致的通常换个镜像或者过几分钟重试就好。国内几个主流镜像同步频率都不低遇到这种问题不用慌。5.2 rosdep 报错的三种典型面孔rosdep 的问题基本集中在三类。第一类是初始化失败报cannot download default sources list。这是索引文件拉不下来用国内替代版 rosdepc 可以绕过pip install rosdepc sudo rosdepc init rosdepc update第二类是rosdep update时超时同样是网络问题多试几次或者换替代版。第三类是在工作空间里执行rosdep install --from-paths src --ignore-src -r -y时报某个包找不到。这通常是因为该包的依赖定义在较新的 rosdistro 里而你的 rosdep 索引比较旧。执行一次rosdepc update刷新索引基本能解决。如果还不行就手动装那个依赖rosdep 本身只是个自动化工具手动装不影响功能。5.3 虚拟机里的 RViz2 和 Gazebo 打不开这个问题前面提过一半这里展开说。表现是启动 RViz2 后窗口一片黑或者 Gazebo 启动到一半崩溃终端里可能有libGL error: failed to create drawable或者Segmentation fault。排查顺序是这样先在虚拟机设置里确认 3D 加速已开启显存够大。然后测试 OpenGL 是否可用glxinfo | grep OpenGL renderer如果提示 glxinfo 未安装先sudo apt install mesa-utils。输出里如果显示的是llvmpipe或者softpipe说明在用软件渲染性能会差但功能正常。如果直接报错连不上说明 3D 加速没生效。实在搞不定的时候用软件渲染强制启动export LIBGL_ALWAYS_SOFTWARE1 rviz2另外 Gazebo 对内存要求比较高虚拟机建议分配 4GB 以上内存否则仿真场景稍微复杂一点就会被 OOM Killer 干掉。5.4 中文输入法和终端环境的冲突这是个容易被忽略但很烦的问题。装了 fcitx 或 ibus 之后某些终端里中文输入不工作或者反过来终端里能输入中文但 Qt 应用里不行。根因在于环境变量。GTK 程序、Qt 程序、XIM 走的是不同的输入法模块需要分别设置export GTK_IM_MODULEfcitx export QT_IM_MODULEfcitx export XMODIFIERSimfcitx这三行写进~/.bashrc或者~/.profile。注意如果你用的是 ROS2 的 rqt 这类基于 Qt 的工具QT_IM_MODULE必须设对否则界面里中文全是方框。还有一个更隐蔽的问题某些版本的 fcitx 和 ROS 的某些库在环境变量上会打架导致ros2命令在设置了输入法变量之后启动变慢。这种情况下可以把输入法变量放到~/.xprofile而不是.bashrc只在图形会话启动时设置一次避免影响每个终端。6. 一键脚本覆盖不到的场景怎么自己补6.1 需要指定版本或者离线安装的时候一键脚本默认装的是它认为「最合适」的版本。如果你有特定版本需求比如项目锁定在某个小版本上脚本给的未必对。这种情况下就得回到 apt 手动指定apt-cache madison ros-humble-desktop sudo apt install ros-humble-desktop0.10.0-1jammy.20230815.000000-0版本号通过apt-cache madison查格式是版本号-发布次数-代号。这种方式适合需要精确复现环境的场景。离线安装是另一个需求。工厂产线或者内网机器上没法连外网。做法是在一台能联网的同版本机器上把 deb 包全部下载下来apt-get install --download-only ros-humble-desktop包会落在/var/cache/apt/archives/拷到目标机器上dpkg -i *.deb安装。注意依赖顺序和版本一致性实操上更稳的办法是用apt-offline这类工具生成依赖清单。6.2 Docker 方案环境隔离的另一种选择如果你的主机系统版本不合适或者不想把系统搞乱Docker 是很干净的方案。官方的 ROS 镜像质量很高docker run -it --rm --network host osrf/ros:humble-desktop几个关键参数说明一下。--network host让容器直接用宿主网络这样 ROS 的 DDS 通信才能正常跨容器/跨主机发现节点用默认的 bridge 网络会有一堆通信问题。如果需要图形界面还要加-e DISPLAY$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix并在宿主机执行xhost local:docker授权。如果是外接硬件比如通过 USB 连接的机械臂、串口设备还要加--device /dev/ttyUSB0把设备映射进去。Docker 方案的缺点是硬件访问和 GPU 直通配置起来麻烦优点是环境隔离彻底删了容器什么都不留。我一般用它来快速验证不同 ROS 版本的兼容性正式开发还是用宿主机。6.3 Micro-ROS 和 ESP32 这类扩展组件ROS2 生态往下延伸会碰到微控制器这一层。Micro-ROS 让 MCU 也能作为 ROS2 节点参与通信常见的是 ESP32 加 Micro-ROS 的组合。这部分一键脚本一般不管需要自己搭。基本流程是宿主机装micro_ros_agentMCU 端用 PlatformIO 或者 Arduino 环境编译带 Micro-ROS 库的固件两边通过串口或 UDP 对接。宿主机侧sudo apt install ros-humble-micro-ros-agent ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0MCU 侧需要在开发环境里引入 micro_ros 相关库配置传输方式串口还是 WiFi然后编译烧录。这一步的坑主要在版本匹配上——micro_ros 的库版本要和 ROS2 发行版对应Humble 对应的是特定版本的 micro_ros 库版本不对会在握手阶段失败报出来的错误信息还很不直观。另一个常见问题是串口权限。普通用户默认没权限访问/dev/ttyUSB0需要把自己加进 dialout 组sudo usermod -aG dialout $USER加完要重新登录才生效很多人加完立刻测试发现还是不行就是因为没重登。工作空间这块标准的 ROS2 工作空间创建流程是这样mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src # 把功能包放进来或者用 git clone cd ~/ros2_ws rosdepc install --from-paths src --ignore-src -r -y colcon build --symlink-install source install/setup.bash--symlink-install这个参数值得说一下它让安装目录里的文件用软链接指向源码改 Python 脚本和配置文件之后不用重新 build 就能生效。C 代码还是得重新编译但省掉 Python 那部分的重建时间日常开发体验提升明显。7. 几个我自己踩过之后才明白的点环境变量污染这件事我是吃过亏才重视的。有段时间我在.bashrc里同时 source 了 ROS1 和 ROS2结果rosrun和ros2 run交替失效排查了大半天才发现是两个环境的后台变量互相覆盖。现在的做法是写个小函数手动切换ros1() { source /opt/ros/noetic/setup.bash; } ros2() { source /opt/ros/humble/setup.bash; }需要哪个就敲哪个干净利落。另一个体会是关于镜像的选择。不同镜像站的同步策略不一样有的同步快但偶尔缺包有的全但延迟高。我的习惯是配两个源一个主用一个备用主用出问题的时候临时切过去比现找地址快得多。还有一点一键脚本虽然方便但别把它当成黑盒。第一次装的时候我建议你把脚本执行过程中的关键命令记下来特别是它改了哪些文件、写了哪些源地址。这样后面出问题的时候你至少知道从哪查起而不是只能重跑脚本。重装系统的时候你手里有这份记录手动装也就是十分钟的事。Docker 镜像也可以提前拉下来存着。docker pull osrf/ros:humble-desktop之后用docker save导出成 tar 文件内网机器上docker load直接导入比现下快很多也不受网络波动影响。写到这里差不多了。ROS 的环境搭建说到底是个体力活但它值得你花时间把原理搞明白因为后面调试节点通信、排查 DDS 发现失败、处理多机通信的时候用的还是同一套知识。一键脚本帮你省掉的是机械重复的部分省不掉的是理解。