VSCode 调试 ROS1/ROS2 等项目完整指南

Robot_Nav2026-03-28 17:34

VSCode 调试 ROS1/ROS2 等项目完整指南

本文档详细介绍如何在 VSCode 中配置和调试 ROS1/ROS2 项目，包括 C++ 和 Python 节点的调试方法。

目录

  1. 安装必要扩展
  2. 工作空间准备
  3. [Debug 编译](#Debug 编译)
  4. [VSCode 配置文件](#VSCode 配置文件)
  5. 创建调试配置
  6. 启动调试
  7. 常见问题排查

1. 安装必要扩展

打开 VSCode，按 Ctrl+Shift+X 打开扩展面板，安装以下扩展：

1.1 ROS 相关扩展

扩展名称 扩展 ID 用途
ROS（已废弃） ms-iot.vscode-ros ROS 官方扩展，支持 ROS1/ROS2 调试
Robotics Developer Environment（下载这个即可） ms-iot.vscode-ros (同上) ROS 调试

1.2 C++ 开发扩展

扩展名称 扩展 ID 用途
C/C++ ms-vscode.cpptools C/C++ IntelliSense、调试支持
C/C++ Extension Pack ms-vscode.cpptools-extension-pack C++ 扩展合集
CMake twxs.cmake CMake 语法高亮和 IntelliSense
CMake Tools ms-vscode.cmake-tools CMake 项目支持

1.3 Python 开发扩展

扩展名称 扩展 ID 用途
Python ms-python.python Python 语言支持
Pylance ms-python.vscode-pylance Python 语言服务器（推荐）

1.4 ROS 文件语法高亮

扩展名称 扩展 ID 用途
Msg Language Support qiaofengsheng.msg-language-support .msg、.srv、.action 语法高亮
Txt Syntax gurumukhi.txt-syntax .txt 文件语法高亮

提示：安装完成后，建议重启 VSCode 以确保所有扩展正确加载。

2. 工作空间准备

2.1 打开工作空间

在 VSCode 中打开 ROS 工作空间：

bash 复制代码 
# ROS1
code ~/catkin_ws

# ROS2
code ~/ros2_ws

或者通过 VSCode 菜单：File → Open Folder 选择工作空间目录。

2.2 验证 ROS 环境

确保 ROS 环境已正确配置：

bash 复制代码 
# ROS1 - 检查环境变量
echo $ROS_DISTRO  # 应输出如：noetic
echo $ROS_ROOT    # 应输出如：/opt/ros/noetic/share/ros

# ROS2 - 检查环境变量
echo $ROS_DISTRO  # 应输出如：humble
echo $ROS_VERSION # 应输出：2

3. Debug 编译

3.1 Debug 编译

Debug 编译会包含调试符号信息，使调试器能够：

  • 在源代码中设置断点
  • 查看变量值
  • 单步执行代码

3.2 清理旧编译（可选）

如果之前是 Release 编译，建议先清理：

bash 复制代码 
# ROS1
cd ~/catkin_ws
rm -rf build/ devel/

# ROS2
cd ~/ros2_ws
rm -rf build/ install/ log/

3.3 执行 Debug 编译

方式一：终端编译（推荐）

ROS1:

bash 复制代码 
cd ~/catkin_ws
catkin_make -DCMAKE_BUILD_TYPE=Debug
# 或
catkin_make --cmake-args -DCMAKE_BUILD_TYPE=Debug

ROS2:

bash 复制代码 
cd ~/ros2_ws
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug
# 或仅编译特定包
colcon build --packages-select <package_name> --cmake-args -DCMAKE_BUILD_TYPE=Debug
方式二：VSCode 编译（ROS1）
  1. 按 Ctrl+Shift+P 打开命令面板
  2. 输入 catkin_make
  3. 选择 ROS: Create Catkin Package 或相关命令

3.4 验证 Debug 编译是否生效

编译完成后，检查可执行文件是否包含调试符号：

bash 复制代码 
# ROS1
file ~/catkin_ws/devel/lib/<package_name>/<node_name>

# ROS2
file ~/ros2_ws/install/<package_name>/lib/<package_name>/<node_name>

预期输出示例：

复制代码 
... ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=..., for GNU/Linux 3.2.0, with debug_info, not stripped

关键信息：with debug_info, not stripped 表示包含调试符号。

4. VSCode 配置文件

编译完成后，VSCode 通常会自动生成 .vscode 文件夹。如果没有生成，可以手动创建。

4.1 目录结构

复制代码 
ros_ws/
├── .vscode/
│   ├── c_cpp_properties.json    # C++ 编译器配置
│   ├── settings.json            # VSCode 设置
│   └── launch.json              # 调试配置
├── src/
│   └── ...
└── ...

4.2 c_cpp_properties.json（C++ 配置）

如果未自动生成，按 Ctrl+Shift+P，输入 C/C++: Edit Configurations (JSON) 创建。

ROS1 示例：

json 复制代码 
{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/src/**",
                "/opt/ros/noetic/include/**",
                "${workspaceFolder}/devel/include/**"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/g++",
            "cStandard": "c11",
            "cppStandard": "c++14",
            "intelliSenseMode": "linux-gcc-x64",
            "configurationProvider": "ms-vscode.cmake-tools"
        }
    ],
    "version": 4
}

ROS2 示例：

json 复制代码 
{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/src/**",
                "/opt/ros/humble/include/**",
                "${workspaceFolder}/install/**/include/**"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/g++",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64",
            "configurationProvider": "ms-vscode.cmake-tools"
        }
    ],
    "version": 4
}

4.3 settings.json（VSCode 设置）

json 复制代码 
{
    "python.autoComplete.extraPaths": [
        "/opt/ros/noetic/lib/python3/dist-packages"  // ROS1
        // "/opt/ros/humble/lib/python3.10/site-packages"  // ROS2
    ],
    "python.analysis.extraPaths": [
        "/opt/ros/noetic/lib/python3/dist-packages"  // ROS1
        // "/opt/ros/humble/lib/python3.10/site-packages"  // ROS2
    ],
    "ros.distro": "noetic",  // 或 "humble", "foxy" 等
    "C_Cpp.default.intelliSenseMode": "linux-gcc-x64",
    "C_Cpp.default.cppStandard": "c++14"
}

5. 创建调试配置

5.1 打开调试面板

点击左侧活动栏的调试图标（或按 Ctrl+Shift+D），然后点击 create a launch.json file。

5.2 选择调试环境

在弹出的选项中，选择 ROS 环境。

5.3 配置 launch.json

5.3.1 ROS Launch 调试（启动 launch 文件）

适用于通过 launch 文件启动多个节点的场景。

json 复制代码 
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "ROS: Launch",
            "type": "ros",
            "request": "launch",
            "target": "${workspaceFolder}/src/<package_name>/launch/<launch_file>.launch"
        }
    ]
}

ROS2 launch 文件：

json 复制代码 
{
    "name": "ROS2: Launch",
    "type": "ros",
    "request": "launch",
    "target": "${workspaceFolder}/src/<package_name>/launch/<launch_file>.py"
}
5.3.2 ROS Attach 调试（附加到运行中的进程）

适用于调试已经运行的节点。

json 复制代码 
{
    "name": "ROS: Attach",
    "type": "ros",
    "request": "attach"
}
5.3.3 C++ 单节点调试（不使用 launch 文件）
json 复制代码 
{
    "name": "C++: Debug Node",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/devel/lib/<package_name>/<node_name>",
    "args": [],
    "stopAtEntry": false,
    "cwd": "${workspaceFolder}",
    "environment": [
        {
            "name": "ROS_MASTER_URI",
            "value": "http://localhost:11311"
        }
    ],
    "externalConsole": false,
    "MIMode": "gdb",
    "setupCommands": [
        {
            "description": "Enable pretty-printing for gdb",
            "text": "-enable-pretty-printing",
            "ignoreFailures": true
        }
    ],
    "preLaunchTask": "catkin_make"  // 可选：调试前自动编译
}
5.3.4 Python 节点调试
json 复制代码 
{
    "name": "Python: Debug Node",
    "type": "python",
    "request": "launch",
    "program": "${workspaceFolder}/src/<package_name>/scripts/<script_name>.py",
    "console": "integratedTerminal",
    "cwd": "${workspaceFolder}",
    "env": {
        "PYTHONPATH": "${workspaceFolder}/devel/lib/python3/dist-packages:/opt/ros/noetic/lib/python3/dist-packages"
    }
}
5.3.5 完整配置示例
json 复制代码 
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "ROS: Launch",
            "type": "ros",
            "request": "launch",
            "target": "${workspaceFolder}/src/my_package/launch/my_launch.launch"
        },
        {
            "name": "ROS: Attach",
            "type": "ros",
            "request": "attach"
        },
        {
            "name": "C++: Single Node",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/devel/lib/my_package/my_node",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        },
        {
            "name": "Python: Node",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/src/my_package/scripts/my_script.py",
            "console": "integratedTerminal"
        }
    ]
}

6. 启动调试

6.1 设置断点

在源代码中点击行号左侧的空白处，设置断点（红色圆点）。

6.2 选择调试配置

  1. 点击左侧调试图标（Ctrl+Shift+D）
  2. 在顶部下拉菜单中选择要使用的调试配置（如 ROS: Launch）

6.3 开始调试

点击绿色的开始调试按钮（或按 F5）。

6.4 调试快捷键

快捷键 功能
F5 开始/继续调试
F9 切换断点
F10 单步跳过（Step Over）
F11 单步进入（Step Into）
Shift+F11 单步跳出（Step Out）
Shift+F5 停止调试
Ctrl+Shift+F5 重新启动调试

7. 常见问题排查

7.1 断点不生效

可能原因：

  • 未使用 Debug 模式编译
  • 源代码与编译的二进制文件不匹配
  • 调试符号被剥离

解决方法：

bash 复制代码 
# 重新进行 Debug 编译
catkin_make clean  # ROS1
catkin_make -DCMAKE_BUILD_TYPE=Debug

# 或 ROS2
rm -rf build/ install/
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug

7.2 找不到 ROS 头文件

解决方法：

检查 c_cpp_properties.json 中的 includePath 是否包含 ROS 安装路径：

json 复制代码 
"includePath": [
    "/opt/ros/noetic/include/**",  // 根据实际 ROS 版本修改
    "${workspaceFolder}/src/**"
]

7.3 Python 调试时模块找不到

解决方法：

在 launch.json 中设置 PYTHONPATH：

json 复制代码 
"env": {
    "PYTHONPATH": "/opt/ros/noetic/lib/python3/dist-packages:${workspaceFolder}/devel/lib/python3/dist-packages"
}

7.4 ROS2 调试无响应

解决方法：

  1. 确保已 source ROS2 环境：

    bash 复制代码 
    source /opt/ros/humble/setup.bash

  2. 检查 ros.distro 设置是否正确

  3. 尝试使用 Attach 模式调试

7.5 GDB 权限问题

如果出现 ptrace: Operation not permitted 错误：

bash 复制代码 
# 临时解决（当前终端有效）
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

# 永久解决
sudo echo "kernel.yama.ptrace_scope = 0" >> /etc/sysctl.d/10-ptrace.conf
sudo sysctl --system

参考链接

附录：快速检查清单

调试前请确认：

  • 所有必要扩展已安装并启用
  • 工作空间已正确打开
  • ROS 环境已 source（echo $ROS_DISTRO 有输出）
  • 使用 Debug 模式重新编译
  • 验证二进制文件包含调试符号（file 命令）
  • .vscode 文件夹和配置文件已创建
  • launch.json 中的路径正确
  • 断点设置在正确的位置

Author : Robot-Nav

Date : 2026-03-27

相关推荐
铮铭2 小时前
上海交大 RoboClaw VS EmbodiedAgentsSys 两个框架对比分析
人工智能·机器人·ai编程·具身智能·vla
机器觉醒时代2 小时前
智元机器人赛事官方解读：双赛道升级，以开源生态共推具身智能落地
机器人·开源·具身智能·智元机器人
hans汉斯2 小时前
《人工智能与机器人研究》期刊推介&征稿指南
人工智能·机器人
pacong4 小时前
vscode使用
javascript·vue.js·vscode
朗宇芯工控5 小时前
机器人示教器如何使用按键旋钮的功能
机器人·自动化·制造·运动控制系统·机械手
沫儿笙5 小时前
Kasawaki川崎焊接机器人智能气阀
人工智能·物联网·机器人
qq_283720056 小时前
VSCode 编译 Qt 5.12 QML 完整教程（Windows + MinGW）
windows·vscode·qt
EmbededCoder7 小时前
基于红外引导的轮式机器人自动回充
机器人·红外回充
小草cys7 小时前
轮足机器人无法直立的原因，哎
单片机·嵌入式硬件·机器人
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）07UV安装并设置国内源08Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南09OpenClaw 使用和管理 MCP 完全指南10中国象棋-html版本