ROS Noetic国内镜像安装：清华源配置与踩坑全解

1. 别急着敲命令，先想清楚官方源为什么会卡

1.1 官方源的痛，装过一次的人都懂

这几年只要有人问我“ROS装不上去怎么办”，我第一反应不是让他重新输一遍命令，而是先问他用的是哪个软件源。官方ROS源放在海外服务器上，晚高峰的时候apt update那叫一个痛苦，满屏红字，进度条半天不动，偶尔还直接Failed to fetch。最气人的是，明明命令一行都没抄错，最后却挂在网络等待上。

清华源算是国内最老牌、更新最勤的一组镜像之一。它不只是把ROS的软件包同步了一份，连Ubuntu系统本身的软件源也有完整镜像。所以想省心，就老老实实把两条链路都换上：一条是Ubuntu系统源，一条是ROS软件源。只换其中一条，安装时依然可能卡在依赖下载上。

1.2 清华源到底管哪一段：系统源和ROS源是两个东西

很多人第一次配置时会把“换源”理解成一个动作，其实这里有两套源。

• Ubuntu系统源：负责安装ROS的底层依赖，比如编译器、CMake、Python、各种库文件，配置文件写在/etc/apt/sources.list里。
• ROS软件源：负责安装ros-noetic-desktop-full这类ROS核心包，配置文件写在/etc/apt/sources.list.d/ros-latest.list里。

清华源对这两套都提供了镜像地址。系统源用https://mirrors.tuna.tsinghua.edu.cn/ubuntu/，ROS源用https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu。先换系统源，再加ROS源，两条腿都落地，后面安装才会顺。

1.3 两条路线：手动换源和一键脚本

网上现在也能看到“鱼香ROS一键安装”之类的脚本，确实方便，适合想赶紧把环境跑起来的场景。但如果你是在帮别人装机、做批量部署，或者之后想排查问题，我建议手动配一次清华源。手动配完你才知道每个文件是干什么的，以后遇到NO_PUBKEY、404这类报错，不会两眼一抹黑。

另外，一键脚本通常也会把rosdep、环境变量一起处理掉，过程对使用者是黑盒，一旦生产环境需要复现，反而难定位。所以本文就把手动步骤一条条拆开讲。

2. 装之前必须确认的版本对应关系

2.1 Ubuntu和ROS版本不能乱配对

ROS不是一个“随便装在哪版Ubuntu都能跑”的软件，它和Ubuntu版本有严格对应关系。版本对不上，最典型的症状是：添加源之后apt update出现404，或者搜索包的时候找不到ros-noetic-*。

目前ROS 1里维护最活跃、资料最多的是Noetic，对应Ubuntu 20.04。如果你手头是22.04，官方并没有对应的ROS 1新版本，强行按本文安装会踩不少坑。最稳妥的做法是用Ubuntu 20.04的物理机、虚拟机或Docker容器来装Noetic。

2.2 三条命令确认系统代号

执行下面的命令，先确认你的Ubuntu版本：

lsb_release -a cat /etc/os-release

重点关注Codename或VERSION_CODENAME，它会输出focal、bionic这类单词。后面配置系统源和ROS源时，这个代号会反复用到。如果提示lsb_release不存在，可以先装一下：

sudo apt update sudo apt install lsb-release

2.3 先备份，随手能回滚

改源之前，把/etc/apt/sources.list备份一份。不要嫌麻烦，配置写错的时候，备份就是你最后的后悔药。

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

备份文件后面加一个日期更方便回滚时辨认：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak.$(date +%F)

3. 系统源切换：这是很多人漏掉的前提条件

3.1 直接覆盖sources.list

用清华源最干净的做法，是把原来的sources.list整个覆盖掉。下面以Ubuntu 20.04（focal）为例，把这四行写进文件：

sudo tee /etc/apt/sources.list > /dev/null <<EOF deb 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 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 EOF

如果你是18.04，就把focal全部替换成bionic；16.04则替换成xenial。这里的main restricted universe multiverse是Ubuntu的软件仓库组件，universe尤其重要，ROS的很多依赖包都在里面。缺了universe，后面装ROS时会提示找不到一堆依赖。

3.2 用sed替换旧源，适合不想大改的场景

如果原来的sources.list里有很多自行添加的条目，不想整个覆盖，也可以用sed把官方域名替换成清华源：

sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g; s/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list

这条命令会把archive.ubuntu.com和security.ubuntu.com一并替换。但替换完最好打开文件看一眼，确认没有残留的http://和https://混用问题。我个人的习惯是直接覆盖，配置越干净越容易排查。

3.3 apt update验证

源改完之后，执行：

sudo apt update

正常情况下会看到从mirrors.tuna.tsinghua.edu.cn下载索引，速度明显比官方源快。如果之前装过ROS但没卸干净，这里可能会报错，先不用慌，继续看后面ROS源的配置，最后再统一处理。

这里提醒一句：apt update通过之后，先不要急着apt upgrade。尤其你是在已有业务的机器上操作时，升级系统包可能把内核、图形驱动一起带掉，概率不高，但没必要在装ROS之前冒险。等ROS装完，再按需升级。

4. ROS源写入与公钥导入：命令只有两行，坑却不少

4.1 写入ros-latest.list

ROS源要写在独立文件里，不建议塞进sources.list，这样以后想换回官方源，删一个文件就行，不用动系统源。

sudo sh -c 'echo "deb https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

命令里的$(lsb_release -sc)会自动取当前的系统代号，比如20.04就是focal，18.04就是bionic。这样写的好处是复制到不同版本的机器上都不会错。

写完后可以查看一下：

cat /etc/apt/sources.list.d/ros-latest.list

你应该看到类似这样的一行：

deb https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu focal main

4.2 导入公钥：选对keyserver

ROS软件包都做了GPG签名，apt需要信任对应的公钥才能安装，否则更新索引时会出现NO_PUBKEY报错。添加公钥的命令是：

sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654

如果keyserver.ubuntu.com网络不稳定，可以换成hkp://pgp.mit.edu:80或keyserver.ubuntu.com不带hkp://前缀再试。公钥导入成功后，终端会提示gpg: Total number processed: 1之类的内容。

4.3 更新后确认ROS源生效

公钥导入后，再执行一次：

sudo apt update

这次刷新列表时，应该能看到 ROS 源被读取。如果看到类似：

Get:... https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu focal/main amd64 Packages

就说明ROS源已经生效。此时可以用搜索命令验证一下：

apt-cache search ros-noetic | head -n 10

能搜出东西，说明源没有问题。如果你在apt update的最后看到403 Forbidden，先别怀疑清华源挂了，多半是地址写错，比如漏了/ros/ubuntu这一段，或者把main写成了其他组件。

5. 选择完整版还是极简版，再动手安装

5.1 安装desktop-full

如果你是新手，目标是学习ROS、跑仿真、做视觉或者机械臂开发，直接安装desktop-full版本准没错。它包含ROS核心、Rviz、Gazebo、turtlesim示例、各种常用库，一次到位。

sudo apt install ros-noetic-desktop-full

这条命令会把几百个软件包装进来，下载量不小。好在已经换成清华源，按我的实际体验，时间主要花在磁盘写入和解压上，网络不再是瓶颈。

5.2 如果跑服务器或只想试试，ros-base更合适

如果机器配置很紧张，或者你只是需要跑一个ROS节点，不需要图形界面和仿真，可以装ros-base：

sudo apt install ros-noetic-ros-base

它只包含ROS通信框架、launch工具和基础库，模块化开发完全够用。等后面需要可视化或者仿真时，再单独安装：

sudo apt install ros-noetic-rviz ros-noetic-gazebo-ros

这样按需安装，磁盘占用和系统负担都会小很多。

5.3 安装完看看装了哪些包

安装结束后，用下面的命令确认ROS包数量：

dpkg -l | grep ros-noetic | wc -l

如果输出是几十甚至几百，说明安装成功了。也可以直接查看某个核心命令是否存在：

which roscore

如果路径里没有输出，说明ROS命令还没有被加入当前shell的环境变量，下一步就解决这个问题。

6. rosdep初始化：我选择先跳过，理由在这里

6.1 rosdep是给源码编译用的，不是给apt用户用的

官方教程在安装完ROS后，会继续执行：

sudo apt install python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential sudo rosdep init rosdep update

很多小白在这里被卡到怀疑人生。实际上，rosdep的作用是帮你解析和安装“ROS功能包源码编译时需要的系统依赖”。如果你只是用apt install ros-noetic-desktop-full装好的预编译二进制包，ROS本体已经把需要的依赖都带上了，rosdep在运行demo阶段根本用不上。

我见过太多人把时间耗在rosdep update的网络报错上，最后发现ROS早就能跑了。所以我的建议是：安装阶段先跳过这一步，不影响使用。

6.2 如果后面编译源码，再考虑配rosdep

当你之后从源码编译某些功能包时，rosdep才真正派上用场。到那时候，你可以再执行rosdep init和rosdep update。这两个命令在部分网络环境下确实容易失败，因为默认的20-default.list指向海外地址。

遇到失败，我的处理习惯是：

• 先确认当前网络对海外服务器的访问情况，多试几次；
• 如果一直失败，立刻放弃在安装流程里耗时间，转而用apt install ros-noetic-xxx手动补齐缺失的依赖；
• 如果必须用rosdep，就找一篇针对当前Ubuntu版本、当前rosdep版本的国内镜像配置教程，把20-default.list里的索引地址换成镜像地址。

不要在这一步“死磕”。rosdep只是一个工具，不是为了它才装ROS的。

6.3 跳过rosdep对后续有什么影响

跳过rosdep后，常规的ROS开发场景不受影响。roscore、rosrun、rostopic、rviz、gazebo这些命令全部可以正常使用。你唯一会碰到的问题是：从源码catkin_make一个功能包时，如果它依赖某个系统库，而你没有手动安装，编译会在find_package阶段报错。这时候再回头补依赖就行。

换句话说，rosdep是“省事工具”，不是“必要条件”。这个问题想通了，安装流程能直接砍掉一大半的痛苦。

7. 用两只小乌龟证明ROS真的能跑

7.1 把setup.bash写进环境变量

ROS安装完成后的核心环境变量脚本是/opt/ros/noetic/setup.bash。每次打开新终端，都得先source它，否则roscore等命令都会提示找不到。最省事的方法是写进~/.bashrc：

echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc source ~/.bashrc

如果你的默认shell是zsh，就改成写进~/.zshrc。加载后运行：

rosversion -d

如果输出noetic，说明ROS环境变量已经正确加载。

7.2 启动三件套：roscore、乌龟节点、键盘遥控

ROS的“Hello World”是turtlesim小乌龟。开三个终端，分别执行：

终端1：

roscore

终端2：

rosrun turtlesim turtlesim_node

终端3：

rosrun turtlesim turtle_teleop_key

在终端3里按方向键，你会发现终端2弹出的蓝色窗口里，小乌龟跟着你的按键动起来了。能走到这一步，说明ROS核心、节点通信、键盘控制、图形界面全部正常，整个安装链路就已经通了。

7.3 小乌龟起不来怎么排查

如果终端2报错Package 'turtlesim' not found，说明desktop-full没有安装成功，或者你只装了ros-base，可以补装：

sudo apt install ros-noetic-turtlesim

如果roscore能启动，但rosrun turtlesim turtlesim_node显示连接超时，检查一下环境变量里是否设置了奇怪的ROS_MASTER_URI。全新安装的机器一般不用管这个，但如果你之前手动配过多机通信，就要清掉。

8. 换源后我实际遇到过的报错，按踩坑频率排序

8.1 apt update 404：版本代号对不上

这是换源后最常见的报错。终端里出现404 Not Found，且URL路径里能看到/dists/或/pool/，多半是系统源和ROS源里的代码有问题。

检查一遍：

• /etc/apt/sources.list里的代号是否和当前系统一致？
• /etc/apt/sources.list.d/ros-latest.list里的代码是否自动取成了正确值？
• 有没有把20.04的源写到18.04机器上？

用一条命令列出当前所有源，再逐一核对：

cat /etc/apt/sources.list cat /etc/apt/sources.list.d/*.list

8.2 NO_PUBKEY：公钥没进对地方

apt update时如果提示：

The following signatures couldn't be verified because the public key is not available: NO_PUBKEY C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654

说明公钥没有导入成功。重新执行一次：

sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654

如果网络差，多试几次，或者换pgp.mit.edu服务器。导入后再sudo apt update，一般就能解决。

8.3 roscore command not found

明明装完了，但一执行roscore就说找不到命令。这个问题的原因几乎永远是环境变量没有source。

一步步排查：

ls /opt/ros/noetic/setup.bash echo $ROS_DISTRO

如果ROS_DISTRO为空，说明/opt/ros/noetic/setup.bash没有被加载。回到刚才的.bashrc配置检查一遍。

8.4 Python环境串台：Anaconda的锅

Noetic版本默认使用Python 3。很多人的机器上装了Anaconda，并且把conda的环境变量和PYTHONPATH写进了~/.bashrc，这会给ROS带来诡异的问题，比如rospkg报错、import rospy失败。

处理方式很简单：在运行ROS的终端里，不要激活conda环境。或者调整~/.bashrc的顺序，先source /opt/ros/noetic/setup.bash，再启用conda。如果问题已经出现，先执行：

echo $PYTHONPATH

正常情况下应为空。如果输出了Anaconda的路径，清理掉，再重新打开终端。

8.5 其他零碎问题

• apt-key提示deprecated：这是Ubuntu 20.04对旧式密钥管理的警告，不影响安装，忽略即可。
• 安装中途断电或强制中断：执行sudo apt --fix-broken install修一遍。
• 之前用官方源装了一半想换清华源：先删掉/etc/apt/sources.list.d/ros-latest.list，再重新按本文配置，最后执行sudo apt update。

9. 手动换源和一条龙脚本，我现在的选择

9.1 手动换源适合谁

如果你需要反复给多台机器安装ROS，或者在公司内网、离线环境里部署，手动换源的价值就体现出来了。清华源地址稳定，配置过程可复制，而且你清楚自己改了哪些文件，出问题时能快速回退。相比之下，一键脚本会把多个步骤封装在一起，虽然省事，但脚本一旦更新了行为，或者目标机器环境特殊，结果就很难预测。

9.2 我现在的装机顺序

根据这么多次装机的经验，我现在的顺序非常固定：

1. 备份/etc/apt/sources.list；
2. 把系统源整体换成清华源；
3. 添加ROS源并导入公钥；
4. 安装ros-noetic-desktop-full；
5. 写setup.bash到.bashrc；
6. 启动小乌龟验证；
7. rosdep等真到了源码编译阶段再处理。

这套流程在清华源的加持下，网络这块基本不会再出幺蛾子。如果你正好卡在某一步，按上面的排查清单逐条过一遍，应该比盲目重装系统靠谱得多。