📚 课程目录第2章环境搭建与工具链

环境搭建与工具链：安装 MuJoCo 2.3.7 与 Python 绑定

说实话，很多初学者在 MuJoCo 上栽的第一个跟头，不是模型写不对，而是环境没配好。我见过有人花了两天时间，最后发现是 Python 和 MuJoCo 的版本对不上。嗯，咱们先把这条路铺平。

为什么选 2.3.7？

你可能要问，现在都出到 3.x 了，为什么我还揪着 2.3.7 不放？

原因很简单——稳定。我在项目里用 2.3.7 跑过上千小时的仿真，踩过的坑基本都填平了。而且目前主流的机器人仿真框架（比如 dm_control、robosuite）对 2.3.7 的支持最成熟。你想想看，如果为了追新版本，结果发现某个关键 API 变了，整个项目都得重写，那多划不来。

  核心原则： 仿真环境搭建，稳定压倒一切。2.3.7 是目前生产环境中最稳妥的选择。

安装流程：三步走

我个人习惯把安装拆成三个独立步骤，这样万一哪一步出问题，排查起来也快。

第一步：安装 MuJoCo 2.3.7 本体

先去 MuJoCo 的 GitHub Releases 页面下载对应系统的压缩包。Windows 选 mujoco-2.3.7-windows-x86_64.zip，Linux 选 mujoco-2.3.7-linux-x86_64.tar.gz，macOS 选 mujoco-2.3.7-macos-x86_64.tar.gz。

下载后解压到一个固定路径。我建议放在用户目录下：

# Linux / macOS 示例
cd ~
tar -xzf mujoco-2.3.7-linux-x86_64.tar.gz
mv mujoco-2.3.7 ~/.mujoco/mujoco237

# Windows 示例（PowerShell）
Expand-Archive .\mujoco-2.3.7-windows-x86_64.zip -DestinationPath $env:USERPROFILE\.mujoco\mujoco237

注意： 路径里不要有中文或空格。我曾经因为把 MuJoCo 装在 "Program Files" 下，结果 Python 绑定死活找不到库文件，折腾了一下午才发现是路径空格的问题。

第二步：配置环境变量

这一步很多人会忽略，但少了它，Python 绑定就找不到 MuJoCo 的动态链接库。

# Linux / macOS 添加 ~/.bashrc 或 ~/.zshrc
export MUJOCO_PATH=$HOME/.mujoco/mujoco237
export LD_LIBRARY_PATH=$MUJOCO_PATH/bin:$LD_LIBRARY_PATH
export PATH=$MUJOCO_PATH/bin:$PATH

# Windows 系统环境变量
# 新建 MUJOCO_PATH = %USERPROFILE%\.mujoco\mujoco237
# 在 Path 中添加 %MUJOCO_PATH%\bin

配置完后，打开新终端，输入 simulate 看看能不能启动 MuJoCo 的图形界面。如果能看到一个带机器人模型的窗口，说明本体安装成功了。

第三步：安装 Python 绑定（mujoco）

MuJoCo 官方从 2.1.0 开始提供了 Python 绑定，包名就叫 mujoco。安装很简单：

pip install mujoco==2.3.7

这里有个细节——版本号必须严格对应。如果你装的是 mujoco 2.3.7 本体，Python 绑定也必须装 2.3.7。版本不匹配的话，轻则报错，重则仿真结果莫名其妙地不对。

小技巧： 我习惯用虚拟环境来隔离项目。比如用 conda 创建一个专门的环境：conda create -n mujoco_env python=3.9，然后在里面装 mujoco。这样即使多个项目用的 MuJoCo 版本不同，也不会互相干扰。

验证安装：跑一个最小示例

装完别急着走，咱们得验证一下。写一个最简单的 Python 脚本：

import mujoco
import numpy as np

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

# 前进一步仿真
mujoco.mj_step(model, data)

# 打印躯干位置
print(f"躯干位置: {data.qpos[:3]}")
print(f"仿真时间: {data.time:.4f} 秒")
print(f"MuJoCo 版本: {mujoco.__version__}")

如果输出类似下面这样，说明环境搭建成功了：

躯干位置: [0. 0. 1.282]
仿真时间: 0.0020 秒
MuJoCo 版本: 2.3.7

知识体系总览

下面这张图把整个环境搭建的脉络梳理清楚了。你可以把它当作一个检查清单，每完成一项就打个勾。

常见问题与避坑指南

环境搭建这块，我总结了几个高频问题，你遇到了可以直接对照排查。

问题现象	可能原因	解决方案
`ImportError: libmujoco.so: cannot open shared object file`	LD_LIBRARY_PATH 未正确设置	检查环境变量，确保指向 MuJoCo 的 bin 目录
`mujoco.FatalError: XML parsing failed`	模型文件路径错误或 XML 语法问题	使用路径，或检查 XML 文件格式
`simulate 命令找不到`	PATH 环境变量未包含 MuJoCo bin 目录	重新加载 shell 配置或重启终端
Python 绑定版本与本体不一致	pip 安装了不同版本的 mujoco	`pip install mujoco==2.3.7` 强制指定版本

我曾经踩过的坑： 有一次在服务器上部署，明明所有环境变量都配好了，但 Python 就是报找不到库。最后发现是系统里同时装了多个版本的 MuJoCo，动态链接器加载了错误的版本。解决方案是把其他版本的路径从 LD_LIBRARY_PATH 里移除，只保留 2.3.7 的路径。

验证清单

最后，给你一个自检清单。每完成一项，心里就有底一分。

MuJoCo 本体：simulate 命令能正常启动图形界面
Python 绑定：import mujoco 不报错
版本一致：mujoco.__version__ 输出 2.3.7
模型加载：能成功加载 humanoid.xml 并执行一步仿真
路径稳定：关闭终端再打开，上述验证依然通过

到这步，你的 MuJoCo 环境就算真正搭好了。接下来就可以放心地往里塞模型、调参数了。