第一章：MuJoCo简介与环境搭建 - 常见安装失败与路径配置错误

各位同学好。咱们这门课叫《MuJoCo模型导入常见错误与修复》，第一章先不急着碰模型，得先把“地基”打牢。MuJoCo这个物理引擎，说实话，安装过程不算复杂，但坑是真不少。我这些年带团队，光是帮新人排查环境问题，就占了将近一半的入门时间。

今天咱们就把这些“拦路虎”一个个揪出来，讲清楚。

1.1 MuJoCo是什么？我们为什么用它？

MuJoCo，全称是Multi-Joint dynamics with Contact。说白了，它是一个专门做机器人仿真、多刚体动力学计算的物理引擎。跟Gazebo、PyBullet比起来，它的特点是快、准、稳。

• 快：计算效率高，能跑实时甚至超实时仿真。
• 准：对接触、摩擦、关节约束的模拟非常精确。
• 稳：数值稳定性好，不容易“炸掉”。

我个人习惯把它比作“仿真界的瑞士军刀”。你想想看，从四足机器人到灵巧手，从强化学习训练到运动规划验证，它几乎都能胜任。DeepMind后来把它开源了，现在用的人越来越多。

1.2 环境搭建：两种主流方式

搭建环境，我建议你直接走Python路线。MuJoCo官方提供了Python绑定，叫mujoco。安装方式主要有两种：

方式	命令	适用场景
pip安装（推荐）	pip install mujoco	大多数用户，快速上手
源码编译	从GitHub克隆后CMake编译	需要修改底层代码或定制功能

我个人强烈建议新手用pip。别折腾源码编译，除非你确实有特殊需求。我曾经有个学员，非要从源码编译，结果折腾了两天，最后发现只是少装了一个依赖库。

1.3 常见安装失败：问题与对策

安装失败，通常就这几种情况。我按出现频率排个序：

1. 网络问题导致下载超时
2. 缺少C++运行时库
3. Python版本不兼容
4. 虚拟环境冲突

咱们一个一个看。

1.3.1 网络超时

这是最常见的。MuJoCo的安装包大概几十MB，如果网络不稳定，很容易下载到一半就断了。

解决办法： 使用国内镜像源。

pip install mujoco -i https://pypi.tuna.tsinghua.edu.cn/simple

嗯，这里要注意。如果你用的是conda环境，记得先激活环境再执行上面的命令。

1.3.2 缺少C++运行时库

MuJoCo底层是C++写的，所以需要系统有对应的运行时库。Windows上通常是VC++ Redistributable，Linux上则是libglfw3和libglew2.1。

Windows用户： 去微软官网下载安装“Visual C++ Redistributable for Visual Studio 2015-2022”。

Linux用户： 执行以下命令：

sudo apt update
sudo apt install libglfw3 libglfw3-dev libglew2.1 libglew-dev

我曾经在Ubuntu 20.04上遇到过一个问题，装完libglfw3后还是报错。后来发现是libglew2.1的版本不对，换成libglew2.2就好了。所以，如果默认版本不行，试试高一个版本。

1.3.3 Python版本不兼容

MuJoCo的Python绑定对Python版本有要求。目前（2024年），它支持Python 3.8到3.12。如果你用的是Python 3.7或更早版本，安装时会直接报错。

检查你的Python版本：

python --version

如果版本太低，建议用conda创建一个新环境：

conda create -n mujoco_env python=3.10
conda activate mujoco_env

1.3.4 虚拟环境冲突

很多人喜欢用conda管理环境。但有时候，conda环境里的包会和pip安装的MuJoCo冲突。表现就是安装成功，但导入时报错。

我的建议： 创建一个全新的虚拟环境，只安装MuJoCo和它的依赖。不要在一个已经装了很多包的环境里硬装。

1.4 路径配置错误：一个容易忽视的坑

安装成功后，下一步就是导入模型。这时候，路径问题就来了。

MuJoCo在加载模型时，需要知道模型文件（.xml或.mjb）在哪里。如果你把模型文件放在当前目录下，那没问题。但如果你放在子目录里，或者引用了其他资源文件（比如纹理、网格），就很容易出错。

错误示例：

import mujoco

# 错误：模型文件不在当前目录
model = mujoco.MjModel.from_xml_path("my_robot.xml")

这段代码会报错：FileNotFoundError。

正确做法： 使用路径，或者用os.path拼接路径。

import mujoco
import os

# 获取当前脚本所在目录
script_dir = os.path.dirname(os.path.abspath(__file__))
# 拼接模型文件路径
model_path = os.path.join(script_dir, "models", "my_robot.xml")

model = mujoco.MjModel.from_xml_path(model_path)

我个人习惯把模型文件放在一个叫models的子目录里，这样项目结构清晰。你想想看，如果所有文件都堆在根目录，后期维护起来多麻烦。

1.5 知识体系总览

下面这张图，把本章的核心知识点串起来了。你可以把它当作一个“安装排错地图”。

1.6 验证安装：跑一个简单的例子

环境搭好了，怎么确认它真的能用？写个最简单的测试脚本。

import mujoco
import mujoco.viewer

# 加载MuJoCo自带的模型
model = mujoco.MjModel.from_xml_path(mujoco.models.get_path("humanoid.xml"))
data = mujoco.MjData(model)

# 启动可视化窗口
with mujoco.viewer.launch_passive(model, data) as viewer:
  # 仿真100步
  for _ in range(100):
    mujoco.mj_step(model, data)
    viewer.sync()

如果这段代码能正常运行，弹出一个窗口，里面有一个站立的人形机器人，那恭喜你，环境搭建成功了。

1.7 避坑指南：我的血泪史

最后，分享几个我踩过的坑，希望能帮你省点时间。

• 我曾经在Windows上装完MuJoCo后，一运行就报DLL load failed。查了半天，发现是系统PATH环境变量里没有包含MuJoCo的bin目录。手动加上就好了。
• 我曾经在Linux上遇到libGL error: failed to load driver: swrast。这是因为系统缺少OpenGL的软件渲染库。安装libgl1-mesa-glx和libgl1-mesa-dri就能解决。
• 我曾经在macOS上遇到mujoco.viewer无法启动。这是因为macOS的权限限制。需要在“系统偏好设置 -> 安全性与隐私 -> 隐私 -> 屏幕录制”中，允许你的终端或IDE录制屏幕。

嗯，环境搭建这部分，说难不难，说简单也不简单。关键是要有耐心，遇到错误别慌，先看错误信息，再上网搜。大部分问题，Stack Overflow上都有答案。

好了，这一章就到这里。记住，环境是基础，基础不牢，地动山摇。把这一步走稳了，后面咱们才能安心地跟模型错误“过招”。