企业官网建设流程全解析

在WSL里折腾ROS2，卡在Unable to locate package ros-humble-desktop这一步的人，我估计能装满一个聊天室。这个报错看起来就像是系统在说“查无此包”，但真实原因往往藏在好几个不同的环节里——软件源没配上、源配错了、系统版本对不上、网络没通，甚至是WSL本身版本太老导致Ubuntu镜像异常。这篇文章就专门拆解这个报错，从原理到实操，把WSL下装ROS2 Humble的完整链路捋一遍，帮你在不重装系统的前提下把ROS2跑起来。适合刚接触ROS2、或者已经在Ubuntu原生环境装过但第一次在WSL下尝试的同学参考。

1. 先搞清楚这个报错在说什么

1.1 报错现场与常见误解

先看典型报错：

$ sudo apt install ros-humble-desktop Reading package lists... Done Building dependency tree... Done Reading state information... Done E: Unable to locate package ros-humble-desktop

很多人第一反应是自己命令拼错了，于是反复检查ros-humble-desktop这几个字母有没有打对，结果发现拼写没问题，问题出在更上游。这个报错的直译是“无法定位这个软件包”，言下之意是：apt在它已知的所有软件源里，翻遍了都没有找到叫ros-humble-desktop的包。

可以拿手机应用商店打比方：你在商店里搜一个App搜不到，通常不是App名字输错了，而是这个App压根没上架到这个商店、或者你登录的是另一个地区的商店。apt也一样，它的“商店列表”就是/etc/apt/sources.list和/etc/apt/sources.list.d/下的一大堆.list文件。ROS2的官方包默认不在Ubuntu自带的源里，必须手动把ROS2的仓库加进去，不加的话，系统再努力也找不到这个包。

还有一个常见误解是：以为apt update和apt install是同一件事。update的作用是“刷新商店的商品目录”，install才是真正去拿商品。如果添加了新的软件源之后不执行apt update就直接install，系统手里的目录还是旧的，照样报Unable to locate package。这个顺序问题在初学阶段特别容易踩。

1.2 WSL环境下更容易踩的坑

WSL和原生Ubuntu在软件源这个问题上有个明显差异：WSL自带的Ubuntu镜像有时候会使用一些特殊的源配置，比如为了在Windows防火墙下能正常更新，某些网络环境下默认源访问极慢。更麻烦的是，很多人的WSL是从旧版本一路升级上来的，或者用了网上下的离线安装包，导致系统版本和ROS2 Humble的要求对不上。

ROS2 Humble对Ubuntu版本的匹配是有明确要求的：Humble对应的是Ubuntu 22.04（Jammy）。如果你在WSL里装的是Ubuntu 20.04（Focal），那你应该装ROS2 Foxy而不是Humble；如果你强行把Humble的源写到20.04上，apt update的时候倒不会直接报错，但install的时候同样会提示找不到包。这种“源写对了但系统版本不对”的隐蔽情况，比单纯没加源更难排查。

另外，WSL本身分为WSL1和WSL2两个大版本。WSL2是真正的轻量虚拟机，兼容性更好，ROS2这种对系统调用要求比较高的软件，强烈建议在WSL2上跑。如果系统里还是老旧的WSL1，很多二进制包运行起来会直接段错误，更别提装ROS2了。所以正式动手之前，先把“地基”检查一遍。

2. 装ROS2之前，先给WSL做一轮“体检”

2.1 确认WSL版本与内核

在Windows的PowerShell或CMD里执行：

wsl --status wsl -l -v

wsl -l -v会列出当前已安装的发行版及其WSL版本。正常应该看到类似这样：

NAME STATE VERSION * Ubuntu Running 2

如果VERSION显示的是1，建议升级到WSL2。升级方法是：

wsl --set-version Ubuntu 2

这一步可能需要几分钟，而且要求Windows功能里开启了“虚拟机平台”。如果在运行的时候提示“your version of windows subsystem for linux (wsl) is too old. run the command...”这类信息，那就是Windows系统里的WSL组件太旧了，直接在PowerShell里执行：

wsl --update

把WSL组件更新到最新版。这个命令需要Windows 10 2004以上版本支持，如果系统太老，得先去Windows更新里把系统补丁打齐。很多人在这一步卡住，wsl --install又特别慢甚至报403，多半就是Windows更新组件不完整。我的建议是：先老老实实把系统更新做完，再回头搞WSL，不然各种莫名其妙的问题会接连不断。

2.2 确认Ubuntu版本与架构

进入WSL终端后，查看系统版本：

cat /etc/os-release

重点看VERSION_CODENAME这一行。如果是jammy，那恭喜，Ubuntu版本符合ROS2 Humble的要求；如果是focal（20.04）或者noble（24.04），那就得换思路了。Humble只支持jammy，这一点没有任何讨价还价的余地。

再看架构：

uname -m

正常是x86_64。如果你是在Arm版的Windows设备上跑的WSL，那架构是aarch64，ROS2 Humble对aarch64也有支持，但部分二进制包可能没有预编译版本，需要源码编译，难度会大不少。绝大多数人的场景是x86_64，下文以这个为准。

顺带说一下：有些人喜欢用“wsl离线安装ubuntu”的方式装系统，这种方式的坑在于离线包版本可能比较旧，装完之后apt update都会报错，因为旧版本的源地址已经失效了。如果你发现自己系统版本挺新但源更新老失败，先检查一下/etc/apt/sources.list里的地址是不是指向了已经停止维护的旧域名。

2.3 基础环境准备

在添加ROS2源之前，先把基础工具装齐：

sudo apt update sudo apt install -y curl gnupg lsb-release ca-certificates sudo apt install -y software-properties-common

lsb-release提供了lsb_release -cs命令，后面写自动化脚本的时候会用到，它可以动态获取当前系统的代号，避免写死版本号。curl用来下载ROS2的GPG公钥，gnupg用来导入公钥。

另外强烈建议把系统自带的源换成国内镜像源。这一步不是必须的，但能极大提高后续apt update和安装依赖的速度。WSL里默认的archive.ubuntu.com在国内网络环境下经常慢到怀疑人生，换成阿里云或清华的镜像之后，整个体验会顺畅很多。改源的时候注意备份原文件：

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

然后编辑/etc/apt/sources.list，把archive.ubuntu.com替换成mirrors.aliyun.com或mirrors.tuna.tsinghua.edu.cn。修改完记得再执行一遍sudo apt update验证源是否可用。

3. 核心解法：把ROS2源配置对，一切迎刃而解

3.1 三种源方案怎么选

ROS2 Humble的软件源大致有三类：官方源、国内镜像源、第三方一键脚本。它们的优缺点如下：

我个人建议：不管最后用哪种方式，至少手动走一遍官方流程，理解每一步在做什么。这样出了问题你能自己排查，而不是脚本跑完报错就只能干瞪眼。下面的步骤以手动配置为例，同时给出国内镜像的替换方法。

3.2 手动添加ROS2软件源的完整步骤

第一步，安装curl和gnupg（如果上一步做过了可以跳过）：

sudo apt update sudo apt install -y curl gnupg lsb-release

第二步，下载并导入ROS2的GPG密钥：

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

注意：这里命令里的地址是GitHub的raw地址，国内网络环境不一定能顺利访问。如果下载失败，可以使用国内镜像站的密钥地址，比如：

sudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/ros2/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

密钥文件放到/usr/share/keyrings/目录下是比较规范的做法，这样apt在验证包签名的时候会使用这个密钥，避免中间人攻击，也避免直接把密钥加到系统的全局信任列表里带来安全隐患。

第三步，把ROS2仓库写入apt源列表：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

这条命令干了几件事：先用dpkg --print-architecture动态获取系统架构，然后用$(lsb_release -cs)动态获取系统代号，最后把整行源地址写入/etc/apt/sources.list.d/ros2.list。使用signed-by参数指定密钥文件，比老教程里直接apt-key add的方式更安全——apt-key已经被官方标记为废弃，因为它会把密钥添加为全局信任，存在安全隐患。

如果用国内镜像，就把上面命令里的http://packages.ros.org/ros2/ubuntu换成https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu或https://mirrors.aliyun.com/ros2/ubuntu。这里有个容易踩的坑：镜像地址的路径要写对，清华的路径是/ros2/ubuntu，不是/ros/ubuntu（那是ROS1的源），写错了照样找不到包。

第四步，刷新软件源并安装：

sudo apt update

看到输出里出现类似这样的信息就说明源加成功了：

Get:6 http://packages.ros.org/ros2/ubuntu jammy InRelease [4,684 B]

如果apt update没有报错，但install还是找不到包，可以用下面的命令确认源里到底有没有这个包：

apt-cache search ros-humble

或者：

apt-cache policy ros-humble-desktop

如果输出里列出了ros-humble-desktop的候选版本，说明源没问题，直接装就行：

sudo apt install -y ros-humble-desktop

如果apt-cache search没搜到，说明源里确实没有，这时候要回到开头检查系统版本和源地址是否匹配。

3.3 安装完成后如何验证

装完之后，ROS2的环境变量默认不会自动加载，需要手动source：

source /opt/ros/humble/setup.bash

然后测试核心命令：

ros2 --help

能看到一堆命令列表就说明装上了。再跑个小乌龟验一下GUI：

ros2 run turtlesim turtlesim_node

新开一个终端，同样source环境变量，然后跑：

ros2 run turtlesim turtle_teleop_key

如果小乌龟的窗口能弹出来，并且可以用方向键控制乌龟移动，那整个ROS2安装就基本算成功了。WSL2下小乌龟弹窗需要Windows侧有可用的图形环境，一般来说WSL2的WSLg已经自动支持GUI程序，不需要额外配置X Server。如果弹窗失败，大概率是WSL版本太老，回到第2.1节升级WSL组件。

source环境变量这个问题，很多人刚接触时不理解为什么要每次手动执行。因为不同版本的ROS2共存时，环境变量会互相干扰，所以ROS2设计成不自动写入全局配置，需要哪个版本就source哪个版本。为了省事，可以把source命令追加到~/.bashrc：

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

这样每次打开新终端就自动加载了。但这也有个代价：如果你以后装了ROS2 Jazzy，两个版本的环境变量会冲突。我的做法是：默认不写入~/.bashrc，在需要用的终端里手动source，或者写一个别名alias ros2humble='source /opt/ros/humble/setup.bash'，这样想切版本的时候不会手忙脚乱。

4. 装了源还是找不到包？排查实录与速查表

4.1 网络问题导致公钥下载失败

添加ROS2源的第一步就是下载密钥，很多人在这一步就挂了。典型报错是：

curl: (35) error:0A000126:SSL routines::unexpected eof while reading

或者干脆超时。这就是网络访问GitHub不稳定导致的。换用国内镜像的密钥地址基本能解决。另外也可以手动下载密钥文件，然后放到指定目录：

sudo cp ./ros.key /usr/share/keyrings/ros-archive-keyring.gpg

只要文件内容是对的，用curl下载还是手动拷贝效果一样。判断密钥文件对不对，可以看文件大小，正常的ros.key文件大小通常在2KB到4KB之间，如果是几百字节或者几千字节但内容是HTML错误页面，那就是下载失败了。

4.2 apt update报403或404

添加源之后apt update报403（Forbidden）或者404（Not Found），原因通常是源地址写错了。403最常见的原因是镜像站要求使用HTTPS而不是HTTP，或者路径不对；404则多半是系统代号不对，比如把focal写成了jammy。这时候用cat /etc/apt/sources.list.d/ros2.list看一下源文件内容，再对比官方文档的写法，基本能定位问题。

还有一种情况是apt update报错信息里提示Certificate is not trusted或者NO_PUBKEY，这说明密钥导入有问题。解决办法是重新导入密钥文件，并确保源文件里的signed-by路径指向正确的密钥文件位置。这里要注意，密钥文件的权限也要正确，如果当前用户无法读取/usr/share/keyrings/ros-archive-keyring.gpg，apt也会报错。正常情况下该文件权限应为644：

sudo chmod 644 /usr/share/keyrings/ros-archive-keyring.gpg

4.3 系统中存在旧版本ROS残留

如果你之前尝试过其他教程安装ROS2，比如通过apt-add-repository添加了老的源，或者用鱼香ROS脚本装到一半失败了，系统里可能残留了旧的源文件和密钥。这些残留文件和新建的源会打架，导致apt update出现重复源或者报Hash校验错误。

排查方法：

ls /etc/apt/sources.list.d/

看有没有多个ros相关的文件。如果有ros2.list、ros.list、ros2-latest.list等多个文件，建议只保留一个，其他删掉。删之前先备份：

sudo mkdir -p ~/backup_sources sudo cp /etc/apt/sources.list.d/*.list ~/backup_sources/

然后清理，再apt update。

4.4 备选方案：一键脚本与Docker容器

如果手动配置实在搞不定，或者你只是急着想跑通一个demo，可以试试第三方的一键安装脚本。社区里流传最广的是鱼香ROS的脚本：

wget http://fishros.com/install -O fishros && . fishros

脚本会引导你选择要安装的ROS版本和桌面版/基础版，然后自动完成添加源、安装依赖的整个过程。但用第三方脚本前务必想清楚：你正在把系统最高权限交给一段网络上随便下载的脚本。我的建议是，只在测试环境或虚拟机里用，生产环境或者你日常开发的电脑上，还是老老实实手动装。

另一种更干净的方案是用Docker跑ROS2。ROS官方提供了ros:humble镜像，一条命令就能拉起一个带ROS2的容器：

docker run -it ros:humble

这种方式的好处是宿主机不会被折腾得乱七八糟，适合拿来做实验或者跑一些不依赖GUI的ROS2程序。配合VSCode的Dev Containers插件和PlatformIO，做嵌入式机器人开发（比如ESP32）非常方便，网上说的“docker microros ros2 humble vscode platformio esp32”就是这个路子。缺点是GUI程序需要额外配置环境，对于刚入门想玩小乌龟的人不太友好。

4.5 常见问题速查表

5. 安装完成后的日常使用配置

5.1 环境变量与多终端配置

ROS2和ROS1最大的区别之一就是环境变量的管理方式。ROS1用source /opt/ros/noetic/setup.bash之后基本一劳永逸，ROS2则更强调工作空间的概念。装完Humble之后，如果你要用colcon构建自己的工作空间，还需要安装colcon工具：

sudo apt install -y python3-colcon-common-extensions

另外建议安装argcomplete，让ROS2命令支持Tab自动补全：

sudo apt install -y python3-argcomplete

这两样虽然不是运行ROS2的必需项，但实际开发中几乎天天用到。没装argcomplete的话，敲ros2 topic再按Tab不会有任何反应，排查问题时效率会低不少。

5.2 WSL + VSCode 开发环境配置

在WSL下开发ROS2，VSCode几乎是事实标准。安装VSCode的WSL插件后，可以直接从Windows侧打开WSL里的代码目录：

code .

在WSL里执行这个命令，VSCode会自动以WSL模式启动，左下角会显示“WSL: Ubuntu”。这时候打开终端就是WSL里的bash，直接可以用ROS2命令，不用来回切换。

字体方面，我自己对比过好几款，在WSL里写ROS2代码最接近macOS终端体验的字体是JetBrains Mono和Cascadia Code，两者的连字效果让箭头函数、比较运算符看起来舒服很多。Cascadia Code是微软自家的开源字体，Windows Terminal里可以直接设置，JetBrains Mono在VSCode里配合FiraCode风格更清爽。你可以在VSCode的settings.json里配置：

{ "editor.fontFamily": "'Cascadia Code', 'JetBrains Mono', monospace", "editor.fontLigatures": true }

字体这事情虽然不影响功能，但长期看代码，眼睛舒服了心情就好，调试bug的耐心也会多几分。

5.3 常用ROS2命令速记

装好ROS2之后，最常用的命令其实就那么几个，记下来能省去很多翻文档的时间：

# 查看所有话题 ros2 topic list # 查看某个话题的消息类型 ros2 topic type /turtle1/cmd_vel # 查看话题实时数据 ros2 topic echo /turtle1/cmd_vel # 查看所有节点 ros2 node list # 查看节点详情 ros2 node info /turtlesim # 运行一个节点（以小乌龟为例） ros2 run turtlesim turtlesim_node # 编译工作空间 colcon build # 运行launch文件 ros2 launch package_name launch_file.launch.py

ros2 topic echo是调试周期最长的一个命令，很多消息问题都是通过它发现的。比如你发现机器人不动，先ros2 topic list看有没有你预期的那个话题，再用ros2 topic echo看有没有数据在发，这一套下来基本能定位是发布端的问题还是订阅端的问题。

5.4 从桌面版到其他扩展包

ros-humble-desktop包含的是ROS2的核心功能、可视化工具（rviz2、rqt）和turtlesim等演示程序。如果你的目标是做SLAM或导航，还需要额外安装：

sudo apt install -y ros-humble-gazebo-ros-pkgs sudo apt install -y ros-humble-nav2 sudo apt install -y ros-humble-slam-toolbox sudo apt install -y ros-humble-cartographer

这些包在安装时同样会依赖大量的其他库，如果前面系统源和ROS2源的配置有问题，这里会再次暴露出来。装这些包之前先执行一遍sudo apt update，确保源是最新的。网络热词里提到的“hotdog livox avia 配置使用 ros2”和“ros2 d435i”属于具体硬件驱动的问题，这些驱动的安装包很多也在ROS2源里，源配置好后直接搜包名就能装，原理和安装Humble本身是一样的。

写在最后的个人体会

我前前后后帮人排查过不少WSL下装ROS2失败的问题，发现90%以上都卡在源配置或者系统版本不匹配这两个环节，很少是命令拼错的。网络上的教程鱼龙混杂，很多都过时了，还在用apt-key添加密钥、源地址也指向旧版域名，照着抄很容易踩坑。我的建议是：遇到问题时先去ROS2官方文档查对应的Ubuntu版本，再对照自己系统实际的版本号，确认无误后再动手。另外不用迷信某一种安装方式，无论是官方源、镜像源还是Docker，适合自己的环境的就是最好的。祝大家的乌龟都能顺利跑起来。