--- title: ROS2系列教程：Xacro参数化建模 categories: - ROS2 date: 2026-09-06 10:18:11 desc: 回顾上一篇的差速小车，你实际感受到了：Xacro 是 URDF 的超集：一个合法的 Xacro 文件经过命令展开后，得到的是标准 URDF。它新增的能力：ROS2 中由同名包提供，启动时用… abbrlink: ros2-xi-lie-jiao-cheng-xacro-can-shu-hua-jian-mo --- ## 本文是 ROS2 系列教程的第 17 篇 > 本文是 ROS2 系列教程的第 17 篇：Xacro 参数化建模。上一篇我们用 URDF 写了一个差速小车，但你一定已经发现痛点：两个驱动轮的 link/joint 代码几乎一模一样，改一个轮径要改五处；机械臂 6 个关节更是噩梦。Xacro（XML Macros，XML 宏）就是为了消灭这种重复而生的。它在 URDF 之上增加宏、属性、数学表达式与条件分支，先"展开"成标准 URDF 再被下游工具消费。本篇讲透 Xacro 的三大法宝（属性/宏/表达式），把小车和六关节机械臂的建模效率提升一个数量级。学完你就能用十几行代码生成几百行 URDF。 ### 一、为什么需要 Xacro #### 1.1 URDF 的三大痛点回顾上一篇的差速小车，你实际感受到了： 1. **重复**：两个驱动轮各 40 行代码，几乎一样，只差 `name` 和 `origin` 的 y 值。 2. **不可计算**：轮子轴心高度 `-0.06`、雷达高度 `0.12` 是手算的，一旦改底盘厚度，所有位置要重新心算。 3. **不可参数化**：想生成"同一型号不同轮距"的多个变体，只能复制整个文件再手改。 #### 1.2 Xacro 是什么 Xacro 是 URDF 的**超集**：一个合法的 Xacro 文件经过 `xacro` 命令展开后，得到的是标准 URDF。它新增的能力： | 能力 | 关键字 | 作用 | | --- | --- | --- | | 属性 | `` | 定义常量，一处修改全局生效 | | 宏 | `` | 定义可复用代码块，带参数 | | 数学表达式 | `${...}` | 在属性值里做四则运算 | | 条件分支 | `` / `` | 按属性值决定是否输出某段 | ROS2 中 `xacro` 由同名包提供，启动时用 `Command(['xacro ', xacro_file])` 展开（见 5.1 节）。 #### 1.3 展开命令 ```bash # 把 xacro 展开成 urdf xacro demo_car.xacro > demo_car.urdf # 传参展开（后面讲宏参数） xacro robot.xacro wheel_radius:=0.10 # 直接打印到终端检查 xacro demo_car.xacro ``` `xacro` 展开不依赖 ROS 运行时，纯命令行即可调试。 ### 二、属性（property）：消灭魔法数字 #### 2.1 基础用法 ```xml ``` `${...}` 里可以直接写表达式： ```xml ``` #### 2.2 属性值类型 Xacro 属性自动按上下文解释，常用类型： | 类型 | 写法 | 示例 | | --- | --- | --- | | 数字 | `value="0.45"` | 直接写 | | 字符串 | `value="red"` | 直接写 | | 布尔 | `value="true"` | true/false | | 数学 | `${a+b}` | 加/减/乘/除/取模，支持括号嵌套 | **注意**：`${}` 里的表达式用 Python 语法求值（Xacro 由 Python 实现），所以可以调用 `pi`、`cos` 等： ```xml ``` ### 三、宏（macro）：一次定义，处处复用宏是 Xacro 的核心。它把一段"模板"封装成带参数的可复用单元。 #### 3.1 宏的基本结构 ```xml ``` #### 3.2 调用宏 ```xml ``` 展开后等价于上一篇手写的两套 link/joint，但代码量从 80 行降到 20 行，且改 `wheel_radius` 一处全局生效。 #### 3.3 宏参数的高级用法参数可以带默认值、可以是布尔： ```xml ... ``` 调用时按需覆盖： ```xml ``` #### 3.4 块参数（block）宏还可以接受一段 XML 作为参数（类似函数回调），用于注入不同内容： ```xml ${block} ``` ### 四、条件与循环：让模型"长出来" #### 4.1 xacro:if 条件包含 ```xml ``` `include_lidar=false` 时整段不输出。这在"同一个模型文件，仿真/真机/仅显示"切换时极其有用。 #### 4.2 用宏模拟循环 Xacro 没有原生 for 循环，但可以用"宏 + 参数"递归或直接调用多次。机械臂 6 个关节最实用的写法是**复用同一个关节宏**： ```xml ``` 要生成 10 个关节？复制 4 行即可。这就是宏的威力。 ### 五、完整示例：Xacro 版差速小车 #### 5.1 完整文件（demo_car.xacro） ```xml ``` #### 5.2 展开并验证 ```bash # 1. 展开成 URDF xacro demo_car.xacro > demo_car.urdf # 2. 用 check_urdf 验证结构 check_urdf demo_car.urdf ``` 预期输出： ```text robot name is: demo_car ---------- Successfully Parsed XML --------------- root Link: base_link has 7 child(ren) child(1): wheel_1 child(2): wheel_-1 child(3): lidar child(4): caster_1_1 ... ``` **对比记忆**：手写 URDF 版约 150 行，Xacro 版约 90 行且更易维护；若再加一个相机，只需 10 行。 #### 5.3 在 RViz 中查看（复用 launch） ```python # display.launch.py from launch import LaunchDescription from launch_ros.actions import Node from launch.actions import DeclareLaunchArgument from launch.substitutions import LaunchConfiguration, Command import os from ament_index_python.packages import get_package_share_directory def generate_launch_description(): pkg_share = get_package_share_directory('my_robot_description') xacro_file = os.path.join(pkg_share, 'urdf', 'demo_car.xacro') return LaunchDescription([ DeclareLaunchArgument('use_sim_time', default_value='false'), Node( package='robot_state_publisher', executable='robot_state_publisher', # 关键：用 xacro 命令展开 parameters=[{'robot_description': Command(['xacro ', xacro_file])}], output='screen'), Node( package='joint_state_publisher_gui', executable='joint_state_publisher_gui', output='screen'), ]) ``` ```bash ros2 launch my_robot_description display.launch.py rviz2 # 添加 RobotModel + TF，Fixed Frame = base_link ``` #### 5.4 命令行传参切换配置把 `include_lidar` 设为 launch 参数，实现"一个文件多种配置"： ```python from launch.actions import DeclareLaunchArgument from launch.substitutions import LaunchConfiguration, Command def generate_launch_description(): include_lidar = LaunchConfiguration('include_lidar', default='true') return LaunchDescription([ DeclareLaunchArgument('include_lidar', default_value='true'), Node( package='robot_state_publisher', executable='robot_state_publisher', parameters=[{'robot_description': Command( ['xacro ', os.path.join(pkg_share, 'urdf', 'demo_car.xacro'), ' include_lidar:=', include_lidar])}], output='screen'), ]) ``` 启动： ```bash # 带激光雷达 ros2 launch my_robot_description display.launch.py # 不带（仿真场景切换） ros2 launch my_robot_description display.launch.py include_lidar:=false ``` ### 六、Xacro 常见坑与排障 | 现象 | 原因 | 解决 | | --- | --- | --- | | `xacro` 报 `NameError: name 'x' is not defined` | `${}` 里引用未定义属性 | 检查属性名拼写与定义顺序（先定义后使用） | | `${}` 里写字符串比较出错 | 值被当成数字 | 数字/字符串要类型匹配，布尔用 `${true}` | | 宏参数传不进去 | 调用时属性名写错或没加 `:=` | 默认值参数用 `param:=value` 覆盖 | | 展开后 link 重复 | 宏内写死了 name | name 必须用 `${参数}` 拼接，保证唯一 | | `check_urdf` 报 joint 缺 parent | 宏展开顺序问题 | 检查宏调用时 parent 名称是否已生成 | | 模型显示但关节不动 | joint_state_publisher 未跑 | 启动 GUI 版或手动发 `/joint_states` | | 中文注释在展开时报错 | 编码问题 | 文件用 UTF-8 保存，避免特殊字符 | #### 6.1 调试技巧：局部展开 ```bash # 只展开不写文件，直接看某段 XML 是否正确 xacro demo_car.xacro | grep -A 10 'link name="lidar"' ``` #### 6.2 版本提醒 ROS2 Humble 自带 `xacro`（Python 实现）。若你手动安装过旧版，注意 `xacro --help` 确认命令存在；launch 里 `Command(['xacro ', file])` 前确保 `xacro` 在 PATH。 ### 七、小结与下一篇预告 **本篇核心**： 1. **Xacro 是 URDF 的超集**：先展开成 URDF 再消费，解决重复/不可计算/不可参数化三大痛点。 2. **属性 property**：常量 + `${}` 数学表达式，一处修改全局生效。 3. **宏 macro**：带参数复用代码块，`params` 支持默认值与块参数；机械臂 6 关节用宏写只需 6 行调用。 4. **条件 if**：`include_lidar:=false` 实现同文件多配置。 5. **工程闭环**：`xacro → check_urdf → robot_state_publisher → RViz`，launch 里用 `Command(['xacro ', file])` 展开。 6. 从 URDF 手写 150 行降到 Xacro 90 行，可维护性显著提升。下一篇进入 **Gazebo 仿真基础与世界搭建**：URDF/Xacro 描述好了"骨骼"，Gazebo 提供"物理世界"——重力、摩擦、碰撞、传感器仿真都在这里。我们会把小车放进 Gazebo，搞定 world 文件、`spawn_entity` 与 gazebo_ros 插件，让小车在虚拟世界里跑起来。蓝图已成，物理引擎接管。 --- **作者：**Wang Shijie **本文链接：**[https://wsj-blog.pages.dev/posts/ros2-xi-lie-jiao-cheng-xacro-can-shu-hua-jian-mo/](https://wsj-blog.pages.dev/posts/ros2-xi-lie-jiao-cheng-xacro-can-shu-hua-jian-mo/) 本文采用[知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](https://creativecommons.org/licenses/by-nc-sa/4.0/)进行许可。