机器人Linux+ROS2开发命令手册:环境搭建·编码调试·部署排错

SSH连板卡调驱动、colcon编译ROS2节点、Docker隔离仿真环境、git管理代码——机器人开发从底层驱动到上层部署，每个环节都绕不开终端。本手册覆盖Linux基础、Git版本控制、Vim快速编辑、Docker容器化、ROS2全流程五大模块，附思维导图总览、场景速查表、开发工作流全景、Docker容器生命周期和故障排查决策树，从嵌入式调参到多机协作一册搞定

命令全景图

1. Linux 基础命令

1.1 文件目录

1.2 文件查看与搜索

1.3 权限管理

嵌入式调试常用：串口设备默认属root/dialout组，把自己加入dialout组：sudo usermod -aG dialout $USER

1.4 系统与进程

1.5 网络

1.6 压缩解压

1.7 管道与重定向

2. Git 版本控制

2.1 基础配置与仓库

# 全局配置（仅首次）git config --global user.name "linuxros"git config --global user.email "dev@linuxros.com"git config --list                         # 查看当前配置# 仓库操作git init                                  # 初始化本地仓库git clone git@github.com:user/repo.git    # 克隆远程仓库

2.2 日常提交流程

git status                                # 随时查看状态（养成习惯）git add src/new_node.cpp                  # 添加指定文件（别用 git add .）git commit -m "feat: add lidar driver"# 提交到本地

2.3 分支管理

git branch                                # 查看本地分支git branch -a                             # 查看所有分支（含远程）git checkout -b feat/gazebo-sim           # 创建并切换到新分支git switch feat/gazebo-sim                # 切换分支（Git 2.23+）git merge feat/gazebo-sim                 # 合并到当前分支git branch -d feat/gazebo-sim             # 删除已合并分支

2.4 远程同步

git remote add origin git@github.com:user/repo.gitgit push -u origin main                   # 首次推送并关联上游git pull --rebase origin main             # 拉取更新（rebase保持历史线性）git fetch --all                           # 获取所有远程分支

2.5 版本回退与暂存

git log --oneline -10                     # 看最近10条提交git log --graph --oneline --all           # 图形化查看分支历史git diff HEAD~1 src/                      # 查看本次改动git diff --staged                         # 查看已暂存的改动git reset --hard HEAD~1                   # 回退到上一个版本（慎用！）git checkout -- src/broken.cpp            # 撤销单个文件修改git stash                                 # 暂存当前修改git stash pop                             # 恢复暂存的修改git stash list                            # 查看暂存列表

2.6 Git 分支工作流

3. Vim 编辑器速查

机器人开发中最常见场景：远程SSH改.bashrc、调launch参数、修CMakeLists.txt

3.1 模式切换

3.2 光标移动

3.3 编辑操作

3.4 搜索与保存

3.5 Vim 三种模式切换

4. Docker 容器

ROS2版本共存、Gazebo依赖冲突、环境隔离——Docker解决90%的"我这能跑你那不行"

4.1 服务与镜像

# 服务管理sudo systemctl start docker               # 启动Docker服务sudo systemctl enable docker              # 开机自启sudo systemctl status docker              # 查看服务状态# 镜像操作docker pull osrf/ros:humble-desktop-full  # ROS2 Humble官方镜像（完整版~2.5G）docker pull osrf/ros:jazzy-desktop        # ROS2 Jazzy官方镜像docker images                              # 查看本地镜像列表docker rmi old_image:v1                    # 删除镜像docker build -t my_robot:v1 .             # 从Dockerfile构建自定义镜像

4.2 容器操作

# 创建并运行容器（开发模式）docker run -dit --name ros_dev \    --network host \                       # 网络host模式（ROS2 DDS通信必需）    -v /home/$USER/code:/workspace \       # 挂载代码目录    -v /tmp/.X11-unix:/tmp/.X11-unix \     # X11转发（GUI应用）    -e DISPLAY=$DISPLAY \    osrf/ros:humble-desktop-full# 常用操作docker ps                                  # 查看运行中容器docker ps -a                               # 查看所有容器（含已停止）docker start ros_dev                       # 启动已停止的容器docker exec -it ros_dev bash               # 进入容器bashdocker logs -f ros_dev                     # 实时日志docker stop ros_dev && docker rm ros_dev   # 停止并删除容器

4.3 GPU支持

# 安装nvidia-container-toolkit后docker run --gpus all ...                  # 容器内使用全部GPUdocker run --gpus '"device=0"' ...         # 指定GPU设备# 验证：容器内执行 nvidia-smi

4.4 数据与编排

docker cp ros_dev:/workspace/log ./        # 容器→宿主机拷贝文件docker cp ./config.yaml ros_dev:/workspace/ # 宿主机→容器拷贝文件# Docker Composedocker compose up -d                       # 后台启动多容器docker compose down                        # 停止并清理docker compose ps                          # 查看compose容器状态docker compose logs -f                     # 查看compose日志

4.5 Dockerfile 最佳实践

# 多阶段构建：构建阶段 vs 运行阶段FROM osrf/ros:humble-desktop-full AS builderWORKDIR /wsCOPY src/ src/RUN . /opt/ros/humble/setup.sh && colcon buildFROM osrf/ros:humble-ros-coreCOPY --from=builder /ws/install /ws/install# 最终镜像不包含编译依赖，体积小得多

4.6 Docker 容器生命周期

5. ROS2 机器人命令

所有命令以 ros2 开头。查帮助：ros2 --help → ros2 <command> --help → ros2 <command> <verb> -h

5.1 环境加载

# 每个新终端都要source（建议写到 ~/.bashrc）source /opt/ros/humble/setup.bash          # 或 /opt/ros/jazzy/setup.bashsource install/setup.bash                  # 加载工作空间# ROS_DOMAIN_ID：多组机器通信隔离（默认0，范围0-232）export ROS_DOMAIN_ID=42echo "export ROS_DOMAIN_ID=42" >> ~/.bashrc

5.2 编译与包管理

colcon build --symlink-install             # 编译工作空间（Python改后自动生效）colcon build --packages-select my_pkg      # 只编译指定包colcon build --packages-up-to my_pkg       # 编译指定包及其依赖colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release  # Release模式编译ros2 pkg create --build-type ament_cmake my_cpp_pkg   # 创建C++包ros2 pkg create --build-type ament_python my_py_pkg   # 创建Python包ros2 pkg list                              # 查看所有包ros2 pkg list | grep my_                   # 过滤自己的包ros2 pkg executables my_pkg                # 查看包的可执行文件ros2 pkg prefix my_pkg                     # 查看包安装路径

5.3 节点

ros2 run my_pkg my_node                    # 运行节点ros2 run my_pkg my_node --ros-args -r __node:=new_name  # 重命名节点ros2 node list                             # 查看运行中节点ros2 node info /my_node                    # 查看节点拓扑（发布/订阅/服务）

5.4 话题 Topic

ros2 topic list                            # 查看所有话题ros2 topic list -t                         # 同时显示消息类型ros2 topic echo /scan                      # 实时打印话题数据ros2 topic echo /scan --no-arr             # 不打印数组内容（精简输出）ros2 topic info /scan                      # 查看话题类型+发布者+订阅者ros2 topic info /scan -v                   # 详细模式ros2 topic hz /scan                        # 查看发布频率ros2 topic bw /scan                        # 查看带宽占用ros2 topic find geometry_msgs/msg/Twist    # 按消息类型查找话题ros2 topic pub /cmd_vel geometry_msgs/msg/Twist \"{linear: {x: 0.5}, angular: {z: 0.1}}" -r 10  # 以10Hz发布速度指令

5.5 接口 Interface

ros2 interface list                        # 查看所有接口（msg/srv/action）ros2 interface list -m                     # 只看消息类型ros2 interface show std_msgs/msg/String    # 查看消息结构定义ros2 interface show nav2_msgs/action/NavigateToPose  # 查看动作定义ros2 interface proto geometry_msgs/msg/Twist  # 查看消息模板（方便写pub命令）

5.6 服务 Service

ros2 service list                          # 查看所有服务ros2 service list -t                       # 同时显示服务类型ros2 service type /clear                   # 查看服务类型ros2 service call /reset std_srvs/srv/Empty "{}"# 调用无参数服务ros2 service call /add_two_ints example_interfaces/srv/AddTwoInts \"{a: 3, b: 5}"# 调用带参数服务

5.7 动作 Action

ros2 action list                           # 查看所有动作ros2 action list -t                        # 同时显示动作类型ros2 action info /navigate_to_pose         # 查看动作详情ros2 action send_goal /navigate_to_pose \    nav2_msgs/action/NavigateToPose "{pose: {...}}" --feedback  # 发送目标+查看反馈

5.8 参数 Parameter

ros2 param list                            # 查看所有节点参数ros2 param list /my_node                   # 查看指定节点参数ros2 param get /my_node use_sim_time       # 获取参数值ros2 param set /my_node linear_scale 1.5   # 动态修改参数（无需重编译）ros2 param dump /my_node                   # 导出参数为YAMLros2 param dump /my_node --output-dir ./   # 导出到文件ros2 param describe /my_node param_name    # 查看参数描述（约束、范围等）

5.9 Launch 启动文件

ros2 launch my_pkg demo.launch.py          # 启动launch文件ros2 launch my_pkg demo.launch.py use_sim:=true# 传参ros2 launch --debug my_pkg demo.launch.py  # 调试模式（暂停等待调试器连接）

5.10 数据录制与回放 Bag

ros2 bag record -a                         # 录制所有话题ros2 bag record -o my_session /scan /tf    # 录制指定话题，指定输出名ros2 bag info my_session/                  # 查看bag信息ros2 bag play my_session/                  # 回放数据ros2 bag play my_session/ --rate 0.5       # 半速回放ros2 bag play my_session/ -l               # 循环回放

5.11 可视化与调试

rviz2                                      # 3D可视化（点云/轨迹/TF/模型）rqt_graph                                  # 节点-话题关系图rqt_plot                                   # 话题数据曲线图ros2 run tf2_ros tf2_echo map base_link    # 查看两个坐标系间变换ros2 run tf2_tools view_frames             # 生成TF树PDF

5.12 系统诊断与管理

ros2 doctor                                # 全面系统诊断（别名 ros2 wtf）ros2 doctor --report                       # 输出完整报告ros2 doctor --report-fail                  # 只看失败项ros2 daemon status                         # 守护进程状态ros2 daemon stop                           # 停止守护进程（网络切换后重置缓存）ros2 lifecycle list                        # 查看受控节点列表ros2 lifecycle set /node configure         # 将节点状态设为configureros2 lifecycle set /node activate          # 激活节点ros2 component types                       # 查看可用组件类型（高性能容器模式）

5.13 ROS2 三种通信机制对比

6. 场景速查表

每个典型场景对应一组命令，按执行顺序排列

7. 开发工作流全景

8. 常见问题排查

8.0 故障排查决策树

8.1 ros2: command not found

根源：没source环境。每个新终端都要：

source /opt/ros/humble/setup.bashsource install/setup.bash

一劳永逸：写到 ~/.bashrc：

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

8.2 Docker容器内无GPU

前提：宿主机 nvidia-smi 能正常输出。

# 1. 安装nvidia-container-toolkitsudo apt install nvidia-container-toolkit# 2. 运行时加 --gpus 参数docker run --gpus all ...# 3. 容器内验证docker exec -it ros_dev nvidia-smi

8.3 colcon build 找不到依赖

# 1. 先检查缺失的依赖rosdep check --from-paths src --ignore-src# 2. rosdep自动安装rosdep install --from-paths src --ignore-src -r -y# 3. 如果rosdep也不知道，手动搜索apt search ros-humble- | grep xxx

确保 package.xml 和 CMakeLists.txt 中声明的依赖正确。首次用 sudo rosdep init && rosdep update 初始化rosdep。

8.4 ROS2多机通信不通

# 1. 确认两台机器 ROS_DOMAIN_ID 一致echo $ROS_DOMAIN_ID# 2. 确认能ping通ping <对方IP># 3. 诊断ros2 doctor --report# 4. 如果用了Docker，确保 network_mode: host

8.5 串口设备无权限

# 把自己加入dialout组（重启后生效）sudo usermod -aG dialout $USER# 临时方案：直接改权限sudo chmod 666 /dev/ttyUSB0# 验证ls -la /dev/ttyUSB*

9. 常用工具速记