Pinocchio避坑，难点从来不只是把库装上，而是URDF、关节索引、坐标系和单位能不能对齐。很多人能跑通示例，却在雅可比、逆动力学或仿真联调时得到离谱结果。下面按最常见的几组选择逐项拆开，帮你少走弯路。
Pinocchio是面向刚体机器人运动学和动力学的开源库，擅长快速算正运动学、雅可比、质量矩阵、逆动力学和正向动力学。它接收的是URDF等描述文件，再根据关节状态输出数学结果。这里最容易犯的错，是把模型输出直接当作真实机器人状态。
模型里一根连杆长500毫米，真实文件却写成500，Pinocchio会把它当500米；模型里惯量以千克平方米计，手工填成克毫米平方，逆动力矩就会失真几个数量级。遇到结果怪异，先别怀疑算法，先检查单位：长度用米、质量用千克、角度接口一般用弧度。
做桌面机械臂时，通常用固定基座模型：buildModelFromUrdf读取后，配置向量q只包含可动关节。做双足、人形或四足机器人时，基座本身会运动，应该建立自由基座模型，例如使用JointModelFreeFlyer。两者不是只差一个参数，状态维度、速度维度和关节编号都会变。
固定基座模型里，六轴机械臂的q长度常常就是6；自由基座模型的配置里会多出位置和四元数，速度里会多出线速度与角速度。把前者的数据直接塞进后者，轻则维度报错，重则因为数组位置刚好能对上而悄悄算错。这类静默错误比报错更麻烦。
不少人把URDF里看到的第3个关节，直接当成q[2]。简单机械臂偶尔能蒙对，复杂模型就不行。Pinocchio内部有universe根节点，浮动基座又会占据多个配置和速度分量；某些关节还可能不是一维关节。正确做法是查看model.names、model.idx_qs、model.nqs，以及model.idx_vs、model.nvs。
实战里我更建议先打印每个关节的名称、q起始位置和自由度，再建立一张名称到控制器通道的映射表。别依赖文件书写顺序，也别依赖电机编号。控制器第4路可能对应shoulder_pan，URDF第4个joint却可能是一个固定关节；这两个概念一混，整条动力学链都会偏。
正运动学之后，只调用forwardKinematics还不够。你若要读取末端执行器位姿，通常还要更新frame placement，再从data.oMf取指定frame。很多人读到的却是关节变换，误以为那就是工具中心点TCP，导致抓取点总是偏一截。
算雅可比时也要明确参考系。局部坐标系下，速度方向跟着末端转；世界坐标系下，方向固定在世界轴；局部世界对齐坐标则常用于控制器。没有哪一种天然正确，关键在于控制误差在哪个坐标系表达。位置误差在世界系、雅可比却取局部系，是末端控制发散的典型原因。
已知q、速度v、加速度a，想要关节需要多少力矩，用rnea，也就是递归牛顿欧拉逆动力学。已知q、v、力矩tau，想推下一刻加速度，用aba。想拿质量矩阵做优化、MPC或阻抗控制，使用crba。三者输入看着相近，问题方向却正好不同。
还有一个常被漏掉的细节：重力来自model.gravity。你在仿真里把机器人竖起来，却在模型中保留默认重力方向或把重力设为零，rnea算出的保持力矩当然不对。排查时可以先令v和a都为零，只看重力补偿力矩；这是一条很省时间的基准测试。