MuJoCo 3.12 升级指南：用兼容检查把机器人仿真迁移风险前置

MuJoCo 3.12.0 是 Google DeepMind 维护的开源物理仿真引擎 MuJoCo 的一次版本更新，面向需要做机器人模型、控制器、碰撞与渲染验证的开发者。本次更新不只是“装一个新包”：它新增了 PID 执行器，也改变了直流电机的输入语义、纹理加载范围和部分渲染调用的返回值。下面按“先加载、再控制、后复测”的顺序整理迁移方法；文中所有版本事实均来自官方发行说明，示例代码只用于本地兼容检查，不代表本文完成了独立性能实测。

MuJoCo 3.12 到底改了什么？

官方在 2026 年 8 月 20 日发布了 3.12.0。最值得先确认的变化有四组：

1. MJCF 的语法规则改由一个统一的模式文件定义，解析器相关的规则和测试从该来源生成。

2. 新增 `pid` 执行器，可接收位置、速度和前馈量的任意组合，并支持可选积分项、积分限幅和设定值变化率限制。

3. `dcmotor` 的输入语义改为输入签名；旧的单控制量模式与部分增益含义发生了迁移。

4. 自定义二进制纹理格式被移除，纹理加载只接受 PNG 与 KTX；内置几何体纹理坐标和有限平面的锚点也有变化。

这四项都来自官方发行说明，不能推导为“所有旧模型都会失效”。它们的共同点是：模型即使能加载，控制量、画面或训练结果也可能不再与旧版本可比。

为什么先做兼容检查，而不是立刻重跑训练？

机器人仿真升级的风险通常分成三层。第一层是模型无法读取，例如纹理资源不再受支持；第二层是模型能跑但控制解释变了，例如执行器输入的数量或顺序不一致；第三层才是性能和任务指标的差异。直接从第三层开始，往往会把迁移问题误判为算法问题。

一个实用的顺序是：

| 检查层 | 要确认什么 | 通过后再做什么 |

| --- | --- | --- |

| 读取层 | 模型、纹理和依赖能否加载 | 记录版本与资源清单 |

| 步进层 | 短步进是否报错，状态是否有限 | 固定相机与随机条件 |

| 控制层 | 输入向量、限幅和增益是否符合预期 | 对照旧控制日志 |

| 任务层 | 成功、失败和耗时是否可重复 | 再比较训练或评测指标 |

表中的流程是工程建议，不是 MuJoCo 官方保证的迁移步骤。它的价值在于把问题缩小到可定位的层级。

如何用最小脚本检查模型是否还能稳定步进？

先在隔离环境中固定目标版本，再用一个代表性模型做短步进。下面的脚本不会修改模型文件，只验证 Python 绑定能否加载模型并执行有限步数。请在自己的项目目录、测试模型和可回滚环境中运行。

python -m pip install --upgrade "mujoco==3.12.0"

from pathlib import Path
import mujoco

model_path = Path("robot.xml")
model = mujoco.MjModel.from_xml_path(str(model_path))
data = mujoco.MjData(model)

for _ in range(100):
    mujoco.mj_step(model, data)

assert all(map(lambda value: value == value, data.qpos))
print("模型读取与短步进完成")

这个检查只能说明“该模型在当前环境中完成了读取与短步进”。它不能证明控制品质、碰撞稳定性、真实机器人表现或训练收敛情况。若模型包含 `dcmotor`、柔性体或纹理资源，应继续做下文的针对性检查。

直流电机和新执行器应该怎样核对？

官方说明指出，新 `pid` 执行器允许从位置、速度、前馈量中选择输入，并提供可选积分与限幅能力。对于 `dcmotor`，官方同时提示其输入由新的输入签名表达，控制器增益从电压空间改为力矩空间；旧的速度模式积分项不再保留。

对已有模型，先全文检索 `dcmotor` 以及旧的 `input="position"`、`input="velocity"` 写法，再把每个执行器的输入个数、动作数组切片、增益单位和零速度设定值记录下来。发行说明给出了旧输入到 `pos`、`vel` 的迁移方向，并说明了与电机常数、电阻相关的增益换算。由于这些量依赖具体模型参数，本文不代替读者填入数值；应以官方迁移说明和本项目的原始控制器参数为准。

纹理和 MJX 调用为什么也要进入回归清单？

3.12.0 移除了自定义二进制纹理格式和“未知扩展名自动回退”的加载方式。若资产管线曾依赖这类文件，升级前应列出所有纹理路径并替换为官方接受的格式。发行说明还提示：基本几何体的二维纹理将使用规范化的纹理坐标；有限平面的纹理锚点从中心移到左下角。因此，画面不一致不一定是相机或光照参数错误。

如果项目使用 MJX 渲染，官方说明要求把返回值的最后一项更新后的数据一起接收。示意写法如下，具体函数参数仍应以项目所用 API 版本为准：

pixels, depth, data = mjx.render(model, data, renderer_context)

这段代码是发行说明描述的解包形状示意，不包含可直接运行的完整场景配置。

“最高两倍”应该怎样读？

官方说明提到：大网格的凸碰撞检测在某些场景中最高可有两倍加速。它没有说明所有模型、所有碰撞形状或所有硬件都会得到相同增益。将这类数字放回评测条件中理解，才不会把发行说明误写成通用性能承诺。

更稳妥的复测方式是固定模型、时间步长、求解器、随机种子、相机和硬件，分别记录升级前后的：

• 单步耗时与整段轨迹耗时；

• 接触数量、穿透或不稳定的失败类型；

• 任务完成条件、成功次数与总试验次数；

• 渲染截图与关键传感器输出。

只有在相同条件下，版本前后的数字才适合并列比较。仿真速度变化也不能直接推出真实系统会更快或更稳定。

一份可复用的升级清单

1. 固定旧版本的依赖、模型、资源、种子、截图和关键指标。

2. 在新版本中先完成读取与短步进，不通过就不要进入长训练。

3. 检查执行器输入、纹理格式、有限平面画面和渲染返回值。

4. 使用相同任务条件复测，并把失败案例与数值一起保存。

这份清单适合把版本升级变成一次可审计的实验，而不是一次不可解释的“重跑”。对涉及真实机械臂、移动底盘或人机共处环境的项目，仿真通过后仍应按设备厂商说明、场地规则和安全流程做独立验证。

常见问题

是否必须马上升级到 3.12？

不一定。是否升级取决于项目是否需要新功能、修复或兼容性支持，以及是否有时间完成回归验证。官方发行说明列出了多个破坏性变化，已有稳定实验应先建立可回退的对照环境。

模型能加载，是否可以认为迁移完成？

不可以。加载只覆盖读取层。控制输入、纹理画面、碰撞行为和任务结果仍需要按项目场景分别检查。

仿真结果更快，是否代表真实机器人更好？

不代表。发行说明中的碰撞加速是特定仿真条件下的结论；真实系统还受传感、执行器、通信时延、环境变化和安全限制影响。

来源与事实边界

• MuJoCo 3.12.0 官方发行说明：<https://github.com/google-deepmind/mujoco/releases/tag/3.12.0>

• MuJoCo 官方概览文档：<https://mujoco.readthedocs.io/en/stable/overview.html>

• MuJoCo 官方变更日志：<https://mujoco.readthedocs.io/en/stable/changelog.html>

• MuJoCo 官方 Python 文档：<https://mujoco.readthedocs.io/en/stable/python.html>

本文中的发布时间、功能、迁移方向和性能条件均以第一条官方发行说明为依据；表格、清单和检查顺序是面向开发者的原创整理。没有对任何机器人、模型或硬件进行独立实测，也不承诺升级后的性能、稳定性或真实部署效果。