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

相关推荐
weixin_513449965 小时前
PCA、SVD 、 ICP 、kd-tree算法的简单整理总结
c++·人工智能·学习·算法·机器人
dyxal8 小时前
VS Code 终端疑难杂症排查：为什么 PowerShell 无法启动？
vscode
这个昵称叫什么好呢8 小时前
nvidia显卡驱动升级造成的无法开机（黑屏）问题
机器人
【ql君】qlexcel8 小时前
Visual Studio Code开发STM32设置头文件宏定义uint32_t报错
vscode·stm32·vs code·头文件宏定义·uint32_t报错·uint8_t报错·uint16_t报错
琉璃榴9 小时前
Visual Studio Code连接远程服务器
服务器·vscode·github
jieyucx10 小时前
Golang 完整安装与 VSCode 开发环境搭建教程
开发语言·vscode·golang
施努卡机器视觉11 小时前
阴极铜机器人剥片：SNK施努卡的双线并行自动化解决方案
运维·机器人·自动化
Olivia0514051412 小时前
Voohu：音频变压器在平衡传输与地环路隔离中的设计要点
网络·机器人·信息与通信
wWYy.12 小时前
ROS:服务机制(Service)
机器人
好家伙VCC12 小时前
# 发散创新：用 Rust实现高性能物理引擎的底层架构设计与实战在游戏开发、虚拟仿真和机器人控
java·开发语言·python·rust·机器人
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点032026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free04AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析05零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）06GPT-6发布日深度解析-Symphony架构200万Token实战07从零部署 Hermes Agent：一只"会成长的 AI 马"保姆级安装教程08一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛09从限购到畅通：GLM-5.1 Coding Plan接入攻略10基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南