机器人 / 系统课时
建立 colcon 工作空间目录
建立 colcon 工作空间目录
在 Ubuntu 24.04 与 ROS 2 Jazzy 环境下,创建 ~/ros2_ws 工作空间,使用 colcon build 初始化构建目录,并在新终端加载 install/setup.bash。完成后,你将知道功能包应放在哪里、哪些目录由工具生成,以及怎样判断工作空间是否准备就绪。
学习目标
- 创建包含
src的标准 ROS 2 工作空间,并从正确位置运行colcon build。 - 区分
src、build、install、log的用途。 - 在独立终端加载工作空间环境,识别空工作空间与构建失败的区别。
检查 ROS 2 与构建工具
以下操作适用于 Ubuntu 24.04、Bash 与通过系统软件包安装的 ROS 2 Jazzy。先加载已有 ROS 2 安装,再确认 colcon 可用;如果使用其他发行版,应将路径中的 jazzy 替换为实际版本。
source /opt/ros/jazzy/setup.bash
printf 'ROS_DISTRO=%s\n' "$ROS_DISTRO"
if command -v colcon >/dev/null 2>&1; then
echo 'colcon=ready'
fi预期输出:
ROS_DISTRO=jazzy
colcon=ready若第二行没有出现,先执行 sudo apt update 与 sudo apt install python3-colcon-common-extensions,然后重新检查。若第一条 source 报文件不存在,应先确认 ROS 2 已安装,不能通过创建空目录代替安装。
创建目录并执行首次构建
工作空间是保存多个功能包的容器,src 放源代码,colcon 从工作空间根目录发现并构建功能包。本课暂不创建功能包,先验证空工作空间能否完成构建。
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
# 从工作空间根目录构建,不要进入 src 后运行
colcon build
ls -d build install log src预期输出示例:
Summary: 0 packages finished [<TIME>s]
build install log src<TIME> 随机器性能变化,ls 的列间距也可能不同。0 packages finished 在这里是正常结果:src 尚无功能包,但 colcon 已创建工作空间产物。它不表示已有 Python 节点构建成功。
看懂构建产物与环境层次
| 目录 | 用途 | 是否手工编辑 |
|---|---|---|
src/ |
放置功能包源码,如后续的 Python 包 | 是 |
build/ |
存放构建时的中间文件 | 否 |
install/ |
存放安装结果及 setup.bash 等环境脚本 |
否 |
log/ |
保存构建日志,便于查错 | 否 |
构建时读取 src/,写入 build/、install/ 与 log/。使用节点时则加载 install/setup.bash,让当前终端能够找到已安装的功能包。系统安装的 /opt/ros/jazzy 是下层环境(underlay),本地工作空间是叠加在其上的上层环境(overlay)。

在新终端加载并验证
新开一个 Bash 终端执行以下命令,不要在已经加载当前工作空间 overlay 的终端反复构建,以免隐藏依赖问题。source 只影响当前终端,重新打开终端后需要再次执行。
source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
test -f ~/ros2_ws/install/setup.bash && echo 'workspace setup=found'
printf 'ROS_DISTRO=%s\n' "$ROS_DISTRO"预期输出:
workspace setup=found
ROS_DISTRO=jazzy这个结果表明工作空间配置脚本存在、加载命令没有报错,且 ROS 2 Jazzy 基础环境可用。由于 src 还是空的,此时用 ros2 pkg list 只能看到已有安装中的功能包,不能期待出现自己尚未创建的包。
排查目录与包发现问题
如果执行 source install/setup.bash 报文件不存在,先检查是否执行过 colcon build、构建是否成功,以及当前目录是否是 ~/ros2_ws;不在根目录时改用绝对路径 source ~/ros2_ws/install/setup.bash。
如果以后把 Python 文件直接放进 src/,但构建仍显示 0 packages finished,说明文件并不等于 ROS 2 功能包。进入工作空间根目录执行 colcon list 检查是否发现包;标准 ament_python 包还需要 package.xml、setup.py 等元数据。添加合法功能包后重新构建,并在新的终端加载 install/setup.bash 才能发现自己的包。