mujoco学习
仿真搭建。
MuJoCo 学习
初版
这套笔记面向从零开始学习 MuJoCo 的工程复现路线。目标不是只让你复制代码跑通，而是让你看懂：
- MuJoCo 模型文件在描述什么。
- Python 代码怎样读取和推进仿真。
qpos、qvel、ctrl这些数组为什么重要。- 如何从一个会掉落的小方块，逐步搭出 Cartpole、Reacher 和 Gymnasium 风格环境。
默认环境为 Fedora 44、Python >= 3.10、mujoco>=2.3 官方 Python bindings。
注意：本文禁止使用 mujoco-py。所有示例均使用：
import mujoco
适合谁阅读
如果你符合下面任意一种情况，可以从第 1 章开始按顺序学：
- 没学过 MuJoCo，只会一点 Python。
- 看过强化学习环境，但不知道 MuJoCo 环境是怎么写出来的。
- 想复现机器人控制、模仿学习、VLA 数据采集，但对仿真模型没有概念。
- 以前接触过
mujoco-py，现在想迁移到官方mujocoPython bindings。
阅读前只需要知道 Python 的变量、函数、列表或数组大概是什么。NumPy 不熟也没关系，教程会尽量解释每个数组的含义。
MuJoCo 到底是什么
MuJoCo 是一个物理仿真引擎。你可以把它理解成一个“机器人和物体的虚拟实验室”：
你写 XML 描述世界里有什么
↓
MuJoCo 编译成物理模型
↓
Python 程序给关节或电机输入控制量
↓
MuJoCo 按物理规律更新位置、速度、碰撞、力
↓
你读取状态、计算奖励、保存数据或训练策略
在机器人、强化学习和具身智能里，MuJoCo 常用于：
- 搭建机械臂、小车、摆杆、多足机器人等模型。
- 快速测试控制算法，不必一开始就上真实机器人。
- 生成强化学习环境。
- 采集状态、动作、图像、奖励等训练数据。
学习前的心智模型
新手最容易卡在“XML 和 Python 代码到底谁负责什么”。可以先记住这个分工：
| 部分 | 负责什么 | 例子 |
|---|---|---|
| MJCF XML | 定义世界和机器人结构 | 地面、盒子、关节、电机、摄像头 |
MjModel | 编译后的静态模型 | 有几个关节、有几个电机、时间步长是多少 |
MjData | 运行中的动态状态 | 当前时间、位置、速度、电机输入 |
mj_step | 推进一步物理仿真 | 根据重力、力、碰撞更新状态 |
| Viewer / Renderer | 把仿真显示出来 | 打开窗口或保存图片 |
一句话总结：
XML 决定“有什么”，MjModel 记住“结构”，MjData 记录“现在怎样”，mj_step 让时间往前走。
参考来源：
- MuJoCo Python 官方文档：https://mujoco.readthedocs.io/en/stable/python.html
- MuJoCo XML Reference：https://mujoco.readthedocs.io/en/stable/XMLreference.html
- MuJoCo Overview：https://mujoco.readthedocs.io/en/stable/overview.html
章节目录
- 环境安装与第一个 MuJoCo 程序
- XML 与 MJCF 物理建模基础
- Python 控制接口：读取状态与推进仿真
- 关节、Actuator 与力控制
- Viewer 可视化与 Renderer 离屏渲染
- 控制任务：Cartpole
- 控制任务：Reacher 机械臂到达目标
- Gymnasium 风格强化学习接口基础
推荐学习路线
环境安装
→ XML / MJCF 建模
→ MjModel / MjData
→ mj_step 控制循环
→ joint / actuator
→ viewer / renderer
→ cartpole / reacher
→ Gymnasium 环境接口
→ imitation learning / VLA 数据采集
不要跳过第 1 到第 4 章。后面的 Cartpole、Reacher 和 Gymnasium 环境，本质上都是在反复使用前面这几个核心概念。
建议的目录结构
为了避免代码散落，建议你在任意工作目录下新建一个学习文件夹：
mkdir -p mujoco_tutorial
cd mujoco_tutorial
每一章的代码都单独保存：
mujoco_tutorial/
├── ch1_first_sim.py
├── ch2_xml_basic.py
├── ch3_python_state.py
├── ch4_joint_motor.py
├── ch5_viewer.py
├── ch5_renderer.py
├── ch6_cartpole.py
├── ch7_reacher.py
└── ch8_gym_env.py
这样出错时，你可以确认到底是哪一章的代码有问题。
学习方法
每章建议按这个顺序操作：
- 先读“核心概念解释”，不用追求一次看懂所有细节。
- 复制最小可运行代码，保存成指定文件。
- 运行代码，确认没有报错。
- 对照“运行结果说明”理解输出。
- 做“验证步骤”，主动改一两个参数。
- 遇到报错先看“常见错误与解决方案”。
不要只看不跑。MuJoCo 的学习重点是“改参数以后观察物理结果”，比如把重力变小、把电机力变大、把初始高度变高。只要你能预测并解释这些变化，就说明你真正理解了。
全局排错顺序
遇到问题时，按下面顺序查：
- Python 环境是否激活：
which python - MuJoCo 是否能导入：
python -c "import mujoco; print(mujoco.__version__)" - 是否误装了
mujoco-py - XML 标签是否闭合、属性是否拼写正确
- actuator 引用的 joint 名字是否存在
data.ctrl的长度是否等于model.nu- 修改
qpos或qvel后是否调用了mujoco.mj_forward - 图形显示问题是否和 OpenGL、GLFW、远程服务器有关