企业官网建设流程全解析

搞过Ubuntu的人应该都有同感：系统装好了、显卡驱动怼上了、开发环境折腾妥了，最怕看到的就是终端里冒出一行Command 'ros2' not found。ROS2的安装说难不难，但网上教程参差不齐，有的让你直接apt install ros-humble-desktop，结果源没配好报一排错；有的让你源码编译，一编就是三四个小时，最后还经常挂在某个依赖上。

我这次在Ubuntu 22.04上完整走了一遍ROS2 humble的安装流程，从系统准备、软件源配置、正式安装到colcon工作区搭建和小乌龟验证，每一步都记录了下来。这篇文章既写给第一次接触ROS2的初学者，也给那些之前被Unable to locate package之类错误劝退的人做个完整排雷参考。

先说明我的测试环境：

ROS2 humble对应的是Ubuntu 22.04（Jammy），这个版本是目前LTS里用户基数最大的组合之一，官方支持周期到2027年5月，所以拿来作为学习和项目落地的主力版本都很合适。

1. 为什么选humble：版本对应关系与支持周期的底层逻辑

在动手敲命令之前，我建议你先花两分钟搞清楚一个事情——为什么偏偏是humble，而不是更新的jazzy或者更早的foxy。

ROS2的每个发行版和Ubuntu版本之间有严格的对应关系，不是随便一个ROS版本都能装在你的系统上的。官方发布策略是每个ROS2版本对应固定的Ubuntu发行版，这个对应关系由二进制包的编译环境决定，跨版本安装轻则缺依赖，重则根本装不上。

1.1 版本代号与Ubuntu版本的对应规则

ROS2的命名规则是代号加海龟品种，humble的全称是Humble Hawksbill（肯氏丽龟），它的目标平台是Ubuntu 22.04 Jammy。

几个常用版本的对应关系如下：

从表格能看出来，如果你用的是Ubuntu 22.04，长期维护的选项其实只有humble（Iron已经停止维护，Jazzy需要Ubuntu 24.04）。网上有些教程会教你在22.04上装jazzy，那种做法需要手动改源和绕过依赖检查，即便装上了也容易在后续使用中出现ABI不兼容的诡异问题，不建议新手尝试。

1.2 支持周期与长期维护的取舍

humble之所以被广泛使用，还有一个现实原因：它是ROS2第一个真正意义上的"LTS版本"。官方承诺的安全更新和维护周期到2027年，这意味着你用它开发的项目、安装的第三方包、你发的论文用的代码，在几年内都能在稳定的环境上运行，不需要频繁跟着版本升级迁移。

我个人的经验是：除非你有明确需求必须用新版本的特性（比如jazzy里的一些新API、新的通信机制），否则在22.04上老老实实用humble就是最优解。官方文档、开源仓库、Stack Overflow上的问题讨论，绝大多数都基于humble环境，遇到问题搜到的解决方案也最全。

2. 安装前准备：换源、语言环境、依赖包三件事

很多教程上来就让你添加ROS2的apt源然后直接开装，忽略了一件事：面向国内网络环境的软件源优化。如果你和我一样在国内网络环境下操作，尤其是用虚拟机的时候，这一步做不好后面会浪费大量时间在无意义的等待上。

2.1 系统源切换与软件包更新

打开终端，首先要做的是备份现有的软件源文件，这是改任何系统配置前的基本素养：

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

Ubuntu 22.04的软件源文件用的是新的DEB822格式，sources.list里只剩下一行引用，实际源配置在/etc/apt/sources.list.d/ubuntu.sources这个文件里。你没必要手动去编辑这个文件，直接用软件更新器或者sed替换镜像源就行，但更推荐的方式是安装software-properties-common后用命令切换：

sudo apt update sudo apt install software-properties-common

然后我用的是清华镜像源，因为实测它的同步频率和速度都比较均衡。编辑/etc/apt/sources.list.d/ubuntu.sources，把URIs: http://archive.ubuntu.com/ubuntu替换为URIs: https://mirrors.tuna.tsinghua.edu.cn/ubuntu即可。

替换完成后执行：

sudo apt update sudo apt upgrade -y

这一步把系统自带的软件包全部更新到最新状态，能避免后面安装ROS2时因为某个底层库版本过旧导致的依赖冲突。

2.2 设置UTF-8语言环境（关键但容易被忽略）

为什么教程里都会提到locale设置？因为ROS2的底层通信库（尤其是rviz2和gazebo这类GUI工具）对locale非常敏感，非UTF-8环境下启动时经常出现乱码或者直接闪退。

如果系统安装时选择了中文，locale默认可能是zh_CN.UTF-8或en_US.UTF-8。检查当前设置：

locale

我建议统一设置为en_US.UTF-8，虽然中文环境也能用，但ROS2的一些日志输出和工具链在英文环境下兼容性最好：

sudo apt install locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 export LANG=en_US.UTF-8

设置完成后需要重启终端或者重新登录会话才会完全生效。这个步骤不是必选项，如果卡在这一步会浪费时间，可以跳过，但如果你后面装完启动rviz2时报错，回来检查一下locale大概率能找到问题。

2.3 launchpad密钥与certificates依赖

ROS2的软件包是从packages.ros.org仓库拉取的，这个仓库使用GPG密钥对软件包签名进行校验，安装前必须把公钥添加到系统的信任列表中。

这个环节最容易出问题的点是curl和gnupg没装，导致密钥下载或者导入失败：

sudo apt install curl gnupg2 lsb-release

lsb-release用于识别当前系统的版本代号，curl负责下载密钥文件，gnupg2负责密钥的导入和管理。这三个工具都不大，但缺一个就卡住。

3. 三步配置ROS2软件源与密钥导入

这一节是整篇安装流程的重头戏，80%的安装失败都发生在这里，所以我会把每一步的命令、预期输出和可能遇到的报错都写清楚。

3.1 添加ROS2 apt源的完整命令

首先将官方ROS2仓库的密钥添加到系统信任的keyring中：

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

这条命令可以直接执行，因为在安装ROS2之前/usr/share/keyrings目录是已经存在的（Ubuntu系统自带），不需要额外创建。它做的事情是：用curl下载ROS官方的GPG公钥，然后存入系统keyrings目录，后续apt校验所有来自packages.ros.org的软件包时都会用这个公钥验证签名。

然后添加仓库地址到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)：动态获取当前系统架构（一般是amd64），避免写死
• signed-by=/usr/share/keyrings/ros-archive-keyring.gpg：指定apt使用我们刚下载的密钥去验证仓库签名，这是新版apt要求的写法
• $(lsb_release -cs)：动态获取系统代号，Ubuntu 22.04会返回jammy
• tee /etc/apt/sources.list.d/ros2.list：把拼接好的仓库配置写入新文件

执行完成后，可以用下面的命令查看写入结果：

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

预期输出：

deb [arch=amd64 signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu jammy main

3.2 校验密钥导入是否成功

很多教程在这一步直接让你apt update，但如果你在国内网络环境下直连packages.ros.org，这个仓库的访问速度通常不太乐观，apt update可能会卡很久甚至直接超时。

我建议添加完源之后，先做一次轻量化验证：

ls -l /usr/share/keyrings/ros-archive-keyring.gpg

确认文件存在且大小不为0。文件大概在几千字节级别，如果显示大小为0，说明刚才的curl下载失败了，需要重新执行。

然后执行：

sudo apt update

如果看到类似Get:14 http://packages.ros.org/ros2/ubuntu jammy InRelease [4,561 B]的输出，说明ROS2仓库连接正常，密钥认证通过。如果报错信息包含The following signatures couldn't be verified，说明密钥文件有问题，回到上一步重新下载。

3.3 常见源配置错误的排查

我见过最多的问题是这两类：

第一类：curl: (7) Failed to connect to raw.githubusercontent.com

这是网络访问问题。raw.githubusercontent.com在国内的连通性不稳定，如果curl下载不到密钥文件，可以改用我实测可用的国内镜像地址：

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

或者用wget加上代理参数重试。如果公司网络有代理，记得先给curl配置代理环境变量。

第二类：E: The repository 'http://packages.ros.org/ros2/ubuntu jammy Release' does not have a Release file

这个报错看起来像是仓库地址不对，但实际上是你的系统代号识别出了问题。用lsb_release -cs检查输出是不是jammy，如果不是，说明lsb-release工具没装好或者系统信息文件有问题。直接手动把jammy写死也行：

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

4. 正式安装humble桌面版：组件拆解与安装过程说明

源配置好了，接下来就是安装环节。这一步我会把版本选择的逻辑和每个组件的用途都讲清楚，方便你按需取舍。

4.1 按需选择desktop或base版本

ROS2 humble提供了几个不同的包组合，最常用的是这两个：

如果是刚接触ROS2，直接装desktop版就行。它包含的rviz2（3D可视化工具）、gazebo（仿真环境）、turtlesim（小乌龟演示程序）都是学习和调试的刚需工具，一次性装好省得以后用到哪个再补哪个。

执行安装：

sudo apt install ros-humble-desktop

这里有个细节要注意：安装过程中如果提示E: Unable to locate package ros-humble-desktop，不要急着换包名或者去搜别的教程，先回到上一步执行sudo apt update，大概率是更新源之后还没刷新软件包列表。

4.2 安装过程中的网络与依赖处理

ros-humble-desktop的依赖数量相当可观，初次安装会拉取几百个软件包，总下载体积在1GB以上。如果你使用的是虚拟机且网络一般，这个阶段可能耗时很长，看起来像是卡住了，实际上apt在后台慢慢拉包。

两条实用经验：

1. 不要中断安装。如果中途Ctrl+C强制终止，apt的锁文件会残留，下次安装会提示Could not get lock /var/lib/dpkg/lock-frontend，还得手动删锁，麻烦。

2. 安装过程如果报依赖错误，大部分是系统自带软件源版本过旧导致的。此时再执行一次sudo apt update && sudo apt upgrade -y，然后重新安装就能解决。

安装完成后，可以验证一下核心命令是否可用：

ls /opt/ros/humble/

预期能看到bin、include、lib、share等目录，其中bin目录下应该有ros2这个可执行文件。

4.3 验证ros2命令是否存在

如果你现在直接敲ros2，大概率会得到Command 'ros2' not found。这是正常的，因为ROS2的环境变量脚本还没有被加载。

确认命令文件存在即可：

ls /opt/ros/humble/bin/ros2

如果这个文件存在，说明安装成功，只是环境变量没配好——这就是下一节要解决的问题。

我在这里额外提一个点：如果你装完发现/opt/ros目录不存在，说明安装过程中出现了静默失败。重新执行sudo apt install ros-humble-desktop，这次留意输出结尾是否有error字样。

5. 环境变量配置与colcon工作区搭建

装好了不等于能用，ROS2的设计逻辑是：所有功能包都安装在/opt/ros/humble下，但系统不会自动把这些路径加入PATH。你需要手动source环境变量脚本，或者在配置文件中持久化设置。

5.1 为什么用bash而不直接改bashrc

每次打开新终端都要手动执行source /opt/ros/humble/setup.bash显然不现实，所以正确做法是写入~/.bashrc：

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

这里有个因为网络热词也提到的话题——"wsl ubuntu写代码最推荐的字体接近macos的体验"，虽然不是ROS2的核心话题，但如果你经常在终端里和ROS2打交道，终端字体和配色真的会影响效率和心情。我实测下来，在Ubuntu终端里设置JetBrains Mono或者Cascadia Code字体，显示中文和日志对齐效果都不错，接近macOS的终端体验。具体的字体安装方式在Ubuntu软件中心里搜索安装即可。

环境变量配置完成后，ros2命令就能直接使用了：

ros2 --help

如果看到命令帮助信息，你的核心环境就OK了。但我一般还会顺手验证一下ros2 topic list，它能确认通信层正常工作：

ros2 topic list

5.2 创建colcon工作区，解决"找不到包"的根源

colcon是ROS2的编译构建工具，相当于ROS1时代的catkin，用来编译你自己的功能包。很多新手装上ROS2后，把功能包放在任意目录下用ros2 run运行，结果报Package 'xxx' not found，就是因为功能包没有被正确构建和source。

创建一个规范的工作区：

mkdir -p ~/ros2_ws/src cd ~/ros2_ws

安装colcon工具：

sudo apt install python3-colcon-common-extensions

现在整个工作区的结构是这样的：

ros2_ws/ ├── src/ # 存放你自己的功能包源码 ├── build/ # 构建中间文件（自动生成） ├── install/ # 安装后的可执行文件和配置（自动生成） └── log/ # 编译日志（自动生成）

后续你编写自己的功能包时，把源码放在src目录下，然后在ros2_ws目录下执行：

colcon build source install/setup.bash

这样才能让ros2 run找到你自己编译的节点。这个工作区推荐也把source ~/ros2_ws/install/setup.bash写入~/.bashrc，和系统级的ROS环境变量一起加载，避免每次新开终端都要手动source：

echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc source ~/.bashrc

需要特别留意的是：install/setup.bash这个文件只有在执行过一次colcon build之后才会生成，新创建的工作区第一次执行source会报文件不存在，属正常现象，先编译一个包或者直接忽略即可。

6. 小乌龟与demo验证：安装成功与否的判定标准

到这里，你的ROS2环境已经装完了。但我一直认为，判断一个开发环境是否真正可用，必须通过一个能实际跑起来的Demo来验证，而不是只看ros2 --help能输出帮助信息就算成功。

6.1 启动turtlesim的完整流程

ROS2自带的turtlesim就是最好的验证工具。执行：

ros2 run turtlesim turtlesim_node

如果一切正常，会弹出一个蓝色背景的窗口，里面有一只可爱的小乌龟。这个操作看起来简单，但实际上验证了以下几个关键链路：

• ros2命令本身可用（核心环境配置无误）
• turtlesim功能包能正常找到（desktop版的包安装完整）
• GUI显示服务正常（X11或者Wayland环境下图形界面能弹出来）

如果窗口没弹出来，大概率是虚拟机里没装图形驱动或者显示配置有问题，和ROS2本身关系不大。VMware或VirtualBox用户可以考虑安装open-vm-tools或virtualbox-guest-utils增强工具：

sudo apt install open-vm-tools-desktop

6.2 键盘控制与话题通信的直观理解

小乌龟窗口弹出来后，新开一个终端，执行：

ros2 run turtlesim turtle_teleop_key

然后就可以用键盘的上下左右方向键控制小乌龟移动了。这个演示的核心意义在于：它验证了ROS2节点间的通信机制——turtle_teleop_key节点发布键盘按键消息到/turtle1/cmd_vel话题，turtlesim_node节点订阅该话题并驱动窗口中的小乌龟移动。

用以下命令可以直观看到话题通信的过程：

ros2 topic list ros2 topic echo /turtle1/cmd_vel

后者会实时显示键盘发布的线速度和角速度数据。看到类似输出：

linear: x: 2.0 y: 0.0 z: 0.0 angular: x: 0.0 y: 0.0 z: 0.0

说明通信链路完全正常，你的ROS2环境已经可以用于后续的实际开发了。

如果你对这个小乌龟还意犹未尽，可以尝试让乌龟画个圆之类的：

ros2 topic pub -r 1 /turtle1/cmd_vel geometry_msgs/msg/Twist "{linear: {x: 2.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 1.8}}"

这会以1Hz的频率向/turtle1/cmd_vel话题发布消息，小乌龟会自动绕圈，这个操作能更深入理解话题发布机制。

7. 我踩过的坑与排查手册（按错误现象分条）

最后这部分是我个人踩坑积累的排查经验，全部按错误现象来组织。你如果安装过程中遇到问题，直接对照着查就行。

7.1E: Unable to locate package ros-humble-desktop

这个报错出现的原因就两个字：没刷新源。sudo apt update这个命令之后运行一次，然后再执行安装。

如果apt update能正常跑完但还是找不到包，检查一下/etc/apt/sources.list.d/ros2.list里的内容是否正确，尤其是jammy拼写和[arch=amd64 signed-by=...]这段有没有写错。我之前见过有人把signed-by写成了sign-by，导致apt认为没有签名信息从而跳过了这个源。

7.2 密钥失效/签名验证失败

报错一般长这样：

The following signatures couldn't be verified because the public key is not available: NO_PUBKEY <密钥ID>

我遇到过两次，一次是密钥文件下载不完整，另一次是系统时间不对导致GPG校验失败。排查思路：

# 检查系统时间（如果时间不对，先同步） date sudo apt install ntpdate sudo ntpdate time.windows.com # 重新下载密钥文件 sudo rm /usr/share/keyrings/ros-archive-keyring.gpg sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

然后重新sudo apt update。

7.3 安装完成但ros2命令找不到

如果/opt/ros/humble/bin/ros2这个文件存在，但敲ros2提示找不到命令，一定是环境变量没配置好。执行：

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

还有一种可能：你当前用的shell是zsh而不是bash，上面写入的是~/.bashrc，只在bash生效。如果用的zsh，写入~/.zshrc即可。

7.4 虚拟机性能相关的卡顿与建议

如果你和我一样在虚拟机里跑ROS2，rviz2和gazebo这类重型工具可能会卡到怀疑人生。我的建议：

• 虚拟机内存至少分配4GB以上，8GB最佳
• 处理器核心数至少分配2个以上
• 开启3D加速
• 如果单纯测试通信逻辑，不涉及可视化，用rviz2的轻量替代方案或者直接在命令行下用ros2 topic echo验证消息收发

rviz2启动实在太卡的话，还有一个临时方案：关闭3D渲染相关插件，在启动命令前加LIBGL_ALWAYS_SOFTWARE=1强制使用软件渲染：

LIBGL_ALWAYS_SOFTWARE=1 rviz2

虽然画面效果一般，但能保住不被卡死。

另外提醒一句，如果你计划在后续项目里用docker microros ros2 humble vscode platformio esp32这套组合给ESP32刷Micro-ROS固件，建议直接创建一个已经配置好humble的ubuntu:22.04镜像，而不是在Windows上再折腾一套WSL环境。WSL可以跑通常规代码开发，但涉及USB设备直通、串口权限这些，还是原生Linux或者配置完善的Docker容器更方便。

最后补充一个小技巧：源里的ROS2包升级是有策略的，不要频繁执行apt upgrade升级ROS2相关包。官方在humble的补丁发布节奏上比较保守，但偶尔也会有大版本行为变化的补丁混进来。如果你测试好的代码突然行为异常，先想想最近是不是升级过ros-humble-*的包，必要时用apt-mark hold把某个关键包锁版。我个人的习惯是只更新系统的非ROS软件包，ROS2相关的包除非有明确修复了影响我项目的bug，否则一律保持原版本不动。