ROS安装卡顿？三步换清华源实操指南，apt/rosdep全加速

ROS安装卡顿？三步换清华源实操指南，apt/rosdep全加速

发布时间：2026/9/30 1:25:25
ROS安装卡顿？三步换清华源实操指南，apt/rosdep全加速 做ROS开发的人应该都有过这种经历一条apt update下去卡在packages.ros.org上不动速度显示几KB每秒运气好等十几分钟勉强跑完运气不好直接超时断连。更折磨的是好不容易开始装ros-noetic-desktop-full又因为某个依赖从官方源拉不下来整个安装进程推到重来。后来我把ROS安装配置为清华源镜像之后这个问题基本就消失了不管apt源、ROS软件源还是rosdep索引全部走清华镜像下载速度和稳定性都有质的变化。这篇就把我实际操作的完整方法步骤写清楚包括Ubuntu系统apt源、ROS本体源、rosdep初始化这三层分别怎么换到清华源以及在这个过程中我踩过的大大小小的坑。无论你是刚入门ROS的新手还是被安装折磨过几次的老手照着这套流程走应该能省下不少时间。1. 为什么ROS装到一半总卡住换源的底层逻辑1.1 官方源的访问痛点是每个新手都躲不掉的坑ROS安装之所以经常卡住核心瓶颈并不在ROS本身而是在于它默认使用的软件源服务器。ROS官方默认将软件包发布在packages.ros.org而系统依赖则来自Ubuntu原生的archive.ubuntu.com这两个域名在我们这边的网络环境下访问速度非常不稳定。具体表现也很典型apt update阶段会长时间停留在“Reading package lists... Done”之前的某个百分比或者干脆报Connection timed out。有些时候源能连上但下载速度惨不忍睹一个几百MB的desktop-full包要拖一两个小时。这还不是最痛苦的最痛苦的是rosdep update阶段它默认要从GitHub上的ros/rosdistro仓库拉取索引文件而GitHub的访问稳定性大家心里都有数经常是重试三次、失败三次。所以很多人装ROS装到最后其实不是不会装而是被网络问题反复折腾到心态爆炸。解决思路也非常直接把ROS安装过程中依赖的外部服务全部换成国内高校提供的镜像源而清华源mirrors.tuna.tsinghua.edu.cn是目前覆盖最全、更新最快、文档最完善的选择之一。1.2 清华源镜像到底给ROS加速了什么很多教程只告诉你“把源换成清华就行”但没讲清楚清华源到底替我们解决了哪些环节导致你换了一半发现还是卡。我再拆得细一点ROS从安装到初始化其实涉及三层独立的网络请求第一层是Ubuntu系统本身的apt源也就是archive.ubuntu.com。这一层如果不换后面安装ROS依赖的底层库比如boost、console_bridge、python3-catkin-pkg等仍然走官方源速度还是慢。第二层是ROS软件包源也就是packages.ros.org。这一层负责提供ros-noetic-*这一系列deb包是安装ROS本体的关键。清华源提供了对应的/ros/ubuntu镜像可以完整替代官方源。第三层是rosdep使用的索引源默认指向raw.githubusercontent.com。这一层很多人会忽略结果ROS主体装好了却在rosdep update这一步反复失败。清华源对这个三层都有对应镜像/ubuntu/、/ros/ubuntu、以及/rosdistro/。把这三层全部切到清华源之后从系统依赖到ROS本体再到rosdep索引整个过程才算是真正意义的“全链路加速”。2. 换源前的环境核对与备份习惯2.1 先确认你的ROS版本和Ubuntu版本对应关系动手换源之前先确定自己的Ubuntu版本和ROS版本是否匹配。这是个看起来简单但实际很容易出错的点因为ROS的deb包是严格按Ubuntu发行版代号命名的你如果把Noetic的源写进Ubuntu 22.04里apt会直接报404或者版本冲突。常见对应关系整理如下ROS版本对应Ubuntu版本系统代号ROS 1 NoeticUbuntu 20.04focalROS 1 MelodicUbuntu 18.04bionicROS 2 FoxyUbuntu 20.04focalROS 2 HumbleUbuntu 22.04jammy我自己的主力版本是ROS 1 Noetic装在一台Ubuntu 20.04系统上所以下面主体步骤以Noetic为例。如果你用的是其他版本只需要把源地址里的focal换成对应代号即可整体流程完全一致。ROS 2 Humble我会在后面的小节单独补充因为它的密钥管理方式和ROS 1有些区别。2.2 换源前先备份很多教程都不会教你的安全操作换源本质上就是修改apt的软件源列表虽然不是什么高风险操作但万一你在网上复制到了一段写错的源内容我见过把focal写成folcal的系统就再也无法正常更新了。所以我一直保持一个习惯任何涉及系统配置文件的修改先备份。备份命令很简单sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo cp -r /etc/apt/sources.list.d /etc/apt/sources.list.d.bak第一行备份主源文件第二行备份整个源目录。万一后面改出问题直接恢复备份就行。另外建议在改完源并确认apt update成功之前不要删除这些备份文件宁可等所有ROS包都装好后确认系统稳定了再清理。这里还要提醒一句sources.list.d目录里可能还有其他已存在的源文件尤其是你之前装过某些第三方软件时。我们替换清华源时不需要动那些第三方源的配置只需确保我们新添加的ROS源文件命名清晰、不冲突即可。3. 清华源镜像配置与ROS安装完整实操3.1 第一步把Ubuntu系统apt源换成清华源虽然这一步不直接属于“ROS安装配置”但强烈建议先做。原因前面也说了ROS的依赖库非常庞大如果系统apt源还走官方源后续安装时会频繁卡顿。先查看当前系统代号lsb_release -sc我这边输出是focal。然后编辑主源文件sudo nano /etc/apt/sources.list将文件内容替换为清华源以focal为例# 默认注释了源码镜像以提高 apt update 速度如有需要可自行取消注释 deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal main restricted universe multiverse # deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-updates main restricted universe multiverse # deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-updates main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-backports main restricted universe multiverse # deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-backports main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-security main restricted universe multiverse # deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-security main restricted universe multiverse如果你用的是Ubuntu 22.04把focal全部替换为jammy即可。保存退出后执行sudo apt update这时候你会看到apt的速度有了明显提升。如果输出里没有报错说明系统源已经切换成功。3.2 第二步添加ROS的清华软件源和GPG密钥系统源搞定之后接下来添加ROS软件包源。这一步要做的就是告诉apt除了Ubuntu官方仓库我还要从清华的ROS镜像仓库里找ros-noetic-*包。先安装一些必要的工具sudo apt install curl gnupg lsb-release然后添加ROS仓库的GPG公钥。ROS 1 Noetic的官方公钥指纹是C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654添加命令如下sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654这条命令会通过Ubuntu的密钥服务器导入ROS官方签名。执行完毕如果输出OK说明密钥导入成功。接着创建ROS源列表文件sudo sh -c echo deb https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu $(lsb_release -sc) main /etc/apt/sources.list.d/ros1.list这里用lsb_release -sc动态获取系统代号比我手动写死focal更稳妥换机器部署时不容易敲错。写完后可以查看确认一下cat /etc/apt/sources.list.d/ros1.list应该输出deb https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu focal main这类内容。再次执行sudo apt update这时候apt的输出里应该能看到来自mirrors.tuna.tsinghua.edu.cn/ros/ubuntu的索引信息说明ROS源已经生效。3.3 第三步安装ROS本体以Noetic版本为例源配好之后安装反而不是什么难事了。如果你只是想体验ROS基本功能可以装精简版sudo apt install ros-noetic-ros-base如果是准备正经做机器人开发、要跑Gazebo和Rviz强烈建议直接装完整版sudo apt install ros-noetic-desktop-fulldesktop-full包含ROS、rqt、RViz、机器人通用库、2D/3D仿真器以及导航、感知相关的功能包体积大概在两三个GB左右但在清华源的加持下即使普通宽带也能在十几分钟内装完。我实测从配置完源到安装结束最快一次不到十五分钟同一台机器之前用官方源装到一半直接超时回滚。安装过程会自动拉取依赖如果中途报依赖冲突先执行sudo apt --fix-broken install让apt自动修复依赖关系后再重新安装。3.4 如果装的是ROS 2 Humble源要这样配ROS 2 Humble在源配置思路上和ROS 1类似但有两处细节不同。第一它使用的是/ros2/ubuntu这个仓库路径第二它的GPG密钥文件已经不再推荐用apt-key命令而是建议直接下载key文件到系统keyring中。先添加ROS 2仓库sudo sh -c echo deb https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(lsb_release -sc) main /etc/apt/sources.list.d/ros2.list然后添加密钥。官方文档的做法是从GitHub下载ros.key但这一步实际执行时经常因为网络问题失败。如果你的网络能访问直接执行sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg如果下载不顺利多试几次或者找一台已经装好ROS2的机器拷贝这个key文件过来。拿到key文件后需要在源列表里显式指定使用这个keyringdeb [signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu jammy main从ROS 2 Foxy后期版本开始这种方法比apt-key更符合新版apt的安全策略。改完执行sudo apt update确认没有NO_PUBKEY错误后安装Humblesudo apt install ros-humble-desktop-full4. rosdep的清华源镜像加速初始化4.1 rosdep究竟是干什么的为什么绕不开很多新手不理解ROS本体都装好了为什么还要跑一遍rosdep init和rosdep update简单说rosdep是ROS的依赖解析工具。你在自己的工作空间里写的功能包package.xml里可能会声明一堆系统级依赖比如OpenCV、PCL、Eigen这些库rosdep会去查这些依赖在Ubuntu里对应哪个apt包然后自动帮你安装。rosdep init负责生成初始配置文件rosdep update负责把rosdistro索引同步到本地。问题在于这两个操作默认都要从GitHub上的ros/rosdistro仓库拉取数据网络不好时基本必挂。清华源对rosdistro也提供了镜像这一步同样可以换成清华源来加速。4.2 用清华rosdistro镜像配置rosdep的两种方式第一步先安装rosdep工具如果你装的是desktop-full一般已经自带没有就手动装sudo apt install python3-rosdep然后处理初始化。我整理了两套方案第一套适合网络偶尔不稳定但能通的情况第二套是更稳妥的兜底方案。方案一正常init然后替换URL先正常执行sudo rosdep init如果这条命令成功了会自动生成/etc/ros/rosdep/sources.list.d/20-default.list文件。接下来把文件里的GitHub地址替换成清华镜像地址sudo sed -i s|https://raw.githubusercontent.com/ros/rosdistro/master|https://mirrors.tuna.tsinghua.edu.cn/rosdistro|g /etc/ros/rosdep/sources.list.d/20-default.list然后查看一下替换结果cat /etc/ros/rosdep/sources.list.d/20-default.list每行yaml地址应该都指向mirrors.tuna.tsinghua.edu.cn/rosdistro了。方案二init失败时手动创建配置文件如果sudo rosdep init一直卡住或报错直接手动创建目录和文件sudo mkdir -p /etc/ros/rosdep/sources.list.d/ sudo tee /etc/ros/rosdep/sources.list.d/20-default.list EOF # os-specific listings first yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/osx-homebrew.yaml osx # generic yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/base.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/python.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/ruby.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/pip.yaml # older distributions (sha-256 only) yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/jade.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/indigo.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/kinetic.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/melodic.yaml # gbpdistro/rosdistro-like files yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/snowball.yaml yaml https://mirrors.tuna.tsinghua.edu.cn/rosdistro/rosdep/rolling.yaml EOF这两套方案任选其一目的都是让rosdep在后续读取索引时访问清华镜像而不是GitHub。接下来设置环境变量ROSDISTRO_INDEX_URL让rosdep在读取索引时也优先走清华镜像。编辑~/.bashrcecho export ROSDISTRO_INDEX_URLhttps://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yaml ~/.bashrc source ~/.bashrc最后执行updaterosdep update正常情况下速度会非常快几秒钟就能完成。以后每次在新环境配ROS这套组合拳都能帮你绕开最常见的rosdep失败问题。4.3 source环境变量与安装验证rosdep搞定了最后一步是配置用户环境变量。很多教程只让你写一行source /opt/ros/noetic/setup.bash到bashrc里确实够用但我还是建议把完整体验补全echo source /opt/ros/noetic/setup.bash ~/.bashrc echo source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash ~/.bashrc # ROS2才需要 source ~/.bashrc验证是否安装成功最简单的办法是开三个终端分别测试roscore新开终端rosrun turtlesim turtlesim_node再开一个终端rosrun turtlesim turtle_teleop_key如果小乌龟界面能打开并且能用键盘控制它移动说明ROS主程序、话题通信环境全部正常。这套验证方式比单纯看rosversion -d更直观能确认节点通信管道没有问题。5. 实操高频问题与排查速查表5.1 GPG密钥添加失败apt update报NO_PUBKEY这是新手最容易卡住的环节。执行sudo apt update时如果输出类似The following signatures couldnt be verified because the public key is not available: NO_PUBKEY ...说明ROS源已经写好但系统没有导入对应的GPG公钥。这种情况下重新执行一遍sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654如果这条命令报超时可以换一种方式把密钥服务器改成keyserver.ubuntu.com的443端口sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:443 --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654如果还是不行就去清华源ROS镜像页面手动下载公钥文件再导入。注意ROS 2的密钥处理方式不同前面3.4小节已经说过使用ros-archive-keyring.gpg即可。5.2 rosdep init或update一直卡住rosdep init卡死的根源基本就是访问GitHub失败这时候不用反复重试直接走4.2节里的方案二手动创建20-default.list。rosdep update卡住的话优先检查/etc/ros/rosdep/sources.list.d/20-default.list里的URL是否已经替换为清华镜像以及ROSDISTRO_INDEX_URL环境变量是否生效。另外有个小习惯值得培养rosdep update执行完后如果后面新增了功能包又提示缺少依赖不需要重新执行整个流程直接rosdep update rosdep install --from-paths src --ignore-src -r -y后者会只解析你当前工作空间的依赖速度更快也不容易误伤全局环境。5.3 apt update报错或403拒绝访问如果在替换清华源后执行apt update出现来自mirrors.tuna.tsinghua.edu.cn的403错误大概率是源地址路径写错了。注意区分Ubuntu系统源是https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ROS1源是https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntuROS2源是https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu这三个路径不一样混用就会404或403。另外如果之前尝试过其他镜像源可能残留了损坏的apt缓存先清理再重试sudo rm -rf /var/lib/apt/lists/* sudo apt clean sudo apt update5.4 依赖冲突和安装一半失败装desktop-full时偶尔会遇到某个包版本冲突apt提示“下列软件包有未满足的依赖关系”。这时候不要急着强制覆盖先运行sudo apt --fix-broken install让apt自己尝试修复。大多数情况下会自动补齐缺失依赖或调整版本组合。如果修复后仍然失败检查是不是混合添加了ROS1和ROS2的源不要在同一系统里让/ros/ubuntu和/ros2/ubuntu同时出现很容易把apt的依赖解析搅浑。下面把这个环节的高频问题整理成一张速查表现象大概率原因快速处理apt update卡住系统apt源还是官方源换成清华/ubuntu/源NO_PUBKEY错误ROS密钥未导入重新执行apt-key并指定keyserverrosdep init卡住默认访问GitHub失败手动创建20-default.listrosdep update慢索引URL没替换sed替换为mirrors.tuna.tsinghua.edu.cn/rosdistro403拒绝访问源路径写错检查/ros/ubuntu与/ubuntu/区别依赖冲突多个ROS源混合清理source list只保留一个ROS发行版6. 给新手的三条实用建议6.1 想图省事也可以用一键脚本但要知道它做了什么现在网上流传最多的“鱼香ROS一键安装”脚本确实能在很大程度上降低ROS的安装门槛它内部也会把源切换到国内镜像某种程度上和手动换清华源的逻辑是一致的。如果你被各种手动步骤折腾得头大可以试一下wget http://fishros.com/install -O fishros . fishros但我的建议是一键脚本可以用但千万别只依赖它。至少要把源文件路径、密钥添加方式、rosdep配置位置这三样搞清楚因为后面你自己建工作空间、装第三方功能包时还是会经常面对apt和rosdep的各种问题到时候再回来看这篇教程你会理解得更快。6.2 换源之后养成两个好习惯第一个习惯每次装完ROS第一时间确认/etc/apt/sources.list.d/目录下的源文件含义。建议用有辨识度的文件名比如ros1.list、ros2.list避免以后忘了哪个文件对应哪个源。第二个习惯定期清理apt缓存。换源后下载速度快系统里会积累大量deb安装包缓存长年累月能占好几个GB。建议偶尔执行sudo apt autoremove sudo apt autoclean这两个命令不会影响已安装的软件只是清理无用的依赖和缓存文件。6.3 装完之后别急着写功能包先跑通一个“最小闭环”ROS安装完成只能算走出第一步我更建议你花十分钟跑一遍turtlesim或者用roslaunch启动一个简单例程确认话题、服务、参数服务器这些基础通信都正常。很多人在环境没跑通的情况下就直接开始写自己的功能包出了问题根本分不清是代码问题还是环境问题排查起来非常痛苦。我个人的习惯是装完环境后先跑一次完整的“建工作空间—编译空包—用rosrun运行”流程确认整个工具链是通的再开始正式开发。这套习惯帮我少踩了很多莫名其妙的坑也推荐你试试。