机器人 / 系统课时
注册入口并通过 ros2 run 启动
注册入口并通过 ros2 run 启动
Python 节点能运行,不代表 ros2 run 能找到它。ROS 2 查找的是安装后的入口脚本,而非源码文件。本篇用 Jazzy 的 ament_python 包演示注册、构建、启动与排错。
学习目标
- 区分功能包名、
console_scripts可执行名、Python 模块与main()函数。 - 正确设置
setup.py、检查setup.cfg,并使用colcon build和ros2 run验收入口。 - 根据“找不到可执行文件”和 Python 导入异常选择不同的修复方向。
准备功能包与最小节点
先确认系统已安装 Jazzy 与 colcon。本例在 Bash 终端新建 py_nodes 包,假定 ~/ros2_ws/src/py_nodes 尚不存在;若已有同名包,直接沿用并检查它的构建类型是否为 ament_python。
source /opt/ros/jazzy/setup.bash
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
ros2 pkg create --build-type ament_python --license Apache-2.0 py_nodes --dependencies rclpy预期结果:命令成功创建 ~/ros2_ws/src/py_nodes/,其中包含 package.xml、setup.py、setup.cfg、resource/py_nodes 和 py_nodes/__init__.py。实际创建提示与终端路径可能不同。
在 ~/ros2_ws/src/py_nodes/py_nodes/hello_node.py 新建以下完整文件。这里让节点只输出一条日志并立即退出,便于判断 main() 是否真正被入口调用。
import rclpy
from rclpy.node import Node
def main(args=None):
rclpy.init(args=args)
node = Node('hello_node')
try:
# 使用 ROS 日志而不是普通 print,验证节点已正常初始化
node.get_logger().info('console_scripts is working')
finally:
# 短生命周期示例必须主动释放 ROS 资源
node.destroy_node()
rclpy.shutdown()
if __name__ == '__main__':
main()预期结果:保存源码不会产生终端输出;通过后面的 ros2 run 启动时会打印 console_scripts is working 并退出。由于进程很快结束,通常无法靠 ros2 node list 捕获它,应以日志验收。
在 setup.py 注册可执行入口
将新建包的 setup.py 改为以下完整内容。console_scripts 等号左侧是交给 ros2 run 的可执行名;右侧 py_nodes.hello_node:main 表示导入 Python 模块 py_nodes.hello_node 并调用其中的 main()。
from setuptools import find_packages, setup
package_name = 'py_nodes'
setup(
name=package_name,
version='0.0.0',
packages=find_packages(exclude=['test']),
data_files=[
# ament 索引负责让 ROS 2 找到已安装的功能包
('share/ament_index/resource_index/packages', ['resource/' + package_name]),
('share/' + package_name, ['package.xml']),
],
install_requires=['setuptools'],
zip_safe=True,
maintainer='ros2_learner',
maintainer_email='maintainer@example.com',
description='Minimal rclpy console entry example',
license='Apache-2.0',
entry_points={
'console_scripts': [
# 可执行名 = Python 包.模块:函数
'hello_node = py_nodes.hello_node:main',
],
},
)生效行为:下一次构建会安装名为 hello_node 的入口包装脚本,后续用 ros2 pkg executables py_nodes 验证。maintainer 和 maintainer_email 是示例元数据,实际项目请替换;resource/py_nodes 与声明 rclpy 依赖的 package.xml 必须保留。源码 .py 不需要额外执行 chmod +x。
再确认自动生成的 setup.cfg 包含以下配置。它告诉安装器把入口脚本放到 ROS 2 预期的 lib/py_nodes 目录,而不是普通的 bin 目录。
[develop]
script_dir=$base/lib/py_nodes
[install]
install_scripts=$base/lib/py_nodes生效行为:构建时入口脚本会安装到功能包的 lib/py_nodes 下;下面通过命令查询可执行入口是否存在。

重新构建并验证 ros2 run
从工作空间根目录构建,而不是在 Python 模块目录执行 colcon。修改 setup.py 中的入口映射后必须重新构建;即使使用 --symlink-install,入口元数据变化也不能仅靠保存源码生效。
cd ~/ros2_ws
colcon build --packages-select py_nodes
source install/setup.bash
ros2 pkg executables py_nodes预期输出(构建耗时是动态值,记作 <TIME>;此处只展示关键行):
Starting >>> py_nodes
Finished <<< py_nodes [<TIME>]
Summary: 1 package finished [<TIME>]
py_nodes hello_node最后一行是判断入口是否已注册的直接证据。py_nodes 是功能包名,hello_node 是可执行入口名;两者与 Python 文件名并不要求一致,只须与入口映射对应。
ros2 run py_nodes hello_node预期输出(日志时间戳因运行环境不同,以 <TIME> 代替):
[INFO] [<TIME>] [hello_node]: console_scripts is working该命令正常打印一次日志并退出,说明已成功从 ROS 2 功能包定位可执行入口、导入模块并调用 main()。
根据报错定位入口问题
不要把“找不到可执行文件”和“找不到 Python 模块”当成一类故障。先看 ros2 pkg executables py_nodes 是否列出了入口,再判断错误发生在入口发现阶段,还是入口启动后的 Python 导入阶段。
| 现象 | 优先检查 | 修复方法 |
|---|---|---|
Package 'py_nodes' not found |
工作空间是否构建、终端是否加载 install/setup.bash |
在工作空间根目录构建并重新 source |
No executable found |
setup.py 的 console_scripts、setup.cfg 的 lib/py_nodes 路径 |
核对入口名,重新构建并加载工作空间 |
ModuleNotFoundError |
是否存在 py_nodes/py_nodes/hello_node.py,模块路径是否拼错 |
修正等号右侧的模块路径并重建 |
AttributeError 提示找不到 main |
模块中是否定义了顶层 def main(args=None) |
补齐函数或修正冒号后的名称并重建 |
例如注册名是 hello_node,却执行 ros2 run py_nodes hello,也会遇到 No executable found;应修正执行名,而不是改节点名称。如果工作空间存在多个同名功能包,还要检查 ros2 pkg prefix py_nodes 指向哪里:它应返回当前工作空间的安装前缀,而不是另一份旧包。入口能够列出却启动失败时,优先排查模块与函数;入口连列出都做不到时,优先排查注册、构建与环境加载。