WSL下ROS2 Humble源配置与安装报错排查

在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.04Jammy。如果你在WSL里装的是Ubuntu 20.04Focal那你应该装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 -vwsl -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的要求如果是focal20.04或者noble24.04那就得换思路了。Humble只支持jammy这一点没有任何讨价还价的余地。再看架构uname -m正常是x86_64。如果你是在Arm版的Windows设备上跑的WSL那架构是aarch64ROS2 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-commonlsb-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的软件源大致有三类官方源、国内镜像源、第三方一键脚本。它们的优缺点如下方案优点缺点适用场景官方源packages.ros.org权威、包最新、无兼容性问题国内网络访问慢容易超时网络条件好或愿意等国内镜像源清华、阿里、中科大速度快、稳定、社区验证充分偶尔同步延迟国内开发者首选鱼香ROS一键脚本全程自动化、适合纯新手第三方脚本有安全风险、难以定制想快速跑通demo、不关心原理我个人建议不管最后用哪种方式至少手动走一遍官方流程理解每一步在做什么。这样出了问题你能自己排查而不是脚本跑完报错就只能干瞪眼。下面的步骤以手动配置为例同时给出国内镜像的替换方法。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的环境变量默认不会自动加载需要手动sourcesource /opt/ros/humble/setup.bash然后测试核心命令ros2 --help能看到一堆命令列表就说明装上了。再跑个小乌龟验一下GUIros2 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命令追加到~/.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc这样每次打开新终端就自动加载了。但这也有个代价如果你以后装了ROS2 Jazzy两个版本的环境变量会冲突。我的做法是默认不写入~/.bashrc在需要用的终端里手动source或者写一个别名alias ros2humblesource /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报403Forbidden或者404Not 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.gpgapt也会报错。正常情况下该文件权限应为644sudo chmod 644 /usr/share/keyrings/ros-archive-keyring.gpg4.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 常见问题速查表问题可能原因解决方案Unable to locate package ros-humble-desktop未添加ROS2源 / 未apt update / Ubuntu版本不对添加正确源的并执行apt update确认系统是jammycurl下载ros.key失败网络访问GitHub不稳定换用清华等镜像的密钥地址手动下载密钥文件apt update报403镜像要求HTTPS / 源路径写错检查源文件路径改用httpsapt update报404系统代号与源不匹配确认lsb_release -cs输出检查源地址中的代号NO_PUBKEY错误密钥导入失败或signed-by路径错误重新下载密钥到/usr/share/keyrings/检查文件权限安装时依赖版本冲突系统源和ROS2源的依赖版本不匹配先完整执行apt update必要时升级系统已有的依赖包小乌龟窗口弹不出来WSLg组件问题或WSL版本太老执行wsl --update升级WSL组件source /opt/ros/humble/setup.bash 报错ROS2没安装成功或路径不存在检查/opt/ros/下是否有humble目录无则重新安装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下开发ROS2VSCode几乎是事实标准。安装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.pyros2 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适合自己的环境的就是最好的。祝大家的乌龟都能顺利跑起来。