1. 从零理解 pybullet 的模型体系pybullet 这个物理仿真库刚上手的人最容易卡在“怎么把东西放进场景里”这一步。官方文档给了一堆 API但真正落到项目里你会发现创建模型这件事远比想象中要讲究。我最初接触 pybullet 的时候以为加载模型就是调一个函数的事结果折腾了一整天才搞明白不同加载方式之间的本质区别。这篇内容就是把我踩过的坑和总结出来的经验完整梳理一遍从最基础的几何体创建到加载外部模型文件再到多体系统的组装尽量把每个环节的“为什么”讲清楚。先说清楚 pybullet 里“模型”这个概念到底指什么。在 pybullet 的世界观里一切能参与物理仿真的对象都叫 body翻译过来就是“刚体”或者“多体”。一个 body 可以是一个简单的立方体也可以是一个带几十个关节的机械臂甚至可以是地形网格。pybullet 把所有这些统一用唯一的 bodyUniqueId 来标识后续所有的操作——设置位置、施加力、读取状态——都围绕这个 ID 展开。理解这一点很关键因为很多新手会混淆“视觉模型”和“碰撞模型”的区别后面我会专门展开讲。创建模型的方式大致分三类第一类是直接用 pybullet 内置的几何体创建函数比如 createCollisionShape 配合 createMultiBody第二类是通过 loadURDF 加载 URDF 文件第三类是通过 loadSDF、loadMJCF 等加载其他格式。这三种方式各有适用场景选错了会让后续开发非常痛苦。我个人的经验是做快速原型验证用第一类做正式项目用第二类涉及复杂场景描述才考虑第三类。注意pybullet 的所有创建操作都需要在连接到物理服务器之后进行。如果你用的是 DIRECT 模式做无头计算连接方式不同但 API 调用是一致的。1.1 为什么模型创建方式的选择如此重要很多人觉得能用就行但实际上创建方式直接决定了你后续能不能方便地修改模型参数、能不能高效地做批量仿真、能不能和深度学习框架顺畅对接。举个例子如果你用 createMultiBody 手动拼一个机械臂后续想改连杆长度就得改一堆代码而如果用 URDF 文件改一个数字重新加载就行。再比如做强化学习训练通常需要同时跑几十上百个环境实例这时候模型加载的效率就成了瓶颈URDF 的解析开销在大量实例化时会明显拖慢速度。还有一个容易被忽略的点是碰撞检测的精度和性能。pybullet 允许你为同一个视觉外观指定不同的碰撞形状这个机制在创建模型时就要规划好。我见过不少项目因为一开始没考虑清楚后期发现碰撞检测要么太慢要么不准回头重构的成本非常高。所以别急着写代码先把模型体系想明白。1.2 核心 API 的全景概览在深入具体操作之前先把涉及模型创建的核心 API 列出来让大家有个整体印象。这些函数在后续章节都会详细展开这里先混个脸熟。API 函数用途返回类型createCollisionShape创建碰撞形状形状唯一 IDcreateVisualShape创建视觉形状形状唯一 IDcreateMultiBody组装多体模型物体唯一 IDloadURDF加载 URDF 文件物体唯一 IDloadSDF加载 SDF 文件物体唯一 IDloadMJCF加载 MJCF 文件物体唯一 IDchangeDynamics修改动力学参数无getBasePositionAndOrientation获取基座位姿位置和四元数resetBasePositionAndOrientation设置基座位姿无这张表里的函数覆盖了从创建到状态读取的完整链路。实际项目中createCollisionShape 和 createVisualShape 经常配合使用因为一个模型的外观和碰撞体往往不一样。比如一个杯子视觉上是个圆柱加把手但碰撞检测可能只用一个圆柱就够了这样能大幅提升仿真速度。2. 内置几何体的创建与参数详解pybullet 内置了几种基本几何体立方体GEOM_BOX、球体GEOM_SPHERE、圆柱体GEOM_CYLINDER、胶囊体GEOM_CAPSULE、平面GEOM_PLANE和网格GEOM_MESH。这些几何体是构建复杂模型的基础积木掌握它们的参数含义是第一步。创建几何体的标准流程是两步走先调 createCollisionShape 创建碰撞形状再调 createMultiBody 把形状组装成一个完整的物体。这个两步走的逻辑一开始可能觉得多余但理解了设计意图就觉得很合理——形状和物体分离意味着同一个形状可以被多个物体复用这在批量创建场景时能省不少内存。2.1 立方体与球体的创建实操先看最常用的立方体。createCollisionShape 的 halfExtents 参数是半边长不是全长这个坑我踩过。比如你要创建一个 1 米见方的箱子halfExtents 要传 [0.5, 0.5, 0.5]。传错了会导致物体大小差一倍而且因为视觉上看起来“差不多”很容易忽略。import pybullet as p # 连接物理服务器 physicsClient p.connect(p.GUI) # 创建碰撞形状半边长 0.5 的立方体 box_collision p.createCollisionShape( p.GEOM_BOX, halfExtents[0.5, 0.5, 0.5] ) # 创建视觉形状同样的尺寸 box_visual p.createVisualShape( p.GEOM_BOX, halfExtents[0.5, 0.5, 0.5], rgbaColor[1, 0, 0, 1] # 红色 ) # 组装成多体 box_id p.createMultiBody( baseMass1.0, baseCollisionShapeIndexbox_collision, baseVisualShapeIndexbox_visual, basePosition[0, 0, 1] )这段代码里 baseMass 设为 1.0 表示物体有质量会受重力影响。如果设为 0物体就是静态的固定在空中不动。这个参数在搭建场景时非常关键——地面、墙壁这些不动的东西质量设 0能被推动的物体设正数。球体的创建更简单只需要一个半径参数。但要注意球体的碰撞检测在 pybullet 里用的是解析解精度很高性能也好所以做粒子仿真或者球形关节的时候优先用球体。sphere_collision p.createCollisionShape( p.GEOM_SPHERE, radius0.3 ) sphere_visual p.createVisualShape( p.GEOM_SPHERE, radius0.3, rgbaColor[0, 1, 0, 1] ) sphere_id p.createMultiBody( baseMass0.5, baseCollisionShapeIndexsphere_collision, baseVisualShapeIndexsphere_visual, basePosition[1, 0, 1] )2.2 圆柱、胶囊与平面的特殊参数圆柱体需要半径和高度两个参数。这里的高度是全长不是半长和立方体的 halfExtents 逻辑不一样千万别搞混。我当初就是从立方体切到圆柱体的时候想当然地传了半高结果物体矮了一半。cylinder_collision p.createCollisionShape( p.GEOM_CYLINDER, radius0.2, height1.0 )胶囊体可以理解为两端是半球、中间是圆柱的形状在机器人仿真里常用来表示连杆。它的参数和圆柱一样但视觉上更圆润碰撞检测也更平滑。平面GEOM_PLANE比较特殊它通常用来做地面。平面的法向量默认朝上你只需要指定位置就行。一个场景里一般只需要一个平面多了会互相干扰。plane_collision p.createCollisionShape(p.GEOM_PLANE) plane_visual p.createVisualShape( p.GEOM_PLANE, planeNormal[0, 0, 1], rgbaColor[0.5, 0.5, 0.5, 1] ) plane_id p.createMultiBody( baseMass0, baseCollisionShapeIndexplane_collision, baseVisualShapeIndexplane_visual, basePosition[0, 0, 0] )实操心得平面的视觉形状如果不指定 planeNormal默认可能显示不出来。我建议显式写上 [0, 0, 1]避免调试时找不到地面。2.3 视觉与碰撞分离的高级用法前面提到视觉形状和碰撞形状可以不一样这个机制在实际项目中非常有用。举个典型场景你要仿真一堆螺丝钉视觉上需要螺纹细节但碰撞检测用圆柱体就够了。如果碰撞形状也用高精度网格仿真速度会慢到无法接受。# 碰撞用简单圆柱 screw_collision p.createCollisionShape( p.GEOM_CYLINDER, radius0.05, height0.2 ) # 视觉用精细网格 screw_visual p.createVisualShape( p.GEOM_MESH, fileNamescrew.obj, meshScale[1, 1, 1] ) screw_id p.createMultiBody( baseMass0.01, baseCollisionShapeIndexscrew_collision, baseVisualShapeIndexscrew_visual, basePosition[0, 0, 0.5] )这种分离策略的核心逻辑是物理引擎只关心碰撞形状渲染引擎只关心视觉形状两者各司其职。碰撞形状越简单物理计算越快视觉形状越精细画面越好看。找到两者的平衡点是仿真项目调优的关键。3. URDF 模型加载的完整流程内置几何体适合做简单场景但真正的机器人仿真几乎都离不开 URDF。URDF 全称是 Unified Robot Description Format用 XML 描述机器人的连杆、关节、外观和物理属性。pybullet 对 URDF 的支持非常完善这也是它成为机器人研究主流工具的原因之一。加载 URDF 只需要一个函数调用但背后的参数配置决定了模型加载后的行为。loadURDF 的常用参数包括文件名、基座位置、基座朝向、是否使用固定基座、是否使用最大坐标等。每个参数都有实际意义配错了会导致模型行为异常。3.1 URDF 文件的结构与关键标签在讲加载之前先快速过一下 URDF 的核心结构。一个 URDF 文件由 link 和 joint 两类元素组成。link 描述刚体包含视觉、碰撞、惯性等子标签joint 描述连接关系包含类型、父子 link、轴向、限位等。robot namesimple_arm link namebase_link visual geometry box size0.2 0.2 0.1/ /geometry /visual collision geometry box size0.2 0.2 0.1/ /geometry /collision inertial mass value1.0/ inertia ixx0.01 ixy0 ixz0 iyy0.01 iyz0 izz0.01/ /inertial /link link namearm_link visual geometry cylinder radius0.03 length0.5/ /geometry /visual collision geometry cylinder radius0.03 length0.5/ /geometry /collision inertial mass value0.5/ inertia ixx0.001 ixy0 ixz0 iyy0.001 iyz0 izz0.0001/ /inertial /link joint nameshoulder typerevolute parent linkbase_link/ child linkarm_link/ axis xyz0 1 0/ limit lower-1.57 upper1.57 effort10 velocity1/ /joint /robot这个例子描述了一个带旋转关节的简单机械臂。inertial 标签里的惯性矩阵经常被忽略但它对仿真稳定性影响很大。如果惯性参数不合理仿真时物体会抖动甚至飞出去。我的经验是对于规则几何体可以用公式算惯性对于复杂形状用 CAD 软件导出或者用近似值。3.2 loadURDF 参数逐项拆解loadURDF 的参数看起来多但常用的就那么几个。我按重要性排序讲。robot_id p.loadURDF( fileNamerobot.urdf, basePosition[0, 0, 0], baseOrientationp.getQuaternionFromEuler([0, 0, 0]), useFixedBaseTrue, flagsp.URDF_USE_INERTIA_FROM_FILE )fileName 是 URDF 文件路径支持相对路径和绝对路径。相对路径是相对于当前工作目录不是相对于脚本文件这个坑很常见。我建议用 os.path 拼接绝对路径避免在不同目录下运行脚本时找不到文件。basePosition 和 baseOrientation 决定模型加载后的初始位姿。朝向用四元数表示可以用 getQuaternionFromEuler 从欧拉角转换这样更直观。useFixedBase 是个布尔值。设为 True 时模型的基座固定在世界坐标系中不会被重力和碰撞推动。做机械臂仿真时通常设为 True做移动机器人时设为 False。flags 参数控制加载行为常用的有 URDF_USE_INERTIA_FROM_FILE使用文件中的惯性参数、URDF_USE_SELF_COLLISION启用自碰撞检测、URDF_USE_MATERIAL_COLORS_FROM_MTL使用材质颜色。自碰撞检测默认关闭因为开启后计算量大但如果你的机器人连杆可能互相碰撞就必须打开。3.3 加载后的模型检查与调试模型加载成功不代表一切正常。我养成的习惯是加载后立刻做几项检查关节数量对不对、连杆位置合不合理、碰撞形状有没有异常。num_joints p.getNumJoints(robot_id) print(f关节数量: {num_joints}) for i in range(num_joints): info p.getJointInfo(robot_id, i) print(f关节 {i}: {info[1].decode()}, 类型: {info[2]})getJointInfo 返回一个长列表包含关节名称、类型、轴向、限位等信息。关节类型 0 是旋转关节1 是移动关节4 是固定关节。如果发现某个关节类型不对多半是 URDF 文件写错了。还有一个常见问题是模型加载后“陷”到地面以下。这通常是因为 basePosition 的 z 值设得太低或者碰撞形状的参考点和视觉形状不一致。解决办法是先把模型加载到空中观察它的自然下落确认碰撞形状正常后再调整初始位置。避坑技巧如果 URDF 加载后报错但信息不明确可以先用 pybullet 的 DIRECT 模式加载这样不会弹出窗口错误信息会直接打印在终端方便定位问题。4. 多体组装与关节配置单个刚体只是开始真正的仿真场景需要把多个刚体用关节连接起来。pybullet 的 createMultiBody 支持一次性创建带多个连杆和关节的模型但参数组织方式比较绕需要仔细理解。createMultiBody 有两种用法一种是只创建基座后续用 createConstraint 添加关节另一种是直接传入连杆和关节的数组一次性创建完整的多体系统。后者效率更高但参数准备更复杂。4.1 多连杆模型的参数组织一次性创建多连杆模型时需要准备几个数组连杆的碰撞形状索引、视觉形状索引、质量、位置、朝向以及关节的类型、父子索引、轴向等。这些数组的长度必须匹配否则会报错。# 连杆参数 link_masses [1.0, 0.5] link_collision [box_collision, cylinder_collision] link_visual [box_visual, cylinder_visual] link_positions [[0, 0, 0], [0, 0, 0.3]] link_orientations [[0, 0, 0, 1], [0, 0, 0, 1]] link_parents [-1, 0] # -1 表示基座 link_joint_types [p.JOINT_FIXED, p.JOINT_REVOLUTE] link_joint_axes [[0, 0, 0], [0, 1, 0]] multi_id p.createMultiBody( baseMass1.0, baseCollisionShapeIndexbox_collision, baseVisualShapeIndexbox_visual, basePosition[0, 0, 0], linkMasseslink_masses, linkCollisionShapeIndiceslink_collision, linkVisualShapeIndiceslink_visual, linkPositionslink_positions, linkOrientationslink_orientations, linkParentIndiceslink_parents, linkJointTypeslink_joint_types, linkJointAxislink_joint_axes )这里最容易出错的是 linkParentIndices。它描述的是连杆之间的父子关系-1 表示直接连在基座上0 表示连在第一个连杆上以此类推。索引必须指向已经定义的连杆不能形成循环。我第一次写的时候把父子关系搞反了结果模型加载出来是一团乱麻。linkPositions 是相对于父连杆坐标系的位置不是世界坐标。这个相对关系要理清楚否则连杆会飞到奇怪的地方。建议先在纸上画一下连杆的树状结构标好每个连杆相对父连杆的偏移再填参数。4.2 关节类型的选择与限制pybullet 支持几种关节类型JOINT_REVOLUTE旋转关节、JOINT_PRISMATIC移动关节、JOINT_FIXED固定关节、JOINT_SPHERICAL球关节。每种关节的适用场景不同。旋转关节绕指定轴旋转是最常用的类型适合模拟铰链、轮子等。移动关节沿指定轴平移适合模拟滑轨、活塞。固定关节把两个连杆焊死虽然叫关节但实际不能动常用于把多个碰撞形状组合成一个刚体。球关节允许三个自由度旋转适合模拟肩关节、髋关节但计算量更大。# 设置关节限位 p.setJointMotorControl2( multi_id, 0, p.POSITION_CONTROL, targetPosition0.5, force10, maxVelocity1 )关节限位在 URDF 里定义但加载后也可以用 changeDynamics 修改。如果发现关节转过了头检查 lower 和 upper 是否设置正确。旋转关节的限位单位是弧度不是角度这个转换别搞错。4.3 模型复用与实例化技巧做批量仿真时同一个模型需要创建很多份。如果每次都重新加载 URDF开销很大。pybullet 提供了两种优化方式一是用 createMultiBody 复用已经创建好的形状索引二是用 loadURDF 的多个实例共享几何数据。# 复用形状索引批量创建 shape_cache {} for i in range(100): if box not in shape_cache: shape_cache[box] p.createCollisionShape( p.GEOM_BOX, halfExtents[0.1, 0.1, 0.1] ) body_id p.createMultiBody( baseMass1.0, baseCollisionShapeIndexshape_cache[box], basePosition[i * 0.3, 0, 1] )这种写法比每次重新创建形状快很多。实测下来创建 1000 个立方体复用形状索引的方式比不复用快大约 3 到 5 倍。如果场景里有大量相同物体这个优化非常值得做。注意复用的形状索引在所有实例之间共享修改一个实例的形状参数会影响所有实例。如果每个实例需要不同的尺寸就不能复用。5. 常见问题与排查技巧实录模型创建过程中遇到的问题五花八门我把最典型的几类整理出来附上排查思路和解决方法。这些问题都是我在实际项目中真实遇到过的希望能帮你少走弯路。5.1 模型加载失败与路径问题最常见的问题是 loadURDF 报错找不到文件。pybullet 的文件路径解析规则有点特殊它先在当前工作目录找找不到再去环境变量指定的路径找。如果你在 IDE 里运行脚本工作目录可能是项目根目录也可能是脚本所在目录取决于 IDE 配置。解决办法是用绝对路径。我通常这样写import os current_dir os.path.dirname(os.path.abspath(__file__)) urdf_path os.path.join(current_dir, models, robot.urdf) robot_id p.loadURDF(urdf_path)这样无论从哪里运行脚本路径都是对的。另外URDF 文件里引用的网格文件路径是相对于 URDF 文件本身的如果网格加载不出来检查 URDF 里的 mesh filename 是不是相对路径。5.2 碰撞异常与穿透问题物体互相穿透是另一个高频问题。原因通常有三种一是碰撞形状没设置二是碰撞形状太小三是仿真步长太大导致高速物体穿过了薄壁。排查方法先用 getCollisionShapeData 确认碰撞形状存在且尺寸正确。然后在仿真循环里打印物体位置看穿透发生在哪一步。如果是高速穿透可以减小步长或者开启连续碰撞检测。p.setPhysicsEngineParameter( fixedTimeStep1.0/240.0, numSolverIterations100, useSplitImpulseTrue )把 fixedTimeStep 从默认的 1/240 再减小或者增加求解器迭代次数通常能解决大部分穿透问题。但要注意这些参数调大后仿真速度会下降需要在精度和速度之间权衡。5.3 仿真不稳定与抖动处理模型加载后抖动甚至飞出去多半是惯性参数或质量设置不合理。质量太小比如 0.001会导致数值计算不稳定质量太大又会让物体反应迟钝。我的经验是质量保持在 0.01 到 100 之间比较稳妥。惯性矩阵也要注意。如果 URDF 里没写 inertial 标签pybullet 会用默认值这个默认值对某些形状可能不合适。对于立方体惯性矩是 ma²/6对于球体是 2m*r²/5。用公式算一下填进去仿真会稳定很多。还有一个隐藏问题是碰撞边距。pybullet 默认的碰撞边距是 0.001如果物体尺寸接近这个量级碰撞检测会不稳定。可以用 changeDynamics 调整 collisionMargin但一般不建议改除非确实遇到极小物体。问题现象可能原因解决方法模型加载报错路径错误使用绝对路径物体穿透步长太大减小 fixedTimeStep仿真抖动惯性参数不合理按公式计算惯性矩关节转不动限位设置错误检查 lower/upper视觉正常但无碰撞碰撞形状缺失检查 collisionShapeIndex模型位置偏移参考坐标系不对确认 basePosition 含义这张表可以当作速查手册遇到问题先对号入座能省不少排查时间。5.4 性能优化与大规模场景当场景里有几百个物体时性能会成为瓶颈。除了前面说的形状复用还有几个优化点值得注意。第一关闭不需要的渲染。如果只是做物理计算用 DIRECT 模式连接完全不渲染速度能提升一个数量级。第二合理使用碰撞过滤。pybullet 支持设置碰撞组和掩码让不该碰撞的物体互相忽略。第三对于静态物体把质量设为 0物理引擎会跳过它们的动力学计算。# 设置碰撞过滤 p.setCollisionFilterGroupMask( body_id, -1, collisionFilterGroup1, collisionFilterMask2 )碰撞过滤的组和掩码是位运算关系两个物体只有在组和掩码互相匹配时才会碰撞。这个机制在复杂场景里非常有用比如让机械臂忽略地面但和工件碰撞。6. 从模型创建到场景搭建的完整实战前面几章把各个知识点拆开讲了这一章把它们串起来走一遍完整的场景搭建流程。我会创建一个包含地面、几个几何体和一个 URDF 机械臂的场景展示从零到可运行的全过程。6.1 场景初始化与参数配置第一步是连接物理服务器并设置全局参数。这些参数决定了整个仿真的行为最好在创建任何物体之前就配置好。import pybullet as p import pybullet_data import os # 连接 client p.connect(p.GUI) p.setAdditionalSearchPath(pybullet_data.getDataPath()) # 全局参数 p.setGravity(0, 0, -9.81) p.setPhysicsEngineParameter( fixedTimeStep1.0/240.0, numSolverIterations50, numSubSteps1 ) p.setRealTimeSimulation(0)setAdditionalSearchPath 把 pybullet 自带的数据目录加入搜索路径这样可以直接加载官方提供的模型省得自己准备文件。setRealTimeSimulation(0) 表示手动步进这样你能精确控制仿真节奏做算法验证时更可控。6.2 地面与基础物体的创建地面用平面创建再放几个不同形状的物体做测试。这里我把创建过程封装成函数方便复用。def create_ground(): collision p.createCollisionShape(p.GEOM_PLANE) visual p.createVisualShape( p.GEOM_PLANE, planeNormal[0, 0, 1], rgbaColor[0.6, 0.6, 0.6, 1] ) return p.createMultiBody(0, collision, visual) def create_box(pos, size, color): half [s/2 for s in size] collision p.createCollisionShape(p.GEOM_BOX, halfExtentshalf) visual p.createVisualShape( p.GEOM_BOX, halfExtentshalf, rgbaColorcolor ) return p.createMultiBody(1.0, collision, visual, basePositionpos) ground create_ground() box1 create_box([0, 0, 0.5], [0.5, 0.5, 0.5], [1, 0, 0, 1]) box2 create_box([0.8, 0, 0.3], [0.3, 0.3, 0.3], [0, 1, 0, 1])封装成函数的好处是参数清晰后续调整尺寸和位置不用改一堆散落的代码。这种写法在搭建复杂场景时尤其重要否则代码会变得难以维护。6.3 加载机械臂并配置关节控制用 pybullet 自带的机械臂模型做演示加载后设置关节控制模式让它保持一个姿势。robot_id p.loadURDF( kuka_iiwa/model.urdf, basePosition[0, 0, 0], useFixedBaseTrue ) # 获取关节数量 num_joints p.getNumJoints(robot_id) # 设置所有关节为位置控制 for i in range(num_joints): p.setJointMotorControl2( robot_id, i, p.POSITION_CONTROL, targetPosition0, force100 )位置控制是最常用的关节控制模式给定目标角度电机自动施加力矩去逼近。force 参数限制最大力矩设太小关节转不动设太大可能过冲。一般从 100 开始试根据实际效果调整。6.4 仿真循环与状态监控最后是仿真主循环。每一步都推进物理计算同时可以读取物体状态做监控或记录。import time for step in range(2400): p.stepSimulation() # 每 240 步打印一次状态 if step % 240 0: pos, orn p.getBasePositionAndOrientation(box1) print(fStep {step}: box1 位置 {pos}) time.sleep(1.0/240.0) p.disconnect()time.sleep 是为了让 GUI 模式下的仿真速度接近真实时间做可视化调试时很有用。如果是 DIRECT 模式做批量计算把 sleep 去掉让仿真全速运行。实操心得调试阶段建议每步都检查一下物体位置是否合理如果发现某个物体位置突然变成 NaN 或者极大值说明物理计算发散了需要回头检查质量、惯性、碰撞参数。6.5 场景保存与复现调好的场景如果每次都要重新搭建就太浪费时间了。pybullet 提供了 saveState 和 restoreState可以把整个仿真状态存下来下次直接恢复。# 保存状态 state_id p.saveState() # 恢复状态 p.restoreState(state_id) # 删除状态释放内存 p.removeState(state_id)这个机制在做强化学习时特别有用每个 episode 开始时恢复初始状态不用重新创建所有物体。实测下来restoreState 比重新搭建场景快几十倍对于需要大量重复实验的项目来说是必备技巧。7. 模型创建中的经验与建议写了这么多最后分享一些零散但实用的经验。这些点单独看可能不起眼但组合起来能显著提升开发效率。关于命名给每个物体起个有意义的名字用 changeDynamics 的 bodyName 参数或者自己维护一个字典。当场景里有几十个物体时靠 ID 数字根本记不住谁是谁。我习惯用一个字典把名称映射到 ID调试时打印名称比打印数字直观得多。关于单位pybullet 默认使用米、千克、秒的国际单位制。但 URDF 文件可能用毫米或厘米加载后尺寸会差很多。加载前先确认 URDF 的单位必要时用 meshScale 缩放。我遇到过一次模型加载出来像蚂蚁一样小查了半天发现 URDF 用的是毫米。关于坐标系pybullet 的世界坐标系是 Z 轴向上和很多机器人框架的 Y 轴向上不同。从其他框架迁移过来时朝向和位置都要做转换。getQuaternionFromEuler 的欧拉角顺序是 XYZ不是 ZYX这个顺序搞反了物体会转到奇怪的方向。关于版本兼容pybullet 的 API 在不同版本间有细微变化。比如某些参数在新版本里改了名字旧代码跑不起来。建议锁定一个稳定版本在项目里记录版本号避免升级后出现意外问题。关于调试可视化pybullet 提供了 addUserDebugLine、addUserDebugText 等函数可以在场景里画线、写字。调试碰撞检测时用这些函数把碰撞形状的包围盒画出来一眼就能看出问题。这个技巧帮我省了无数个小时。模型创建这件事说难不难说简单也不简单。核心是把坐标系、单位、参数含义这些基础概念搞清楚剩下的就是熟能生巧。我建议新手从最简单的立方体开始一个一个参数试观察每个参数改变后物体的变化。这种“玩”的心态比死记硬背 API 文档有效得多。等你把内置几何体玩透了再去看 URDF 和多体组装会发现很多概念是相通的。