摘要本文基于 WSL 2 Ubuntu 24.04 ROS 2 Jazzy 环境从零搭建 Python 版首个 ROS 2 节点。内容涵盖前置环境确认、工作空间构建、功能包创建、发布节点编写、节点入口注册、编译校验及话题通信全链路验证。全程开启--symlink-install软链接模式修改 Python 代码无需重新编译重启节点即可生效实测零坑、100% 跑通。前言很多刚接触 ROS 2 的开发者在 WSL 环境下创建 Python 功能包时很容易遇到参数报错、节点找不到、编译失败等问题。本篇笔记是我在 WSL 2 Ubuntu 24.04 ROS 2 Jazzy 环境下实际踩坑后跑通的全流程每一条命令都经过实际验证全程没有任何无效步骤跟着走就能 100% 得到一个可运行的首个 Python ROS 2 节点。一、前置环境确认先确保你已经提前完成 ROS 2 Jazzy 的基础环境安装执行以下命令确认环境正常source/opt/ros/jazzy/setup.bashecho$ROS_DISTRO正常输出jazzy就代表基础环境就绪。二、构建自定义工作空间我们从零搭建标准 ROS 2 工作空间同时开启 Python 调试最实用的软链接模式后续修改 Python 代码完全不用重复编译直接重启节点就能看到效果。本文统一使用/home/zz/ros2作为工作空间根目录# 进入自定义开发根目录你可以改成自己习惯的路径cd/home/zz/ros2# 彻底清除旧的残留构建文件避免新旧代码冲突rm-rfbuildinstalllog# 创建标准的 ROS 2 源码目录mkdir-psrc# 首次构建工作空间开启--symlink-install软链接模式colcon build --symlink-install# 激活当前工作空间的运行环境sourceinstall/setup.bash三、创建 Python 类型 ROS 2 功能包这里有一个 ROS 2 Jazzy 的经典参数坑直接按常规顺序写命令会报error: the following arguments are required: package_name的错误。我们调整参数顺序在依赖参数末尾加上--分隔符明确告诉命令行工具后面的内容就是功能包名称。先进入工作空间的src目录cdsrc ros2 pkg create --build-type ament_python--dependenciesrclpy std_msgs -- my_first_pkg执行成功后终端输出提示Creating package my_first_pkg代表 Python 类型功能包生成完成。如果你本地已经存在同名的my_first_pkg文件夹又不想删除重建可以直接进入已有的目录继续后续步骤无需覆盖原有文件。四、编写首个 Python 发布节点进入功能包内的 Python 源码目录my_first_pkg/my_first_pkg新建发布者节点文件cdmy_first_pkg/my_first_pkgnanosimple_publisher.py粘贴以下完整代码实现每秒向/my_topic话题发布一条消息的逻辑importrclpyfromrclpy.nodeimportNodefromstd_msgs.msgimportStringclassMyPublisher(Node):def__init__(self):super().__init__(my_publisher)# 定义发布者话题名my_topic消息类型String队列长度10self.publisherself.create_publisher(String,my_topic,10)# 创建1秒触发一次的定时器self.timerself.create_timer(1.0,self.timer_callback)deftimer_callback(self):msgString()msg.dataHello from WSL!self.publisher.publish(msg)self.get_logger().info(Publishing: %s%msg.data)defmain(argsNone):rclpy.init(argsargs)nodeMyPublisher()rclpy.spin(node)rclpy.shutdown()if__name____main__:main()保存退出编辑器。五、注册节点入口让 ROS 2 能找到你的自定义节点回到功能包根目录my_first_pkg/打开setup.py文件在entry_points的console_scripts部分添加节点启动声明cd..nanosetup.py把原有entry_points部分替换为下面内容entry_points{console_scripts:[simple_publisher my_first_pkg.simple_publisher:main,],},保存文件节点入口就配置完成。六、编译功能包并全链路校验回到工作空间根目录针对性编译my_first_pkg包cd/home/zz/ros2 colcon build --symlink-install --packages-select my_first_pkg正常 1~2 秒就能编译完成输出Summary: 1 package finished代表编译成功。接下来执行 3 条校验命令确认所有环节全部正常确认 ROS 2 系统能识别到自定义功能包sourceinstall/setup.bash ros2 pkg list|grepmy_first_pkg输出my_first_pkg即代表注册成功。确认节点可执行文件已被正确识别ros2 pkg executables my_first_pkg输出my_first_pkg simple_publisher即代表节点入口配置正确。直接运行你的首个 Python ROS 2 节点ros2 run my_first_pkg simple_publisher终端会每秒打印一条发布日志你的第一个自定义节点已经成功运行。七、通信全链路验证新开一个 WSL 终端执行环境激活命令后监听话题消息确认发布订阅通信正常source/opt/ros/jazzy/setup.bashcd/home/zz/ros2sourceinstall/setup.bash ros2 topicecho/my_topic终端会持续收到节点发布的Hello from WSL!消息代表完整的 ROS 2 Python 话题通信 Demo 100% 跑通。后续调试提示因为我们开启了--symlink-install软链接模式后续你直接修改simple_publisher.py里的任何代码不需要重新执行colcon build重启节点就能直接看到修改后的效果Python 开发调试效率直接拉满。