1. 先搞明白 rosdep update 究竟在下载什么rosdep update卡住然后抛 timeout几乎是每个在国内网络环境下装机的人都要过的一关。我第一次遇到的时候是在一台刚装完 ROS 的工控机上rosdep init顺利跑完rosdep update跑到 reading in sources list data 那一行就一动不动等了四五分钟甩出一串urlopen error timed out。当时以为是 rosdep 装坏了重装了三遍后来才明白 —— 这不是软件问题是它在按顺序去抓一堆远程文件而其中某几个地址在当前网络下慢到超时。先把话说清楚rosdep是 ROS 体系里的系统依赖解析器。你在package.xml里写dependlibeigen3-dev/depend真正知道这台 Ubuntu 上该装libeigen3-dev还是eigen3-dev的就是 rosdep 背后那张巨大的映射表。这张表不在你本地得从远程拉下来缓存到~/.ros/rosdep/里rosdep update干的就是这件事。适合看这篇内容的人分三类刚装完 ROS 想跑rosdep install的新手、要在内网批量部署 ROS 环境的运维、以及在做 CI 流水线镜像构建时被这一步堵住的工程师。不管你是哪一类下面这套排查加解决的组合拳都能直接用。1.1 init、update、install 三个子命令各管什么很多人把这三个命令混着用出了问题也说不清卡在哪。其实分工非常清晰sudo rosdep init只做一件事 —— 把一份默认的源列表写到/etc/ros/rosdep/sources.list.d/20-default.list。这个文件里全是地址不是真正的数据。它自己也会去下载一次默认列表所以这一步也可能 timeout。rosdep update读上面那个列表把列表里每一行指向的 yaml 文件抓下来解析、合并、缓存到~/.ros/rosdep/sources.cache和~/.ros/rosdep/sources.cache/下的分片文件里。这一步要发的请求最多也最容易挂。rosdep install --from-paths src --ignore-src -r -y读本地缓存把当前工作空间里所有的依赖名翻译成 apt 包名然后交给 apt 去装。这一步不联网抓 rosdep 数据只走 apt 源。理解这个分层极其重要因为后面我给的离线方案本质上就是「让 init 和 update 都去读本地文件」而 install 阶段你什么都不用改。1.2 update 阶段实际发出的请求链路把这条链路拆开看你就知道 timeout 到底断在哪个环节了。以较新的 rosdep0.20 以上为例它大致会依次做这几件事读/etc/ros/rosdep/sources.list.d/*.list拿到所有源地址去拉 rosdistro 的索引文件index-v4.yaml老版本是index.yaml。这个文件里记录了每个 ROS 发行版的名字、状态以及它对应的distribution.yaml相对路径对每个发行版去拉releases/targets.yaml走 rep3 机制的版本会走这一步和各个distribution.yaml按sources.list里列出的yaml行逐个拉base.yaml、python.yaml、ruby.yaml这些动辄几百 KB 的映射文件如果有gbpdistro行比如 fuerte 这种老发行版还要再拉一份对应的 yaml。一个关键细节所有这些地址绝大多数都指向同一个域名下的 raw 内容服务。也就是说你的成败集中在一两个域名的连通性上而不是分散在几十个不同的站点。这就是为什么有时候你感觉「网络没问题啊网页都能开」但 rosdep 就是过不去 —— 它要去的地方恰好就是慢的那几个。1.3 为什么报的是 timeout 而不是 404这个区分很有价值。404 说明地址写错了、文件被删了、分支改名了timeout 说明TCP 连接建立起来了但数据迟迟不来或者连握手阶段都超时。前者你要改配置后者你要改网络路径或绕开网络。还有一种容易被误判的情况报错里出现Connection reset by peer或者Remote end closed connection without response。这通常不是超时而是链路上有设备在干扰长连接。遇到这种单纯调大 timeout 是没用的必须走「换源」或者「完全离线」这两条路。注意不要在没看清报错类型的情况下就去改 timeout 参数。把urlopen error timed out和Connection reset当成一回事是最常见的误诊。2. 定位问题别急着改代码先让它把话说清楚我见过太多人一上来就去搜「rosdep update 超时怎么改源码」然后照着某个三年前的帖子把 python 文件改得乱七八糟最后连rosdep本身都 import 不进去了。正确顺序是先让命令吐出足够的信息确认卡在哪一步、哪一条地址再决定用哪种方案。2.1 打开 verbose让它把每次请求都打出来rosdep 是 python 写的--verbose会把中间过程全打出来。别省这一行命令rosdep update --verbose 21 | tee /tmp/rosdep_update.log跑完之后看两样东西日志最后停在哪一行、以及那一行对应的是哪个域名。我一般直接用 grep 把地址捞出来grep -oE https?://[^ ] /tmp/rosdep_update.log | sort -u这一条命令能把这次 update 尝试访问过的所有地址列出来非常直观。你会看到它们的域名高度集中这时候问题就从「rosdep 报错了」变成了「某个具体域名的可达性如何」排查范围一下子缩小了。如果 verbose 的输出量大到看不清最后停在哪儿用timeout给整条命令加个上限超时后看日志尾部timeout 120 rosdep update --verbose 21 | tail -n 402.2 用 curl 单独验证某一个地址把上面捞出来的地址挑一个用 curl 做一次只测连通性、不测内容的探测curl -4 -I --connect-timeout 8 --max-time 20 \ https://raw.githubusercontent.com/ros/rosdistro/master/index-v4.yaml几个参数的含义值得说清楚因为它们决定了你测出来的结论是否可信-4强制走 IPv4。国内不少环境 IPv6 是「有地址但出不去」的状态不强制 v4 的话curl 会先尝试 IPv6、卡满超时再回落测出来的时间完全是假的。-I只发 HEAD 请求不下载正文快。--connect-timeout 8握手阶段最多等 8 秒这也是判断「是 DNS 慢、握手慢、还是传输慢」的关键。--max-time 20整个请求的硬上限。如果connect阶段就超了那是 DNS 或者 TCP 层的问题如果 connect 很快但总时间打满那是传输阶段被限速。这两种情况对应的解法完全不同一个可能只需要换个 DNS另一个必须换数据源。顺手也可以看一眼 DNS 解析结果判断有没有被解析到奇怪的地址getent hosts raw.githubusercontent.com如果解析出来的地址明显不对或者干脆解析不出来那问题在 DNS 层不在 rosdep。2.3 报错信息对照表我把这些年遇到的、以及同行反馈过的典型报错整理成了一张表对着看能省很多时间。报错关键词实际含义优先尝试的方案urlopen error timed out握手或传输阶段超时方案一调超时、方案二换源Connection reset by peer链路被中途打断长连接维持不住方案二、方案三离线Remote end closed connection without response服务端或中间设备主动断开方案三离线[Errno -3] Temporary failure in name resolutionDNS 解析失败检查/etc/resolv.conf换 DNS[Errno 101] Network is unreachable根本没有出网路由检查网卡、网关或直接用离线方案SSL: CERTIFICATE_VERIFY_FAILED证书校验失败常出现在有中间设备的网络先确认系统时间正确再考虑本地源方案ERROR: unable to process source [...yaml]地址拿到了但内容解析失败检查文件是否被截断重跑一次提示SSL: CERTIFICATE_VERIFY_FAILED这个消息里九成情况下第一步应该检查系统时间。虚拟机快照恢复后时间错乱会让证书看起来「过期」很多人在这里绕了很久。3. 方案一调大超时与重试最省事的止血如果你的网络只是「慢」而不是「断」那这个方案是最低成本的。它的思路是把 rosdep 内部的超时阈值放大再给它加一层自动重试。慢就慢点能跑完就行。3.1 三个关键文件和需要改的地方rosdep 的网络请求最终都落到 python 的urlopen或者 requests上而很多调用点没有显式指定 timeout用的是系统默认值。默认值在某些 python 版本下短得离谱网络稍抖一下就抛异常。你要找的文件通常在 site-packages 目录下具体路径随安装方式和 python 版本变化先用python3 -c把它定位出来python3 -c import rosdep2, rosdistro, os; print(os.path.dirname(rosdep2.__file__)); print(os.path.dirname(rosdistro.__file__))拿到目录之后重点看这几个文件里的urlopen(调用rosdistro/__init__.pyget_index函数里拉索引文件的地方rosdep2/sources_list.py下载sources.list里各个 yaml 的地方rosdep2/gbpdistro_support.py处理gbpdistro类型源的地方rosdep2/rep3.py走 rep3 机制时拉 targets 文件的地方。改法就是给每个没有 timeout 的调用补上参数。手动改容易漏我一般用一个短脚本批量处理先备份再改import pathlib, re, shutil targets [ rosdistro/__init__.py, rosdep2/sources_list.py, rosdep2/gbpdistro_support.py, rosdep2/rep3.py, ] base pathlib.Path(/usr/lib/python3/dist-packages) # 按上一步的实际路径替换 for rel in targets: p base / rel if not p.exists(): print(跳过不存在:, p) continue shutil.copy2(p, str(p) .bak) src p.read_text(encodingutf-8) # 只给单参数形式的 urlopen(x) 补 timeout已有 timeout 的不动 new, n re.subn(rurlopen\(\s*([^,()]?)\s*\), rurlopen(\1, timeout120), src) p.write_text(new, encodingutf-8) print(f{rel}: 替换 {n} 处)跑完检查一下没有语法错误python3 -c import rosdep2, rosdistro; print(import ok)打印出import ok就说明改动没破坏模块。然后重新跑rosdep update。3.2 加一层自动重试把偶发失败吃掉即使超时调大了链路抖动导致的偶发失败还是会有。与其盯着屏幕一次次手敲不如写个循环#!/usr/bin/env bash # retry_rosdep_update.sh set -u MAX30 for i in $(seq 1 $MAX); do echo 第 $i 次尝试 if rosdep update; then echo 第 $i 次成功 exit 0 fi sleep 3 done echo 连续 $MAX 次均失败请改用离线方案 exit 1这个脚本的价值在于rosdep update 实际是分多个步骤串行下载的每次重跑已经成功的部分有概率更快通过多试几次的成功率比单次高不少。我实测过几次在弱网环境下前二十次都失败、第二十三次突然全过就是运气好赶上了一段通畅的窗口期。3.3 这个方案的注意事项有三点必须提前说清楚否则你会踩坑。第一直接改 site-packages 里的文件是脆弱的。apt 升级 rosdep 或者重装系统包改动会被覆盖问题原封不动回来。所以我在脚本里强制留了.bak备份改坏了能一键还原for f in /usr/lib/python3/dist-packages/rosdep2/*.bak; do mv $f ${f%.bak} done第二用 pip 装的 rosdep 路径完全不同通常在~/.local/lib/python3.x/site-packages/下而且不需要 sudo。这也是我推荐在容器里用 pip 装 rosdep 的原因 —— 改起来不需要提权重建镜像时也干净。第三timeout 不是越大越好。设成 600 秒一次失败就要等十分钟重试三十次的脚本能跑五个小时。我一般设 60 到 120 秒这个区间既给了慢链路足够的容错又不至于让失败检测变得太迟钝。4. 方案二把索引源换成公共软件镜像站如果调超时也没用说明问题不是「慢」而是「那条路根本走不通或者极不稳定」。这时候最直接的思路是换一条走得更顺的路。好消息是rosdistro 的数据本身就是开源仓库内容国内多所高校和云厂商都做了公共镜像这些镜像站是正规的开源软件分发服务直接拿来用就行。4.1 ROSDISTRO_INDEX_URL 这个环境变量rosdep 支持通过环境变量覆盖索引地址这是整件事里最关键的一个开关。默认情况下索引地址指向上游的 raw 内容服务你把它改成镜像站上的对应文件地址整个下载链路就换了出口。export ROSDISTRO_INDEX_URLhttps://镜像站域名/rosdistro/index-v4.yaml rosdep update --verbose要注意两点老版本的 rosdep 用的是index.yaml而不是index-v4.yaml。判断方法很简单看rosdep update --verbose输出的第一个地址里写的是哪个文件名照着换成镜像站上同名的文件即可。这个环境变量是进程级的当前终端生效。想持久化就写进~/.bashrc或者在 Dockerfile 里用ENV声明。CI 环境里我更推荐在流水线脚本里显式 export避免隐式依赖 shell 初始化文件。4.2 镜像地址的选择与校验我一般会准备两三个候选用 curl 快速筛一遍谁快用谁for u in \ https://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yaml \ https://mirrors.ustc.edu.cn/rosdistro/index-v4.yaml ; do printf %-70s $u curl -4 -o /dev/null -s -w %{http_code} %{time_total}s\n \ --connect-timeout 6 --max-time 20 $u done输出里第一个数字是 HTTP 状态码200才算地址有效第二个是总耗时越小越好。看到404就说明该镜像站没有这个路径或者文件名不对换一个试。这一步绝对不能省。我见过很多帖子直接把某个地址写死结果时间一长镜像站目录结构调整了读者照着做全报 404然后开始怀疑自己的系统有问题。确认地址可用之后还要顺手验证内容是不是完整的 yaml避免镜像站返回一个半截文件或者错误页curl -4 -s --max-time 20 https://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yaml \ | head -n 5正常情况下你应该看到标准的 yaml 头部和distributions:字段。如果看到 HTML 标签说明这个路径返回的是网页而不是文件不能用。4.3 完整的换源操作步骤把上面几步串起来一套可直接复制的流程是这样# 1. 选出可用镜像写入环境变量临时生效 export ROSDISTRO_INDEX_URLhttps://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yaml # 2. 顺便把 sources.list 里的地址也换掉 sudo cp /etc/ros/rosdep/sources.list.d/20-default.list \ /etc/ros/rosdep/sources.list.d/20-default.list.bak 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 # 3. 清掉可能已经写坏的缓存避免旧数据干扰 rm -rf ~/.ros/rosdep/sources.cache # 4. 重新执行 rosdep update --verbose第 3 步容易被忽略但很重要。rosdep 的缓存是有状态的如果你上一次在下载中途失败缓存里可能留下不完整的文件下一次 update 有可能直接读了这个坏缓存然后报一个莫名其妙的解析错误。改完源地址就清缓存这是我反复验证过的最省事做法。注意sed里的分隔符我用了#而不是默认的/因为替换内容里包含大量斜杠用/做分隔符需要疯狂转义极易写错。5. 方案三完全离线把数据喂到本地前两个方案都有一个前提你至少能联通某个镜像站。但现实里有相当一部分场景是彻底不通的 —— 内网隔离的编译机、只允许白名单出网的构建环境、以及网络极其糟糕的现场设备。这种情况下唯一的出路是把 rosdistro 的整个仓库搬到本地让 rosdep 直接读文件。5.1 把 rosdistro 完整仓库拿到手关键在于要拿整个仓库而不是零散几个 yaml。因为索引文件里记录的是相对路径目录结构必须完整缺一个发行版目录就可能解析失败。最省事的办法是在一台能上网的机器上操作然后把结果拷过去mkdir -p /opt/ros-offline cd /opt/ros-offline git clone --depth 1 https://github.com/ros/rosdistro.git如果连这一步都不通就去公共镜像站或代码托管平台上找 rosdistro 的完整镜像仓库。这里同样建议先探测再克隆用git ls-remote花几秒钟确认地址存在比克隆到一半失败要划算得多git ls-remote --heads https://mirrors.tuna.tsinghua.edu.cn/git/rosdistro.git | head返回了分支列表说明这个仓库可用再执行git clone。克隆完确认几个关键文件在位ls /opt/ros-offline/rosdistro/index-v4.yaml \ /opt/ros-offline/rosdistro/rosdep/base.yaml \ /opt/ros-offline/rosdistro/noetic/distribution.yaml三个文件都在目录结构就是完整的。5.2 把 sources.list 和索引变量都指向本地路径这一步是整个离线方案的核心把所有https://地址替换成file://本地路径。先手工生成一份全新的 sources.list内容大致是下面这个样子发行版名字按你实际使用的替换# os-specific listings first yaml file:///opt/ros-offline/rosdistro/rosdep/osx-homebrew.yaml osx # generic yaml file:///opt/ros-offline/rosdistro/rosdep/base.yaml yaml file:///opt/ros-offline/rosdistro/rosdep/python.yaml yaml file:///opt/ros-offline/rosdistro/rosdep/ruby.yaml gbpdistro file:///opt/ros-offline/rosdistro/releases/fuerte.yaml fuerte写进去sudo mkdir -p /etc/ros/rosdep/sources.list.d sudo tee /etc/ros/rosdep/sources.list.d/20-default.list /dev/null EOF yaml file:///opt/ros-offline/rosdistro/rosdep/osx-homebrew.yaml osx yaml file:///opt/ros-offline/rosdistro/rosdep/base.yaml yaml file:///opt/ros-offline/rosdistro/rosdep/python.yaml yaml file:///opt/ros-offline/rosdistro/rosdep/ruby.yaml gbpdistro file:///opt/ros-offline/rosdistro/releases/fuerte.yaml fuerte EOF然后设置索引变量同样指向本地export ROSDISTRO_INDEX_URLfile:///opt/ros-offline/rosdistro/index-v4.yaml rosdep update正常情况下这次会秒过因为所有的读取都是磁盘操作。如果还是打印出 https 开头的地址说明你用的 rosdep 版本还在走 rep3 机制它内部硬编码了一个 targets 文件地址。处理办法是把那个文件也改成file://打开rosdep2/rep3.py找到那个被写死的地址常量替换成本地路径即可改完记得用python3 -c import rosdep2验证一下语法。5.3 验证、迁移与回滚离线跑通之后第一件事是验证结果真的可用别等到跑rosdep install才发现表是空的rosdep resolve python3-yaml rosdep resolve libeigen3-dev能正常输出 apt 包名比如python3-yaml、libeigen3-dev说明缓存里的映射表是有效的。第二件事也是我认为这套方案最有价值的地方把成果直接复制到其他机器让它们跳过整个 update 过程。你需要打包两个东西路径内容说明~/.ros/rosdep/sources.cache解析后的映射缓存核心数据必须带/etc/ros/rosdep/sources.list.d/20-default.list源列表定义使缓存与源一一对应tar czf rosdep-cache.tgz \ -C $HOME .ros/rosdep/sources.cache \ -C /etc/ros/rosdep sources.list.d/20-default.list新机器上解包到相同位置即可。这里有一个必须注意的前提缓存和源列表是绑定的。如果你在新机器上把20-default.list改成别的地址rosdep 会认为缓存失效并重新下载。所以要么两边完全一致要么目标机器也把 rosdistro 仓库放在同样的绝对路径下。回滚也很简单把备份的.bak换回来、删掉环境变量、清理缓存即可unset ROSDISTRO_INDEX_URL sudo mv /etc/ros/rosdep/sources.list.d/20-default.list.bak \ /etc/ros/rosdep/sources.list.d/20-default.list rm -rf ~/.ros/rosdep/sources.cache rosdep update6. 常见问题速查与踩坑实录方案讲完了接下来是更实用的部分 —— 这些年我和同事在各类环境里踩过的坑以及对应的处理方式。这些东西在官方文档里基本找不到但真遇到的时候能省下大半天。6.1 问题速查表现象最可能的原因处理方式换源后仍访问上游地址环境变量没生效或被别的脚本覆盖在命令前显式export用 envupdate 秒过但 resolve 报找不到包读了旧的坏缓存删掉~/.ros/rosdep/sources.cache重跑某一行 yaml 永远失败其他都正常该文件在镜像站上缺失把这一行暂时注释掉其余照常容器里改完重启就失效改动没写进镜像层在 Dockerfile 里ENV 复制文件而不是运行期手改多用户机器上有人跑有人不跑缓存是 per-user 的每个用户各自 update或者统一分发缓存--include-eol-distros后更慢多拉了一堆已停止维护的发行版数据只在确实需要老发行版时才加这个参数关于最后一行补充一句rosdep update --rosdistro noetic这种显式指定发行版的写法能显著减少一次 update 需要拉取的文件数量。只拉你真正要用的那个发行版是最容易被忽略的优化。6.2 几条我踩过的坑第一条不要在 Dockerfile 里用RUN rosdep update而不ENV索引地址。镜像构建时的网络环境和你本地可能完全不同本地通了不代表构建机上通。我建议在 Dockerfile 里显式声明ENV ROSDISTRO_INDEX_URLfile:///opt/ros-offline/rosdistro/index-v4.yaml COPY rosdistro /opt/ros-offline/rosdistro RUN rosdep update把离线数据打进镜像构建过程就完全不依赖网络了这个做法在多阶段构建里我用了很久复现性非常好。第二条rosdep init失败时不要反复重试。这一步只是写一个文件失败通常就是因为那份默认列表要在线拉取。直接手工创建20-default.list就能绕过省下大量时间。很多人卡在 init 上以为容器有问题其实完全没必要。第三条注意 shell 的作用域。export出来的变量只对当前 shell 及其子进程有效。你用sudo rosdep update时sudo默认会清空大部分环境变量导致你的ROSDISTRO_INDEX_URL根本没传进去如果某个步骤需要 sudo用sudo -E保留环境变量sudo -E rosdep update这个坑我卡过整整一个下午一直以为镜像站地址是错的最后发现是 sudo 把变量吃掉了。第四条备份一定要带时间戳。我习惯把每次改动过的配置都留一份带日期的副本出问题时能快速回溯到「上次能用是什么状态」sudo cp /etc/ros/rosdep/sources.list.d/20-default.list \ /etc/ros/rosdep/sources.list.d/20-default.list.$(date %Y%m%d-%H%M%S)6.3 长期维护上的几点经验把 rosdep 这一步彻底解决之后后续维护其实很轻。我总结下来就三件事。一是定期同步离线仓库。rosdep 的映射表是持续更新的新包、包改名都会反映在里面。如果用了离线方案建议隔一两个月在一台能联网的机器上git pull一次再重新分发缓存。频率不用太高半年一次对大多数项目也够用。二是把版本固定下来。rosdep 和 rosdistro 都有版本差异index-v4.yaml和index.yaml的切换就是例子。团队协作的场景下我倾向于把 rosdep 版本和 rosdistro 的快照都写进项目文档出现「同事那边能跑我这边不行」的时候第一件事就是比对这两个版本。三是别在生产环境里依赖公网。这句话听起来像废话但我见过太多线上设备因为某次重启后 rosdep 缓存失效、而恰好网络又不可用导致部署卡死。凡是需要长期运行的机器都应该把完整的 rosdep 缓存固化进系统镜像或配置管理流程里而不是指望运行时能拉下来。最后分享一个我现在的习惯任何需要联网的构建步骤我都会在动手之前先想清楚「如果这条路断了我有没有离线兜底」。rosdep 这件事教会我的其实不只是怎么改几个地址 —— 而是把「不确定性」从流程里挤出去。你现在遇到的那个 timeout说到底就是一个不确定的环节把它换成确定能跑通的东西问题就永远消失了。