2、URDF/SRDF模型加载失败：模型文件路径错误、格式不规范、关节命名冲突、缺少必要的碰撞检测参数

模型加载失败，是MoveIt入门时最让人头疼的问题之一。我刚开始接触那会儿，光是把一个URDF文件成功加载到MoveIt里，就折腾了大半天。说白了，机器人模型就是MoveIt的“身体”，身体都站不起来，后面的运动规划、避障什么的根本无从谈起。

这一节，我把常见的模型加载失败原因掰开揉碎了讲。你想想看，一个模型文件从磁盘读到内存，再被解析成机器人描述，中间任何一个环节出问题，都会导致加载失败。咱们一个一个来排查。

核心观点：URDF/SRDF加载失败，90%的问题出在路径、格式、命名和碰撞参数这四个方面。把这四个点卡死，模型加载基本就稳了。

2.1 文件路径错误：ROS包路径与相对路径的陷阱

路径问题，是我见过最频繁的坑。ROS里加载模型文件，通常用 package:// 协议来指定路径。比如 package://my_robot_description/urdf/robot.urdf。但很多人习惯直接写相对路径，或者把模型文件放错了位置。

为什么会这样？ ROS的包路径查找机制，依赖于 ROS_PACKAGE_PATH 环境变量。如果你没有 source 对应的 setup.bash，或者包名写错了，ROS根本找不到你的模型文件。

避坑指南：我曾经在一个项目里，把URDF文件放在了 src/my_robot/urdf/ 下，但CMakeLists.txt里忘记安装这个文件。结果在launch文件里引用 package://my_robot/urdf/robot.urdf 时，一直报文件不存在。折腾了两小时才发现，文件根本没被安装到install目录里。

正确的做法是：

模型文件统一放在 urdf/ 目录下
在CMakeLists.txt中添加 install(DIRECTORY urdf/ DESTINATION share/${PROJECT_NAME}/urdf)
launch文件中始终使用 package:// 协议
用 rospack find your_package 验证包路径是否正确

2.2 格式不规范：XML语法与URDF标签的硬性要求

URDF本质上是XML文件。XML对格式要求非常严格——标签必须闭合，属性值必须加引号，大小写敏感。我见过有人把 <link> 写成了 <Link>，结果解析器直接报错。

另外，URDF的标签结构有固定要求：

每个 <link> 必须有 <inertial>、<visual> 和 <collision> 三个子标签（至少要有 <inertial> 和 <collision>）
每个 <joint> 必须有 <parent> 和 <child>，且 <origin> 的 xyz 和 rpy 属性必须完整
所有几何体（box、cylinder、sphere、mesh）的尺寸参数必须为正数

我的小技巧：写URDF时，我习惯先用 check_urdf robot.urdf 命令做语法检查。这个工具会告诉你每一行的问题，比如“missing required attribute 'xyz'”之类的。比肉眼排查快多了。

还有一个常见问题：编码格式。URDF文件必须是UTF-8编码，不能有BOM头。如果你在Windows上编辑了文件，然后传到Linux上，很可能因为BOM头导致解析失败。我建议直接用 file robot.urdf 命令查看文件编码。

2.3 关节命名冲突：一个名字只能属于一个关节

关节命名冲突，说白了就是两个关节用了同一个名字。ROS的机器人模型描述中，所有关节名必须全局唯一。如果你在URDF里定义了两个 <joint name="shoulder_pan">，解析器会直接报错。

但有一种情况比较隐蔽：SRDF中的命名冲突。SRDF（Semantic Robot Description Format）里定义了规划组、虚拟关节、被动关节等语义信息。如果SRDF里引用了URDF中不存在的关节名，或者SRDF中的组名与URDF中的关节名重复，也会导致加载失败。

我建议的命名规范：

元素类型	命名规范	示例
关节	小写+下划线，以关节类型或位置结尾	`shoulder_pan_joint`
连杆	小写+下划线，以 `_link` 结尾	`upper_arm_link`
规划组	首字母大写，使用驼峰命名	`ArmGroup`
虚拟关节	以 `virtual_` 开头	`virtual_joint`

经验之谈：我在做一个双臂机器人项目时，左右臂的关节都叫 shoulder_pan，结果MoveIt加载后只识别到一个臂。后来我改成 left_shoulder_pan 和 right_shoulder_pan，问题就解决了。命名时加上左右前缀，是个好习惯。

2.4 缺少碰撞检测参数：MoveIt无法进行碰撞检查

这个坑比较隐蔽。URDF中每个 <link> 的 <collision> 标签，定义了该连杆的碰撞几何体。如果某个连杆没有 <collision>，MoveIt在碰撞检测时会直接跳过它——这意味着该连杆可以和其他任何物体“穿模”，运动规划的结果可能完全不可用。

更严重的是，如果所有连杆都缺少 <collision>，MoveIt的碰撞检测器会初始化失败，导致整个规划流程崩溃。

正确的做法是：

每个 <link> 都必须有 <collision> 标签
碰撞几何体可以比可视化几何体更简化（比如用圆柱体代替复杂的网格模型），以提高碰撞检测效率
碰撞几何体的位置和朝向要与可视化几何体保持一致

避坑指南：我曾经为了省事，只给机械臂的末端执行器加了碰撞几何体，其他连杆都省略了。结果运动规划出来的轨迹，机械臂直接穿过桌面。嗯，从那以后我再也不敢偷懒了。每个连杆的碰撞几何体，必须老老实实加上。

另外，SRDF中的 <disable_collisions> 标签也很重要。它定义了哪些连杆对之间不需要进行碰撞检测（比如相邻连杆之间）。如果这个配置不合理，会导致碰撞检测计算量过大，或者误报碰撞。

2.5 快速排查流程

当你遇到模型加载失败时，按这个顺序排查：

检查路径：用 rospack find your_package 确认包路径，用 ls 确认文件存在
检查格式：运行 check_urdf robot.urdf 和 check_srdf robot.srdf
检查命名：用 grep 搜索URDF和SRDF中是否有重复的关节名
检查碰撞：确认每个 <link> 都有 <collision> 子标签
查看日志：运行 roslaunch your_package your_launch.launch，仔细看终端输出的错误信息

我的习惯：每次修改URDF后，我都会先跑一遍 check_urdf，再在Rviz里加载一次看看效果。发现问题立刻改，不要攒到后面一起排查。小步快跑，比一次性写完再debug要高效得多。

模型加载是MoveIt仿真的第一步，也是最重要的一步。把这四个方面的坑都填平了，后面的工作才能顺利展开。记住：路径要准、格式要对、命名要唯一、碰撞要齐全。做到这四点，模型加载基本不会出问题。