MuJoCo 安装与部署
二、安装与部署
安装步骤
- 准备 Python 环境（建议使用独立虚拟环境，避免与系统包冲突）。
- 安装官方包
mujoco。Windows、Linux、macOS 都有对应轮子，不需要从源码编译。
- 安装可视化所需的图形依赖：本地有显示器时用默认后端即可；无头服务器上渲染需要 EGL 或软件渲染后端。
- 安装常用配套库：
dm_control（DeepMind 的控制套件）、gymnasium（标准环境接口）、模型库 mujoco_menagerie（官方整理的一批开源机器人模型）。
- 拿官方示例模型跑一次前向仿真，确认安装正常。
python3 -m venv ~/venv-mj
source ~/venv-mj/bin/activate
pip install mujoco
pip install dm-control gymnasium
git clone https://github.com/google-deepmind/mujoco_menagerie.git
python -c "import mujoco; print(mujoco.__version__)"
早年流行的 mujoco-py 已经不再维护，新项目请直接用官方包。网上大量教程仍在教 pip install mujoco-py，照做会在新版 Python 上编译失败。
无头渲染
# 服务器上使用 EGL 后端渲染
export MUJOCO_GL=egl
# 没有 GPU 时退回软件渲染（速度慢很多）
export MUJOCO_GL=osmesa
python -c "
import mujoco, mujoco.viewer, time
m = mujoco.MjModel.from_xml_string('<mujoco><worldbody><geom type=\"plane\" size=\"1 1 .1\"/></worldbody></mujoco>')
d = mujoco.MjData(m)
mujoco.mj_step(m, d)
print('ok', m.nq, d.qpos)
"
常见报错排查
| 报错 / 现象 | 原因 | 处理 |
|---|
| GLFW 相关报错、窗口起不来 | 无显示环境或图形库缺失 | 设置 MUJOCO_GL=egl 或 osmesa，或改成离线跑 |
| EGL 初始化失败 | 缺少 EGL 运行库或驱动不匹配 | 安装 EGL 相关库，确认 GPU 驱动正常；实在不行用软件渲染 |
| XML 解析报错 | 标签拼写、属性名或嵌套层级不对 | 按报错行号检查，常见是把 body 写在了 worldbody 外面 |
| 模型加载后穿透地面 | 初始位置在地面以下，或几何尺寸不合理 | 检查初始 pos 与 geom 的 size |
| 仿真发散、数值爆炸 | 时间步太大、质量太小、刚度太高 | 减小时间步，检查惯性与刚度参数 |
| 仿真跑得比预期慢 | 模型中碰撞几何过多、时间步过小 | 用简单碰撞体近似、减少网格碰撞，适当放大步长 |
| 旧教程里的接口报不存在 | 大版本之间接口有调整 | 对照所安装版本的官方文档，不要照抄老教程 |
