URDF/Xacro：模型是硬件接口，不是 launch 补丁对象

1. 模型错时，导航参数救不了

仿真里机器人「飘移、穿模、原地打转」，团队花了两周调 Nav2 膨胀与 DWB 权重——最后发现 base_link 到 laser 的 joint 轴方向反了 180°，点云相对机体镜像。惯性乱填（轮组当点质量）让 Gazebo 里车身弹跳，控制器以为是打滑。根因不在算法，在 URDF 是硬件接口：连杆树、惯性、碰撞、关节限位共同决定 TF、footprint、ros2_control 接口。用导航参数「补」模型，是在控制器上掩盖机械谎言。

2. Xacro 组织：可读优先于宏炫技

按物理部件拆文件：chassis.xacro、wheel_macro.xacro、sensors/lidar.xacro。宏只用于真正重复的结构（四轮同构），参数暴露 wheelbase、轮径等标量——不要嵌套五层 if 让新人找不到 <link name="base_link"> 在哪。

xml

<xacro:macro name="wheel" params="prefix reflect">
  <link name="${prefix}_wheel_link">
    <inertial>
      <mass value="2.1"/>
      <inertia ixx="0.012" ixy="0" ixz="0" iyy="0.012" iyz="0" izz="0.021"/>
    </inertial>
  </link>
</xacro:macro>

顶层 robot.xacro 只做 include 与实例化，像目录而不像程序。

3. 惯性：来源可追溯，单位不能错

惯性张量必须标注来源：SolidWorks 导出、称重组装实测、或保守估计（并写「估计，待标定」）。常见错误：把 kg 当 g、把 cm² 当 m²、对角项数量级离谱。验收时算整机质量与称重对比，误差超过 10% 应阻塞合并。SolidWorks 导出时注意坐标系：若导出帧与 URDF link 帧差 90°，惯性主轴会跟着错——要在 xacro 注释里写清变换链。

visual 用精细 mesh 给 RViz；collision 用 box/cylinder 简化——精细 mesh 碰撞让规划器在缝隙里卡死，还拖慢碰撞检测。关节 <limit> 的 effort、velocity 上限应与驱动器 datasheet 一致，虚高的 limit 不会增加真机能力，却会让仿真控制器发出物理上不可能的指令。

4. 与 ros2_control / Nav2 的对齐

关节名 left_wheel_joint 必须在三处一致：URDF <joint>、ros2_control 的 <joint name>、驱动配置里的接口表。改一处不同步，表现是「命令发了轮子不动」或「TF 树断枝」。footprint 来自 collision 投影或显式 <robot><link> 策略——改轮距或 bumper 几何必须同步 Nav2 costmap 的 footprint 参数，但几何源头仍是 URDF。

<gazebo> 插件块（摩擦、驱动接口）与 URDF 本体同 PR 审查：仿真里打滑常是 gazebo friction 与 URDF 惯性同时不对，只改一边会在真机复现另一种错。transmission 或 ros2_control 的 <hardware> 插件名必须与 launch 里 spawner 加载的控制器一致。

5. 零位与方向：实测标定，不靠 remap

关节 zero position、传感器 mount 角度应来自标定（卷尺、倾角仪、ArUco），不是 launch 里 -π/2 旋转凑对齐。在 launch 里 remap TF 能骗过 RViz 一帧，但 Gazebo 物理、真实驱动编码器仍按 URDF 真值运动——仿真与真机「同参不同命」常源于此。

6. 工具链验收

bash

check_urdf robot.urdf
ros2 run robot_state_publisher robot_state_publisher --ros-args \
  -p robot_description:="$(xacro robot.xacro)"
ros2 run tf2_tools view_frames  # 导出 TF 树 PDF 存档

在 RViz 里动 joint_state_publisher_gui 各关节，看 mesh 与 TF 轴是否反直觉。仿真中做自由落体与轻推：无对穿、无异常弹跳。改任何宏，回归整机树——局部 diff 通过但整机 mass 漂移，是集成回归高频来源。发布前对比上一版 view_frames PDF：新增 joint 是否挂在预期 parent 下，有无 orphan link。

7. 变更连带：模型 PR 不是单文件 PR

改 xacro 的 MR 应同时触及：惯性来源注释、collision 简化说明、joint 名与 control 接口表、Nav2 footprint 截图对比。缺一项视为 incomplete。CI 可跑 check_urdf + 解析总质量阈值。

8. 案例：碰撞过大吞噬窄道

某车 collision 直接包 mesh，走廊里 footprint 比视觉模型宽 15 cm，Nav2 永远规划失败。换成 box 近似后，同样膨胀参数即可过门。视觉可以好看，碰撞必须为运动规划服务。

9. 默认策略

模型即接口；惯性可追溯；collision 简化；错误回模型层修，不回 Nav2 参数层掩盖。URDF 审过比 launch 审过更值钱——launch 可以 remap，URDF 谎言会进 TF、进仿真、进控制器。把 xacro 当源码而不是生成物：.urdf 若提交进仓库，应是 CI 从 xacro 导出的产物， hand-edit 的 urdf 与 xacro 分叉后无人知晓。