ROS rosdep update 超时解决：换源、调参与离线化

装 ROS 的朋友大概都经历过这个场面：新系统刚配好，rosdep init一路顺风，紧接着敲下rosdep update，终端停在某一行不动了，等两三分钟，最后甩出一句Read timed out，重试几次还是同样的位置卡死。更气人的是，你照着网上某个教程改了两个文件，重新跑一遍，看起来过了，第二天换个终端又失败——因为那条命令其实从来没真正修好过，只是恰好在某一刻网络通畅。

这篇内容就是把rosdep update出现 time out 这件事拆到根上：请求到底发去哪、卡在哪一步、哪些改法是真有效、哪些改法只是碰运气。解决思路我会分三层给你——换索引源、调参数与超时、彻底离线化。不管你是刚装完 ROS 的桌面用户，还是在做气隙环境下的容器镜像构建，这三层里都有一条能直接抄的路径。文中所有路径和命令，都以 Ubuntu 系 + ROS Noetic/ROS 2 常见环境为基准，其他发行版把路径里的 Python 版本号换成你自己的即可。

1. rosdep update 超时的链路拆解：请求到底发去了哪里

1.1 rosdep init 和 rosdep update 根本不是一回事

很多人把这两个命令当成一件事，一出错就一起重装，这是排查效率最低的做法。rosdep init做的事情非常轻，它只是在/etc/ros/rosdep/sources.list.d/目录下写一个20-default.list文件，里面几行文本描述"数据源从哪来"，本身几乎不产生网络请求，所以它很少失败，一旦失败多半是权限问题（没用 sudo）而不是网络问题。真正产生网络流量的是rosdep update，它读取这个 list 文件里的每一条来源，把索引和规则文件逐个拉下来，落盘到~/.ros/rosdep/sources.cache。理解了分工，你就知道为什么"init 早就成功了，update 还是超时"——这两个命令的成功条件完全不重叠。

我还见过一种典型误解：以为删掉/etc/ros/rosdep/sources.list.d/20-default.list重新 init 就能解决超时。实际上重新 init 生成的还是同一份地址，只是把同一个坑又踩了一遍。源地址不改，init 一万次也没用。

1.2 一次 update 要发多少个请求，为什么这么容易断

rosdep update的请求是串行的，大致是三类：第一类是 sources list 里列的那几个通用规则文件（base、python、ruby 这类）；第二类是发行版索引文件；第三类是索引指向的每个发行版的具体描述文件。这几个文件本体都非常小，加一起也就一两百 KB。所以这条命令卡住，几乎从来不是带宽问题，而是"每一次连接握手能不能在超时时间内完成"的问题——跨境链路抖动、DNS 解析慢、TLS 握手被拖长，任何一个环节慢一点，整个串行流程就断在那里。

串行是这里最要命的设计。假设你有 10 个请求，每个成功率 90%，整体成功率就掉到 35% 左右。这解释了那个让人抓狂的现象：手动curl那个地址是通的，但rosdep update就是过不去。不是你运气差，是它在很短的时间里连着压了太多次独立请求，只要有一次超时，本轮就整体失败，而失败之后重试又是从头发起。

1.3 先判断是"慢"还是"根本不通"

动手改配置之前，先花两分钟定位，能省掉大量无用功。第一步，rosdep update --debug跑一遍，看它停在哪一行输出。如果停在查询索引那一步，说明是索引地址的问题；如果已经打印出"正在下载索引"然后才断，说明索引能到达，问题在这一步之后的规则文件链接上。位置不同，要改的文件也不同，这是后面所有操作的前提。

第二步，直接探活。用curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' <你的索引地址>，看返回码和耗时。如果耗时在两三秒以上，那基本可以确定不是偶发问题，必须换源或离线化，别指望多试几次能过。第三步，看缓存目录ls -l ~/.ros/rosdep/sources.cache/，里面已经有内容的，说明上次至少部分成功了，这种"半成功"状态最容易误导人——你以为是修复生效，其实是旧缓存被复用。

注意：排查阶段不要急着大改。先确认卡点，再决定改哪一处。我见过太多人一上来就把三个文件全改了，结果不知道是哪个改动起了作用，后面升级 rosdep 出问题时完全无法回滚。

2. 换索引源：把 rosdep 的数据请求指向可稳定访问的镜像

2.1 第一步永远是 grep，而不是照着记忆改文件

不同版本 rosdep 的源码结构差异不小，网上教程里写的行号在你机器上大概率对不上。所以第一步不是打开编辑器，而是先找出现场：

grep -rn "raw.githubusercontent.com" \ /usr/lib/python3/dist-packages/rosdistro/ \ /usr/lib/python3/dist-packages/rosdep2/ \ /etc/ros/rosdep/ 2>/dev/null

这条命令会把所有硬编码的海外地址位置一次性列出来。实战中最常见的命中点是三个：/etc/ros/rosdep/sources.list.d/20-default.list（list 文件，几行 yaml 来源）、rosdistro/__init__.py（默认索引地址常量）、rosdep2/sources_list.py（下载规则文件时的地址处理函数）。如果你想确认本机实际生效的索引地址，可以跑一句python3 -c "import rosdistro; print(rosdistro.get_index_url())"，它会告诉你当前用的是哪个 URL，比翻源码猜要靠谱得多。

2.2 三个位置分别怎么改，为什么都要改

先说 list 文件。用 sudo 打开/etc/ros/rosdep/sources.list.d/20-default.list，把里面所有指向海外地址的行，域名部分替换成可稳定访问的镜像域名，路径保持原样。这一步解决的是"通用规则文件"的下载。

再说rosdistro/__init__.py。找到那个默认索引地址常量，把它替换成镜像站上的索引地址。这里有个坑：索引文件名跟 rosdep 版本相关，老版本是index.yaml，中间版本index-v3.yaml，新版是index-v4.yaml。别凭记忆写，先探一下镜像站上到底有哪个文件：

curl -sI https://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yaml | head -1

返回 200 再用这个名字。如果返回 404，就把index-v3、index依次试一下，或者直接看镜像目录列表里存在什么。这一步解决的是"发行版索引"的下载。

最后是rosdep2/sources_list.py。索引文件里记录的每个发行版描述文件的地址，通常是写死的完整 URL，所以即使你把索引换成了镜像，索引拉下来之后它往下指的地址可能还是海外地址。这个文件里有一段地址拼接/替换的逻辑，把里面的域名基址替换成镜像域名，才能让第三步的请求也走镜像。这一步最容易被漏掉，也最容易造成"改了索引还是超时"的迷惑现象。

改完之后不要忘了删缓存重跑，否则你判断不了生效的是新地址还是旧数据：

rm -rf ~/.ros/rosdep/sources.cache rosdep update --rosdistro $ROS_DISTRO --debug

提示：改/usr/lib/python3/dist-packages/下的文件属于"打补丁"，被 apt 升级覆盖是迟早的事。改之前先cp xxx.py xxx.py.bak留个备份，或者干脆把这几条 sed 写成一个脚本存到自己的 dotfiles 里，升级完重新执行一次。

2.3 镜像同步延迟带来的"key 找不到"

换源之后很多人会遇到另一种报错：Cannot locate rosdep definition for [xxx]，或者某个包的依赖解析不出来。这不是超时问题，而是镜像同步延迟或索引与规则文件版本不一致导致的。最常见的原因是"半换源"——索引指向 A 镜像，规则文件还指向原地址或另一个 B 镜像，两边的快照时间不一样，于是索引里声明的 key 在当前规则文件里还没出现。

处理办法很直接：全部统一到同一个镜像，并且优先选同步频率高的站点；如果只是要装当前这一个发行版，用rosdep update --rosdistro $ROS_DISTRO只更新对应发行版，能显著减少需要同步的文件数量，也就减少了版本错配的概率。另外，别在容器构建过程中临时改源又临时改回来，构建缓存一旦把中间层留下来，后续排查会非常痛苦。

2.4 用环境变量兜住 apt 升级的覆盖问题

改包文件最大的缺点是不可持久。arm 架构的板子、长期不关机的开发机、需要重复初始化的 CI 机器，都建议用"不改包文件"的方式兜底。新版 rosdistro 支持通过环境变量ROSDISTRO_INDEX_URL覆盖索引地址，部分版本还会读取/etc/ros/rosdistro.yaml里的index_url字段。用哪种都行，关键是用python3 -c "import rosdistro; print(rosdistro.get_index_url())"验证它真的读到了你配置的值。

这里有个非常隐蔽的坑：环境变量对sudo不生效。你现在这个 shell 里配好了，rosdep update前面加个 sudo，环境就被重置了，读回去的还是默认地址，然后你盯着终端怀疑人生。要么用sudo -E，要么把变量写进/etc/environment或/etc/profile.d/下的一个脚本里。我个人倾向后者，因为它对所有用户、所有登录方式都生效，容器镜像构建时也不容易漏。

3. 参数与超时调优：不完全依赖镜像的第二种活法

3.1 先把手头这版支持哪些开关摸清楚

rosdep update的参数在不同版本之间差异挺大，与其照搬别人的命令，不如先看清楚自己这一版有什么：

rosdep update --help rosdep --version

几个通用性比较强的思路可以先用上。限定发行版是最有效的一招，rosdep update --rosdistro noetic（ROS 2 里换成对应的发行版名）只更新一个发行版的数据，请求数量直接砍掉一多半。--include-eol-distros这类开关则是反向操作，它会去拉已经停止维护的历史发行版，纯属给自己增加超时概率，非必要不要加。--debug用来定位卡点，排查完成后就别在自动化脚本里带着了，日志噪音太大。

3.2 把"无超时的等待"改成"有限超时 + 重试"

rosdep底层用的是标准库的 urlopen，早期版本没有显式设置超时，遇到握手慢的连接就会长时间挂住。这是一种比直接报错更糟糕的状态：你不知道它是在等还是在死。可以给下载调用补上超时和重试，思路大概是这样：

# 仅示意修改位置与思路，具体行号以你本机安装的版本为准 for attempt in range(3): try: data = urlopen(url, timeout=15).read() break except Exception as e: if attempt == 2: raise time.sleep(2)

为什么要加超时而不是把超时调得更大？因为这条链路的特点是"慢而不稳"，把超时从默认值拉到 60 秒，只会让每次失败多等 45 秒，成功率并不会提升。反而是"短超时 + 多次重试"的整体期望耗时更低、成功率更高。这是我在这类跨境访问场景里踩了很多次坑之后总结出的规律：跟不稳定链路打交道，快速失败比耐心等待划算。

3.3 一个能一次跑通的组合命令

把上面几件事串起来，我通常会用这样一条组合，先删缓存保证状态干净，再限定发行版、开 debug 观察：

rm -rf ~/.ros/rosdep/sources.cache rosdep update --rosdistro ${ROS_DISTRO} --debug 2>&1 | tee /tmp/rosdep-update.log

tee这一步看着多余，实际很值：报错信息里往往只有最后一行Read timed out，前面的关键上下文被截在滚动缓冲里找不到了。把完整输出落成文件，回头对比"这次卡在第几步、上次卡在第几步"，能很快判断出你的修改有没有真正把请求位移到新的地址上。判断标准很简单：日志里出现的域名应该是你配置的镜像域名，如果还是原来的海外域名，说明前面某处没改干净。

4. 完全离线：把 rosdistro 数据搬进本地，一次做成永久的

4.1 版本升级导致的补丁丢失，不如一次离线化

前三节都属于"绕开不稳定连接"，而离线化是"不再需要连接"。它的价值在两类场景下特别明显：一是内网或气隙环境，根本不给你访问外部地址的机会；二是容器镜像构建，你希望构建结果可复现，而不是今天能过明天不能过。

思路是把 rosdistro 数据整体复制到本地某个目录，然后把所有指向网络的 URL 都改写成本地文件路径。准备工作是拿到一份 rosdistro 数据的快照，可以从镜像站的归档下载，也可以在另一台网络条件好的机器上拿到整份数据后拷过来。放到比如/opt/rosdistro下面，保证里面有索引文件和rosdep/目录。

4.2 用 file:// 把两处地址都改写掉

拿到本地副本后，先把副本内部所有互相引用的地址改成file://形式：

cd /opt/rosdistro grep -rl "raw.githubusercontent.com" . | xargs -r sed -i \ 's#https://raw.githubusercontent.com/ros/rosdistro/master#file:///opt/rosdistro#g'

再改 list 文件，让起点也指向本地：

sudo tee /etc/ros/rosdep/sources.list.d/20-default.list > /dev/null <<'EOF' # local offline sources yaml file:///opt/rosdistro/rosdep/base.yaml yaml file:///opt/rosdistro/rosdep/python.yaml yaml file:///opt/rosdistro/rosdep/ruby.yaml EOF

然后照常rosdep update。因为走的是本地文件，整个流程基本是瞬间完成，也再不会有超时。这里要注意的是路径必须用三个斜杠的file:///，两个斜杠会被解析成 host，很多人卡在这一步。另外本地副本的目录权限要保证执行 rosdep 的那个用户可读，容器里往往是以非 root 用户运行的。

4.3 在能联网的机器上把 rosdep init 做完再搬

离线环境还有个细节：rosdep init需要往/etc/ros/写文件，如果目标机器权限受限，可以换一种做法——在一台能联网、环境相同的机器上完整跑通 init + update，然后把/etc/ros/rosdep/sources.list.d/和~/.ros/rosdep/sources.cache两个目录整体打包，拷到目标机器对应位置。这样连 init 都不需要在目标机上执行。

打包时注意两点：一是缓存目录属于哪个用户就要放到哪个用户的家目录下，权限用chown -R修正，否则 rosdep 会认为缓存不可用而重新尝试联网；二是记录一下这份快照的时间点，半年后排查依赖问题时你会需要知道当时的规则文件是哪个版本。这个习惯我是吃过亏才养成的——某次线上构建突然报一个依赖查不到，翻回来看才发现离线快照已经是一年前的。

4.4 固化进 Docker 镜像的正确姿势

容器场景下，把离线源直接写进 Dockerfile 是最省事的：

COPY rosdistro /opt/rosdistro COPY 20-default.list /etc/ros/rosdep/sources.list.d/20-default.list RUN rosdep update --rosdistro noetic && rm -rf /var/lib/apt/lists/*

几个坑说一下。第一，rosdep update的缓存默认写在执行用户的~/.ros下，构建时通常是 root，也就是/root/.ros，如果后面切了非 root 用户运行，缓存就找不到了，得用-u或HOME环境变量控制位置，或者把缓存放到/opt/ros这类共享路径并在运行时设置HOME。第二，别把rosdep update和网络依赖的步骤混在一个 RUN 里，否则网络抖动会让整个构建层缓存失效，每次都要从这层重来。第三，离线源的目录别放在构建完就删的临时目录里，运行时如果需要rosdep install，它还要读这些规则文件。

4.5 怎么验证离线源是真的可用

装完之后别急着走，做一次验收：

rosdep resolve rviz rosdep install --simulate --from-paths src --ignore-src -r

--simulate是关键，它只做依赖解析不实际安装，能快速暴露规则文件缺 key 的问题。如果输出里出现Cannot locate rosdep definition，说明你的离线快照不完整，缺了某些发行版或 OS 相关的规则文件，回到副本目录里核对一下是不是漏拷了某个子目录。这一步能在真正编译前把问题拦住，比编译到一半报依赖缺失要省事得多。

5. 排查顺序与几个想当然的坑

5.1 一张对照表，照着排查比瞎试快得多

5.2 最容易踩的五个"想当然"

第一个，以为只改一处就够了。索引和规则文件是两段独立的请求，只改其中一段，另一半照样超时。判断方法就是看 debug 日志里出现的域名，两个域名都应该是镜像域名才算改干净。

第二个，改完不删缓存。~/.ros/rosdep/sources.cache里已经落盘的旧数据会被复用，你根本分不清生效的是新配置还是旧内容。改配置和删缓存这两步永远绑在一起做。

第三个，系统里存在多个 rosdep。用 apt 装的python3-rosdep和用 pip 装的 rosdep 可能同时存在，which -a rosdep会列出所有可执行文件路径，python3 -c "import rosdep2; print(rosdep2.__file__)"能告诉你当前解释器实际加载的是哪一份。改错文件是最浪费时间的坑，因为所有操作看起来都对，就是不生效。

第四个，把第三方定制工具和原生 rosdep 混着用。社区里有针对国内网络做过源适配的定制版本，能省事，但它的缓存目录、配置文件位置和原生版本不一定一致，混用之后会出现"明明更新过，命令用的还是老数据"这类诡异问题。我的建议是团队里统一选一种，并且写进环境搭建文档，别让两个人用两套。

第五个，以为版本升级后补丁还在。用 apt 升级过 rosdep 相关包之后，/usr/lib/python3/dist-packages/下被改过的文件会被覆盖回默认版本，如果你只是手动改过没留脚本，下次升级完超时问题会原样复现。用dpkg -S /usr/lib/python3/dist-packages/rosdistro/__init__.py可以确认这个文件归属哪个包，方便你判断哪些改动会被覆盖。

5.3 我现在的标准操作顺序

给一个我实际在用的顺序，从零到可用大概五分钟：先curl探活确认镜像索引文件存在；再grep -rn找出所有海外地址位置；统一替换域名，改前备份；把ROSDISTRO_INDEX_URL写进/etc/profile.d/下的脚本，让 sudo 也能读到；删缓存，跑rosdep update --rosdistro $ROS_DISTRO --debug并把日志落盘；最后用rosdep resolve和--simulate做一次解析验收。这一套跑下来，我不再需要"多试几次碰运气"，成不成功当场就能看出来。

另外分享一个小习惯：把镜像索引文件用curl -o下载一份存到项目目录下，同时记下下载时间。下次遇到依赖解析不出来，可以直接对比"是不是镜像同步落后了"，不用重新猜。这个习惯在跨团队协作的时候特别有用，别人复现不了你的构建时，你能立刻给出当时的镜像快照信息。

至于最终选哪条路，我的经验是这样：个人桌面开发机，换镜像 + 环境变量兜底足够了；CI 和容器构建，直接上离线快照，别跟网络抖动较劲，省下来的时间远比做一次离线化的成本高；气隙环境没得选，只能离线化，而且越早做越省钱——等到构建流水线里几十个任务都依赖网络源的时候再改，工作量是现在的十倍。