前言
很多初学者会混淆 ROS1 与 ROS2 的工作空间，
ROS1 使用 catkin_ws + catkin_make
ROS2 统一使用 colcon 编译工具
工作空间结构、创建命令、编译命令全部改动。
本文基于 Ubuntu22.04 + ROS2 Humble，全程小白友好，逐行解释命令、拆解每个文件夹作用，看完就能独立搭建、使用自己的 ROS2 工程。
一、什么是 ROS2 工作空间
ROS2 工作空间（workspace）就是一个独立文件夹，专门存放你自己写的机器人代码、功能包、自定义消息、启动文件。
系统自带的 ROS 工具（比如 turtlesim、rviz）存放在 /opt/ros/humble 系统目录，不建议修改；
所有个人开发代码全部放在自定义工作空间，解耦方便，工程迁移、删除、复制都不会破坏系统 ROS 环境。
ROS2 工作空间固定包含 4 个核心目录：src、build、install、log（ROS2 无 ROS1 的 devel 文件夹，这是最大区别）。
二、四大核心目录详解（重点，小白必看懂）
假设你的工作空间名为 colcon_ws，根目录路径：~/colcon_ws/
1. src（Source Space 源码空间，唯一需要手动写代码的文件夹）
- 路径：
~/colcon_ws/src/ - 作用：存放所有自定义功能包（package），Python 脚本、C++ 源码、launch 启动文件、自定义消息、配置文件全部放在这里。
- 目录结构说明：
colcon_ws/src/ ├── package_01/ # 第一个自定义功能包 │ ├── package.xml # 功能包配置文件（依赖、名称、版本） │ ├── CMakeLists.txt # 编译规则文件 │ ├── launch/ # 存放.launch.py启动文件 │ ├── scripts/ # 存放Python可执行脚本 │ ├── src/ # 存放C++源码 ├── package_02/ # 第二个自定义功能包 - 关键规则：工作空间下所有功能包必须直接放在 src 下，不能嵌套文件夹。
2. build（Build Space 编译中间文件目录）
- 路径：
~/colcon_ws/build/ - 作用：
colcon build编译时生成的临时缓存、CMake 编译中间文件、日志、依赖检测文件。 - 实用知识点：
- 里面文件看不懂，不需要手动修改；
- 代码改完编译报错时，可以直接删除整个 build 文件夹，重新编译清除缓存；
- 每个功能包会在 build 里生成独立子文件夹，互不干扰。
3. install（Install Space 安装空间，运行程序核心目录）
- 路径：
~/colcon_ws/install/ - 作用：编译完成后，生成可执行程序、库文件、环境脚本、启动文件，运行自己代码全靠这个文件夹。
- 内部关键子文件夹：
bin/：编译好的可执行程序（Python/C++ 节点）；lib/：C++ 编译生成的动态库、Python 包；share/：功能包配置、launch 文件、消息定义、参数文件；setup.bash / setup.sh：环境变量脚本，新开终端必须source install/setup.bash，系统才能识别你写的自定义节点；
- 补充：ROS1 的
devel文件夹在 ROS2 中被彻底移除，所有运行相关文件统一放到 install。
4. log（日志目录，ROS2 独有）
- 路径：
~/colcon_ws/log/ - 作用：每次
colcon build编译完整日志，编译报错、警告全部存在这里，排查编译失败时可以打开日志查看详细报错信息。
三、从零搭建 ROS2 工作空间（逐行命令 + 详细说明）
前置条件
- Ubuntu22.04 系统，已完整安装 ROS2 Humble；
- 终端提前加载 ROS2 基础环境（永久配置过
.bashrc可跳过）
source /opt/ros/humble/setup.bash步骤 1：创建工作空间根目录 + src 源码文件夹
mkdir -p ~/colcon_ws/src-p：自动创建多级目录，上层文件夹不存在也不会报错；
~/colcon_ws：工作空间根目录，~代表当前用户家目录；
/src：源码目录，ROS2 强制要求所有功能包放在 src 内。
步骤 2：进入 src 目录，创建自定义功能包（工程代码载体）
#切换到 src 文件夹 cd ~/colcon_ws/src #创建功能包通用语法 ros2 pkg create --build-type ament_python 包名 依赖1 依赖2ros2 pkg create：ROS2 创建功能包专用指令（替代 ROS1 的 catkin_create_pkg）；
--build-type ament_python：编译类型，写 Python 代码；
--build-type ament_cmake：编译类型，写 C++ 代码；
实操示例（创建名为demo_pkg的 Python 功能包）:
ros2 pkg create --build-type ament_python demo_pkg rclpy std_msgs末尾跟随依赖包，rclpy（Python 通信核心库）、std_msgs（标准消息）是基础必带依赖。
执行后 src 内会生成demo_pkg完整模板文件夹，自带 package.xml、资源目录。
步骤 3：返回工作空间根目录，编译整个工作空间
#切回工作空间根目录（必须在 colcon_ws 下编译，不能在 src 里编译） cd ~/colcon_ws #执行编译命令 colcon build命令说明：
colcon：ROS2 官方统一编译工具，替代 ROS1 catkin；build：执行编译操作；- 可选优化指令：
colcon build --packages-select demo_pkg只编译单个功能包，速度更快；
- 编译成功标志：终端末尾输出
Summary: X packages finished [XX.Xs]，无 error 报错。 - 编译完成后，根目录自动生成
build、install、log三个文件夹。
步骤 4：加载工作空间环境变量（关键！不 source 无法运行自定义节点）
临时生效（仅当前终端，新开终端需要重新执行）
source ~/colcon_ws/install/setup.bash原理：执行 install 内的 setup 脚本，把你的自定义功能包路径注册到系统 ROS 环境，终端才能通过ros2 run找到你写的节点。
永久生效（推荐，新开终端自动加载）
#编辑 bash 配置文件 gedit ~/.bashrc #在文件最底部添加一行： source ~/colcon_ws/install/setup.bash #保存关闭文件，刷新配置立刻生效 source ~/.bashrc步骤 5：验证工作空间环境是否配置成功
执行检查命令：
echo $COLCON_PREFIX_PATH正常输出会包含/home/wzl/colcon_ws/install，代表环境加载成功。
四、创建 / 编译功能包完整流程复盘（简化实操流程）
1:进入源码目录：cd ~/colcon_ws/src
2:创建功能包（Python 举例）：ros2 pkg create --build-type ament_python test_pkg rclpy std_msgs
3:返回工作空间根目录：cd ~/colcon_ws
4:编译：colcon build
5:加载环境：source install/setup.bash
6:运行自定义节点：ros2 run test_pkg 你的节点文件名
五、ROS1 catkin_ws vs ROS2 colcon_ws 核心区别（避坑重点）
表格
| 对比项 | ROS1（catkin） | ROS2（colcon） |
|---|---|---|
| 编译工具 | catkin_make / catkin build | colcon build |
| 工作空间名称 | catkin_ws（习惯命名） | colcon_ws（习惯命名） |
| 中间目录 | build + devel | build + install + log，无 devel |
| 创建功能包命令 | catkin_create_pkg | ros2 pkg create |
| 环境脚本路径 | devel/setup.bash | install/setup.bash |
| 编译系统 | catkin | ament_python / ament_cmake |
六、小白高频问题解答
1. 为什么运行自己写的节点提示 “包不存在”？
90% 原因：没有执行source install/setup.bash，系统没识别到你的工作空间，永久写入.bashrc即可一劳永逸。
2. 代码修改后运行还是旧效果？
两种解决方式：
- 在工作空间根目录重新执行
colcon build，再 source 环境； - 彻底清除缓存：删除 build、install、log 三个文件夹，重新编译。
3. src 里可以放多个功能包吗？
完全可以，src 下能存放几十个独立功能包，一次colcon build全部编译。
4. 能不能创建多个工作空间？
可以，比如一个colcon_ws做 AGV 导航、一个camera_ws做视觉，注意source时只会生效最后加载的工作空间，多工程开发建议分开终端。
5. build 文件夹可以删除吗？
完全可以，删除后重新colcon build会自动生成，常用于解决编译缓存错乱、奇怪报错。
七、拓展小实操（快速测试你的工作空间）
#在 src 创建测试包 cd ~/colcon_ws/src ros2 pkg create --build-type ament_python hello_world rclpy std_msgs #返回根目录编译 cd ~/colcon_ws colcon build source install/setup.bash #查看包是否被识别 ros2 pkg list | grep hello_world能输出 hello_world，代表整个工作空间搭建流程完全成功。
