概述

ROS 2 的 Python 节点不会像 C++ 一样编译成二进制程序。

Python package 执行：

colcon build

主要作用是：

安装 package
注册 ros2 run 入口
安装 package.xml、resource、launch、config 等元信息
生成 install/setup.bash 对应的环境信息

所以这里的 build 本质是：安装 + 注册

不是传统意义上的编译。

基本流程

• 初始化

# 创建 workspace：
mkdir -p ~/robot_ws/src
cd ~/robot_ws/src
# 如果没有写入 .bashrc，每个新终端都要先 source ROS 2 环境
source /opt/ros/$ROS_DISTRO/setup.bash
# 创建 Python package：
cd ~/ros2_ws/src
# 如果这个指令中没有写完全依赖，后续需要在package.xml中补全
ros2 pkg create my_first_pkg --build-type ament_python --dependencies rclpy
# 创建节点文件
cd ~/ros2_ws/src/my_first_pkg/my_first_pkg
touch hello_node.py
chmod +x hello_node.py

• 编写节点程序 略

• 配置 package.xml
  如果创建功能包时没有写全依赖，在 package.xml 中声明依赖：

<exec_depend>rclpy</exec_depend>
<exec_depend>std_msgs</exec_depend>

• 配置 setup.py 注册节点

vim ~/ros2_ws/src/my_first_pkg/setup.py
# 将 entry_points 字段改成：
# 格式：ros2 run 时的名字 = Python包名.文件名:main函数
entry_points={
    'console_scripts': [
        'hello_node = my_first_pkg.hello_node:main',
    ],
},
# 保存退出

• 编译并运行

# 编译工作区
cd ~/ros2_ws
# （可选）根据package.xml自动安装依赖
# rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
# source 工作区环境
source install/setup.bash
# 运行节点
ros2 run my_first_pkg hello_node
# ctrl c 终止节点

• 验证：

ros2 node list
ros2 topic list
ros2 topic echo /chatter

--symlink-install参数

开发阶段建议固定使用：

colcon build --symlink-install

该指令会编译当前工作空间中的所有功能包，但是功能包中的节点是否被编译/注册安装，c++取决于CMakelists, python取决于setup.py的

entry_points={
    'console_scripts': [
        'talker = my_pkg.talker:main',
        'listener = my_pkg.listener:main',
    ],
},

没写进console_scripts，就不会被注册安装，也不能用ros2 run找到

普通 build 可能会把 Python 文件复制到 install/ 目录。修改 src/ 下的 .py 文件后，运行时仍可能使用旧代码。

--symlink-install 会尽量让 install/ 中的 Python 文件链接到 src/ 源码。这样只修改已有 .py 业务代码时，通常不需要重新 build，只需要重启节点。

不需要重新 build 的情况

前提：

colcon build --symlink-install
source install/setup.bash

通常不需要重新 build 的修改：

修改已有 .py 文件中的业务逻辑
修改回调函数内部实现
修改日志内容
修改 topic 名
修改 timer 周期
修改普通算法逻辑

操作方式：

# 停止旧节点后重新运行
ros2 run my_py_pkg talker

必须重新 build 的情况

以下情况必须重新 build：

第一次创建 package
修改 setup.py
修改 package.xml
新增或修改 entry_points
新增 ros2 run 可执行入口
新增依赖
新增或修改 .msg/.srv/.action
新增 launch/config 文件安装规则
清理过 build/ install/ log/
未使用 --symlink-install 后修改 .py 文件

通用命令：

cd ~/robot_ws
colcon build --symlink-install
source install/setup.bash

修改自定义接口，并且其他包依赖该接口时：

colcon build --symlink-install --packages-up-to <使用该接口的包>
source install/setup.bash

判断表

修改内容	是否需要重新 build
只改已有 .py 业务代码	通常不需要
修改日志文本	通常不需要
修改回调内部逻辑	通常不需要
修改 topic 名	通常不需要
修改 timer 周期	通常不需要
修改 setup.py	需要
修改 package.xml	需要
新增 entry_points	需要
新增节点入口	需要
新增依赖	需要
修改 .msg/.srv/.action	需要
修改 launch/config 安装规则	需要
删除 build/ install/ log/	需要
未使用 --symlink-install 后修改 .py	通常需要

规则总结

Python 节点本身不编译成二进制。
colcon build 负责安装和注册 Python package。
开发阶段使用 colcon build --symlink-install。
只改已有 .py 业务代码，通常不需要重新 build。
修改 package 元信息、入口、依赖、接口或安装规则，必须重新 build。