如果你在 WSL 里执行sudo apt install ros-humble-desktop时看到Unable to locate package ros-humble-desktop先别急着怀疑人生。这个错误几乎每个 ROS 2 新手都会撞上一次原因通常不是你的命令写错了而是 apt 的源列表里根本没有 ROS 2 的仓库。今天我就把这个问题从现象到根源、从自查到修复、从安装到验证完整过一遍顺便把我踩过的坑都摆出来照着做基本不会翻车。1. 先搞清楚报错的来龙去脉1.1 你的环境到底是什么样我见过不少朋友在群里贴出这个报错第一反应是“Ubuntu 坏了”或者“ROS 2 装不了”。其实问题往往出在最基本的环境匹配上。在 WSL 里安装 ROS 2首先得确认你用的是哪个发行版、什么版本、什么架构。WSL 默认装的是 Ubuntu但版本可能是 20.04、22.04 甚至 24.04。ROS 2 Humble 官方支持的是 Ubuntu 22.04 JammyROS 2 Jazzy 对应 24.04ROS 2 Galactic 对应 20.04。如果你在 20.04 上去装ros-humble-desktop系统自然会告诉你找不到包因为 Humble 根本不在 20.04 的软件仓库里。我遇到过最典型的一种情况是有人用 WSL 安装了 Ubuntu 22.04但/etc/apt/sources.list里的代号被改成了focal或者他从网上复制了一份旧的源配置导致 ROS 2 的安装命令去找 20.04 的源结果自然一无所获。所以在动手之前先花半分钟把环境确认清楚。cat /etc/os-release uname -m这两条命令分别告诉你系统版本和 CPU 架构。正常情况下你应该看到VERSION_ID22.04以及x86_64。如果你用的是 ARM 版的 Windows 设备这里会出现aarch64后续添加软件源的时候需要对应调整。1.2 为什么 apt 找不到这个包Unable to locate package这个报错的本质是 apt 在本地软件包索引里查无此包。它不是“包坏了”也不是“网络断了”而是 apt 根本不知道有这个包存在。打个比方apt 就像你在超市购物但货架上没有这件商品。你问店员店员只能说“没这个东西”。要让货架上有ros-humble-desktop就得先把 ROS 2 的官方仓库地址写进 apt 的源列表然后执行apt update把商品清单拉下来。只要这个仓库没加或者加了没更新你永远会得到Unable to locate package。很多教程会直接让你执行安装命令但忽略了你可能是第一次在这台机器上装 ROS 2。WSL 本身只是一套刚装好的 Ubuntu它默认的源里只有 Ubuntu 自带的软件包和 ROS 2 一丁点关系都没有。所以接下来的核心工作就是把 ROS 2 的软件源加进去并且确保 key 校验通过。2. 完全解决前的三步自查2.1 系统版本对不对得上ROS 2 Humble 对 Ubuntu 版本的要求非常严格因为不同版本依赖的底层库版本不一样。Ubuntu 22.04 对应 HumbleUbuntu 24.04 对应 JazzyUbuntu 20.04 对应 Galactic。如果你装的是 20.04又非要用 Humbleapt 一定会给你Unable to locate package。你可以在 WSL 终端里执行lsb_release -a如果看到Release: 22.04那你走对方向了。如果不是你需要考虑更换 WSL 里的 Ubuntu 版本或者改用与系统匹配的 ROS 2 发行版。顺带一提WSL 里更换 Ubuntu 版本并不复杂你可以用wsl --install -d Ubuntu-22.04安装指定版本也可以在 Windows 应用商店里直接搜索对应版本。但要注意如果当前 WSL 发行版里已经写了不少代码最好先备份数据再换。2.2 ROS 2 软件源加没加这是最核心的自查项。执行下面的命令看看有没有 ROS 2 的仓库文件ls /etc/apt/sources.list.d/正常情况下你会看到ubuntu.sources或ros2.list之类的文件。如果在列表里看不到任何和 ros 相关的.list或.sources文件那基本可以断定ROS 2 源没加。有些朋友之前可能加过源但文件路径写错了。比如把源文件放到了/etc/apt/sources.list里但格式写成了 deb822 的.sources格式导致 apt 解析异常又或者写在sources.list末尾但注释符号没去掉。这些细节也会让 apt 找不到包。更隐蔽的一种情况是源加在/etc/apt/sources.list.d/ros2.list但文件里没有signed-by指向 keyringapt 会因为安全校验失败而忽略整个仓库然后报找不到包。所以光看文件存在不够还要看文件内容是否合法。2.3 软件包索引更新了吗假设你已经添加了 ROS 2 源但忘了sudo apt update那么本地的软件包列表仍然是老版本apt 一样不知道ros-humble-desktop的存在。这个步骤看起来简单却救了无数人的命。不少教程把apt update和apt install写在一行里或者让你先装别的依赖时顺手执行过 update但你自己操作时可能只复制了 install 那一段。所以当你遇到 Unable to locate package 时先老老实实执行一次sudo apt update然后再看能不能找到包。如果 update 过程中没有任何错误并且包名正确这个问题基本就消失了。3. 手把手修复的几种落地方式3.1 官方仓库手动安装流程既然问题是仓库没加那第一步就是把 ROS 2 的官方 apt 仓库加进去。ROS 2 官方文档里给了完整的步骤我在这里做一个可以复制的精简版。先安装必要工具sudo apt update sudo apt install -y software-properties-common curl sudo add-apt-repository universe然后导入 ROS 2 的 GPG keysudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg如果你的网络环境访问 GitHub 不够稳定这一步可能会失败。失败的表现一般是 curl 报错、key 文件为空或者后续 apt update 提示 key 不存在。这种情况下我会选择从国内镜像站下载同一个 keysudo curl -sSL https://mirrors.tuna.tsinghua.edu.cn/rosdistro/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpgkey 文件本质是个公钥用哪个镜像下载都行内容是一样的不影响后续校验。接着写入 ros2 源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)会输出你的架构比如amd64这样源地址就能匹配当前系统$(lsb_release -cs)会输出 Ubuntu 的代号比如jammy这样就不会因为系统版本写错而找不到包。signed-by参数指定的就是刚才下载的 keyring 文件。写入后执行sudo apt update如果一切正常你会看到软件源列表里多出了packages.ros.org的条目没有报错。然后再安装sudo apt install -y ros-humble-desktop如果这一步还报Unable to locate package那问题大概率出在源文件的内容或系统版本上。回到第 2 节重新检查。3.2 国内镜像源替换虽然官方源在国内大多数情况下能用但偶尔会出现速度慢、超时的问题。遇到这种情况把源切换到国内镜像会更省心。这里以清华源为例。前面的 key 导入步骤不变关键是源地址变一下echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null这里用的是https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu。阿里云、中科大也有对应的 ROS 2 镜像原理都一样。切换镜像源后记得执行sudo apt update刷新索引然后就可以正常安装了。我个人的建议是如果你在安装时发现 key 下载失败或 apt update 很慢别死磕官方源切镜像源是最省时间的方案。毕竟我们最终的目的是把 ROS 2 跑起来而不是和网络环境较劲。3.3 用 fishros 一键安装快速解决如果你不想手动折腾这些源和 key还有一个更省力的办法使用鱼香 ROS 的一键安装脚本。这个脚本在国内 ROS 圈子里很流行它会把软件源、key、依赖、环境变量全部处理好还会帮你选择安装版本。执行方法wget http://fishros.com/install -O fishros . fishros运行后会出现一个交互式菜单选择1一键安装 ROS 2 桌面版并按提示输入系统密码它会自动帮你配置环境。如果你倾向于自动化又怕手动步骤出错这个方式非常稳妥。不过我还是要补充一句一键安装脚本本质上是替你执行了手动流程它并不神秘。如果你后面想排查问题还是得理解前面讲的源和 key 的概念。脚本只是把重复劳动包装了一下核心逻辑没有区别。3.4 安装完成后的环境初始化包装好后还不能直接使用ros2命令因为 ROS 2 的环境变量还没有加载。你需要在终端里 source 一下source /opt/ros/humble/setup.bash但每次打开终端都要手动 source 很麻烦更推荐把它写进 shell 配置echo source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc此时执行ros2 --help如果能看到命令列表说明安装成功。如果你是 zsh 用户把上面的.bashrc改成.zshrcsetup 文件也可以换成setup.zsh。WSL 默认是 bash但很多人会自己装 zsh这里要注意一下。4. 装完后能跑哪些东西小乌龟与 rviz24.1 用 turtlesim 验证核心通信ROS 2 装好之后最经典的“Hello World”就是小乌龟。它能验证你的核心通信是否正常也可以作为学习话题、节点、服务的入口。打开三个终端分别执行终端一ros2 run turtlesim turtlesim_node终端二ros2 run turtlesim turtle_teleop_key终端三ros2 node list ros2 topic list如果你在终端二里用方向键控制小乌龟移动并且在终端三能看到/turtle1/cmd_vel这个话题那说明你的 ROS 2 核心功能一切正常。第一次跑小乌龟时很多人会遇到窗口打不开的问题这个我会在下一节展开。4.2 在 WSL 里调通 GUI 图形界面以前在 WSL 里跑 ROS 2 图形程序需要额外配置 X Server比如 VcXsrv、Xming 之类还要设置DISPLAY环境变量非常麻烦。但如果你用的是 Windows 11并且 WSL 版本较新系统自带的 WSLg 已经支持图形界面了小乌龟和 rviz2 都能直接弹出窗口。如果你遇到窗口黑屏、闪退或者无法显示先检查一下 WSL 版本wsl --version如果版本太老建议在 Windows 终端里执行wsl --update另外运行 rviz2 之前可以先跑一个简单的图形程序测试sudo apt install x11-apps xeyes如果能看到一双眼睛跟随鼠标说明 GUI 通路没问题。如果 xeyes 都打不开那就和 ROS 2 无关是 WSLg 或 X 转发配置的问题。关于 WSLg还有一个容易踩的坑如果你的 Windows 版本是旧的或者 WSL 内核没更新某些图形程序会报cannot open display。这时候最快的解决办法是执行wsl --update更新 WSL 到最新版本。4.3 在 VSCode 中开发 ROS2 的舒服姿势前面解决的只是安装和运行真正做开发时我一般都推荐使用 VSCode WSL 的组合。VSCode 装上 WSL 扩展后可以直接连接到 WSL 里的 Ubuntu 环境不需要单独装 Linux 版 VSCode整个体验和本地开发几乎一样。在 Windows 端打开 VSCode安装WSL扩展然后在终端输入code .VSCode 就会自动连接到当前 WSL 的目录。之后你写的代码、跑的终端都在 WSL 内部不会碰到 Windows 和 Linux 文件权限混乱的问题。字体方面如果你追求接近 macOS 的终端体验可以试一下JetBrains Mono或MesloLGS NF。在 VSCode 的settings.json里设置{ editor.fontFamily: JetBrains Mono, terminal.integrated.fontFamily: JetBrainsMono Nerd Font, editor.fontLigatures: true }字体大小可以按个人喜好调我个人习惯是 14。这个设置会让代码里的-、变成好看的连字阅读 ROS 2 源码时舒服不少。5. 常见问题速查与避坑记录5.1 换源后 apt update 报错最常见的报错是类似The repository http://packages.ros.org/ros2/ubuntu jammy Release does not have a Release file。这种问题一般是源和 key 不匹配或者源里用了不存在的发行版代号。排查时先看一下/etc/apt/sources.list.d/ros2.list里的内容确认 URL 后面跟的代号是不是你的系统代号。如果系统是 Ubuntu 22.04这里必须是jammy不能写focal或noble。另外确认 URL 是有效的通常直接访问这个 URL 能看到dists目录。另一个报错是GPG error: The following signatures couldnt be verified because the public key is not available。这说明 keyring 文件没生效或路径不对。重新执行一次 key 下载命令并检查文件权限sudo ls -l /usr/share/keyrings/ros-archive-keyring.gpg如果文件长度为 0说明下载失败了需要重新下载。5.2 rosdep 初始化卡住ROS 2 安装之后很多人会执行rosdep init和rosdep update来初始化依赖管理工具。但这一步在国内网络环境下经常卡住要么卡在ERROR: cannot download default sources list要么在 update 时一直超时。如果你的项目要用到 rosdep推荐直接使用国内镜像源。一个比较省事的方法是使用小鱼的一键安装工具里的 rosdepc 替代方案sudo apt install python3-rosdep sudo rosdep init rosdep update如果发现 update 卡死可以改用rosdepc它本质上是一段替换了源地址的 rosdep 脚本能解决绝大多数网络问题。具体安装方式可以参考 fishros 的脚本它会自动帮你搞定。如果你只是学习和练习rosdep 并不是必须的。日常编译自己的 workspace 时用colcon build就够了rosdep 主要是在编译别人的源码时帮你下载依赖包。所以卡住可以先跳过不影响小乌龟和 rviz2。5.3 重启 WSL 后 ros2 命令不见了这个问题出现频率极高原因不是安装失败而是source /opt/ros/humble/setup.bash没有写入~/.bashrc。很多人安装完执行source后当场运行正常但重启 WSL 或关闭终端再打开又报ros2: command not found。解决方案就是之前说的把 source 命令追加到~/.bashrcecho source /opt/ros/humble/setup.bash ~/.bashrc source ~/.bashrc另外要注意如果你用 zsh 代替了 bash修改~/.bashrc是没用的得写到~/.zshrc里。还有一种情况是你安装了多个 ROS 2 版本比如先装了 Foxy又装了 Humble两个 source 在 .bashrc 里冲突了。这时候检查一下 .bashrc 里的 source 行保留一个就好。5.4 其他零碎问题安装过程中还会遇到一些不起眼的小问题我列在下面sudo: add-apt-repository: command not found没有安装 software-properties-common先执行sudo apt install software-properties-common。E: Package ros-humble-desktop has no installation candidate这个报错比 Unable to locate 更进一步说明 apt 确实找到了仓库但当前系统架构或版本不支持这个包。检查uname -m和lsb_release -cs。WSL 磁盘空间不足ROS 2 桌面版装完会占用好几个 GB如果 WSL 虚拟磁盘满了apt 安装会报空间不足。可以在 Windows 端用wsl --shutdown之后压缩 vhdx或者清理 apt 缓存sudo apt clean。同时安装多个发行版导致默认 WSL 不对如果你在 Windows 上装了多套 WSL终端里打开的可能不是你想要的那套。执行wsl -l -v查看当前发行版列表必要时用wsl -s Ubuntu-22.04设置默认版本。最后说一个我个人的习惯每次安装完 ROS 2我不会急着跑小乌龟而是先建一个空 workspace 测试colcon build保证整个工具链是通的。因为小乌龟只验证运行时而 colcon 验证的是编译环境。只有编译、运行都通了后面写自己的节点才会少踩坑。mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build如果这个命令能顺利生成build和install目录你的 ROS 2 开发环境才算真正准备完毕。后面就可以开始写 publisher / subscriber做你的第一个 ROS 2 程序了。