【无标题】

2401_84208145

229人浏览 · 2026-08-26 00:01:34

2401_84208145 · 2026-08-26 00:01:34 发布

ROS2 Humble 学习笔记：从零到第一个 C++ 节点的踩坑与总结

引言

作为一名机器人爱好者，我最近开始学习 ROS2，选择了在 Ubuntu 22.04 上安装 ROS2 Humble（长期支持版）。学习过程中遇到了不少问题，从系统语言设置、输入法，到 VS Code 终端崩溃，再到编译第一个 C++ 节点时的一连串错误。本文将详细记录我踩过的每一个坑以及解决方案，希望能帮助初学者少走弯路，同时加深对 ROS2 构建系统和节点机制的理解。

一、环境准备：安装 ROS2 Humble

1.1 系统要求

Ubuntu 22.04（Jammy）
至少 4GB 内存，建议 8GB 以上
稳定的网络

1.2 安装步骤（精简版）

# 设置 locale 为 UTF-8
sudo apt update && sudo apt install -y 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

# 添加 ROS2 软件源
sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install -y curl
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# 安装桌面版
sudo apt update
sudo apt install -y ros-humble-desktop

# 设置环境变量
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

# 安装开发工具
sudo apt install -y python3-colcon-common-extensions python3-rosdep
sudo rosdep init
rosdep update

验证安装：

ros2 doctor

或运行两个示例节点：

# 终端1
ros2 run demo_nodes_cpp talker
# 终端2
ros2 run demo_nodes_cpp listener

如果终端2能收到消息，说明安装成功。

二、中文环境与输入法问题

2.1 现象

安装完系统后，界面和右键菜单是英文，且无中文输入法。

2.2 排查与解决

检查 /etc/default/locale 文件，发现 LANG 正确但 LC_ALL=en_US.UTF-8 覆盖了中文设置。

解决方法：

sudo update-locale LANG=zh_CN.UTF-8 LC_ALL=zh_CN.UTF-8

或者直接编辑 /etc/default/locale：

sudo sed -i 's/LC_ALL=en_US.UTF-8/LC_ALL=zh_CN.UTF-8/' /etc/default/locale

注销重新登录后界面恢复中文。

安装 IBus 拼音输入法：

sudo apt install ibus ibus-pinyin
im-config -n ibus
ibus restart

在“设置 → 区域与语言 → 输入源”中添加“汉语 (Pinyin)”，切换快捷键为 Super + Space。

三、VS Code 安装与终端问题

3.1 安装

使用 Snap 安装：

sudo snap install --classic code

安装 ROS 扩展（ROS、Python、C/C++、CMake Tools 等）。

3.2 VS Code 内置终端启动失败

现象：在 VS Code 中使用 CMake 生成任务时，提示“终端进程启动失败(退出代码: -1)”。

原因：VS Code 终端配置异常或 shell 路径错误。

解决：

检查 settings.json 中是否有过时的 terminal.integrated.shell.linux 配置，删除或改为 bash。
确认系统 shell 正常：echo $SHELL。
重启 VS Code。
或者干脆使用外部终端进行编译，VS Code 仅用于编辑代码。

四、创建工作空间与 ROS1/ROS2 命令区别

4.1 ROS1 vs ROS2 核心差异

功能	ROS1	ROS2
构建工具	`catkin_make`	`colcon build`
工作空间目录名	通常 `catkin_ws`	通常 `ros2_ws`
启动主节点	`roscore`	不需要
运行节点	`rosrun`	`ros2 run`
启动 launch	`roslaunch`	`ros2 launch`
创建包	`catkin_create_pkg`	`ros2 pkg create`

注意：ROS2 没有 roscore，节点间通过 DDS 自动发现，无需中央节点。

4.2 创建工作空间

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

编译空工作空间也是成功的，会生成 build/install/log 目录。

五、仿真机器人包 wpr_simulation2 安装与启动

5.1 克隆并编译

cd ~/ros2_ws/src
git clone https://github.com/6-robot/wpr_simulation2.git
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build

5.2 启动仿真环境

source ~/ros2_ws/install/setup.bash
ros2 launch wpr_simulation2 wpb_simple.launch.py

5.3 控制机器人

键盘控制：
```
ros2 run teleop_twist_keyboard teleop_twist_keyboard
```
重要：运行后要点击该终端窗口使其获得焦点，否则键盘输入无效。

鼠标控制（GUI）：

sudo apt install ros-humble-rqt-robot-steering
ros2 run rqt_robot_steering rqt_robot_steering

两者都向 /cmd_vel 话题发布 Twist 消息。

六、创建第一个 C++ 功能包

6.1 创建包

cd ~/ros2_ws/src
ros2 pkg create my_cpp_pkg --build-type ament_cmake --dependencies rclcpp std_msgs

6.2 包结构

my_cpp_pkg/
├── CMakeLists.txt
├── package.xml
├── include/
│   └── my_cpp_pkg/
└── src/          # 存放 .cpp 文件

6.3 编写简单的 C++ 节点

在 src/chao_node.cpp 中写入：

#include "rclcpp/rclcpp.hpp"

int main(int argc, char ** argv)
{
    rclcpp::init(argc, argv);
    auto node = rclcpp::Node::make_shared("chao_node");
    RCLCPP_INFO(node->get_logger(), "hello world!");
    rclcpp::shutdown();
    return 0;
}

七、编译错误汇总与解决方案

7.1 拼写错误

现象：

error: ‘ptintf’ was not declared in this scope

原因：printf 拼写错误，eorld 拼写错误。
解决：仔细检查每个单词，推荐使用 IDE 的自动补全。

7.2 缺少分号

现象：

error: expected ‘;’ before ‘return’

解决：在 printf("...") 后添加分号。

7.3 CMakeLists.txt 中 `add_executable` 位置错误

现象：编译成功但 ros2 run 提示 No executable found。
原因：add_executable 被放在了 ament_package() 之后，导致 CMake 未生成可执行文件。
解决：将 add_executable 和 ament_target_dependencies 移到 ament_package() 之前。

7.4 缺少 install 规则

现象：编译看似成功，但 install/my_cpp_pkg/lib/ 目录为空，ros2 run 找不到可执行文件。
解决：在 CMakeLists.txt 中添加：

install(TARGETS
  chao_node
  DESTINATION lib/${PROJECT_NAME})

7.5 CMakeLists.txt 中出现多余字符

现象：

Parse error. Expected "(", got unquoted argument with text ">".

原因：使用 cat > file << 'EOF' 时，结束符 EOF 没有单独一行，或复制内容时带入终端提示符等。
解决：使用 nano 手动清空文件并重新输入正确内容，确保最后一行是 ament_package()，无多余字符。

八、问题排查思路总结

先看终端报错：错误信息通常会指出文件名、行号、错误类型。
检查文件内容：使用 cat 或 nano 查看源文件和 CMakeLists.txt 是否如预期。
关注环境变量：确保每次新终端都 source /opt/ros/humble/setup.bash 和 source ~/ros2_ws/install/setup.bash。
理解构建流程：colcon build 会调用 CMake，生成可执行文件并安装到 install 目录，ros2 run 从那里查找。
不要害怕错误：每个错误都是一次学习机会，解决后理解会更深刻。