2.1 章节目标 上下文回顾在 01 章看完七层架构全景之后你现在站在 L1 模型描述层的入口。本章不涉及任何代码编写——它的唯一目标是让你在 30 分钟内把环境搭好、把 ElectronBot 的 MJCF 模型加载到 MuJoCo Viewer 里、看到 6 个关节自由转动。这是全书的Hello World如果这一步走不通后续的仿真、控制、AI 训练都无从谈起。依赖栈的设计有意做得极简——venv 虚拟环境 pip install mujoco 一个 assets/ 目录不需要 Docker、不需要 GPU、不需要 ROS。 核心概念MuJoCo 依赖栈的极简设计为什么 ElectronBot-SIM 的依赖栈如此简洁三个设计意图Python 3.11 是硬要求MuJoCo 3.x 的 Python binding 基于 Python 3.8选 3.11 是因为它是 PyTorch/robomimic/stable-baselines3 等 AI 生态当前最稳定的版本。低于 3.10 的部分 binding 不可用。使用 venv 而非系统 pipvenv 是 Python 3.3 内置的虚拟环境模块无需额外安装能干净地隔离项目依赖避免与系统 Python 包冲突。CUDA 通过系统 apt 安装版本管理清晰独立。没有 Docker、没有 ROS、没有 GPU 要求这是故意的。仿真核心L2-L4完全 CPU 可跑AI 训练L6可选 GPU 加速。最低配置只需要 4 核 CPU 16GB RAM。核心关键词Python 3.11MuJoCo 3.xMJCFGLFWassetsGymnasiumEGL2.1 先认识 assets/——你的原材料仓库在装任何依赖之前先看一眼项目根目录下的assets/。这里存放着 ElectronBot-SIM 的全部原材料——没有它们后面的仿真、动作、AI 训练都无从谈起子目录内容在架构中的角色assets/cad/ElectronBot.step30.5MB、cadelectron.FCStdL1 输入稚晖君原版 CAD 设计图24 个零件的精确尺寸和装配关系。第三章的起点。assets/meshes/5 个 STL 文件base_link / body / head / left_arm / right_armL1 中间产物从 CAD 按运动组合并导出的三角网格。每个 STL 对应一个在仿真中独立运动的刚体组。assets/mjcf/electronbot_full_arm.xml~1.7MB、electronbot.xml、scene_single.xml / scene_dual.xmlL1 最终输出MuJoCo 可直接加载的物理模型。full_arm 版使用 inline mesh单文件自包含零外部依赖——这就是你这章要加载的文件。这里有一个值得理解的细节为什么 STL 是 5 个而不是 24 个ElectronBot 的 CAD 原始设计有 24 个独立零件左右手的外壳、骨架、连接件等但如果按每个零件单独导出 STLMJCF 中需要定义 24 个 body——不仅工作量大而且很多相邻零件之间根本没有相对运动比如左手的 6 个零件在运动中始终一起动。第三章会详细展开这个按运动组合并的核心决策——现在你只需要知道5 个 STL 对应 5 个运动组每个组内的零件在物理上固连不需要独立建模。2.2 环境依赖为什么是这些Python 3.11看起来像是一个平淡无奇的要求但背后有具体的技术原因。MuJoCo 的 Python bindingmujoco包要求 Python ≥ 3.8而选 3.11 是因为① 它是 PyTorch 2.x、robomimic、stable-baselines3 在 2024-2025 年最稳定的 Python 版本② 3.12/3.13 的部分 C 扩展特别是 EGL headless 渲染相关尚未完全适配③ 3.11 的性能比 3.8/3.9 有显著提升。验证命令python3--versionPython venv 虚拟环境本书的所有操作都在一个名为.venv的 venv 隔离环境中进行。用 Python 自带的 venv 而非系统 pip是为了避免项目依赖污染系统 Python 环境。CUDA 工具包通过系统 apt 安装版本管理清晰独立。创建环境python3-mvenv .venv--pythonpython3.11source.venv/bin/activateMuJoCo 3.x核心物理引擎MuJoCo 是 ElectronBot-SIM 的物理心脏——所有刚体动力学、碰撞检测、关节运动都由它计算。安装只需要一行 pip因为 Google 在 2021 年收购 DeepMind 后将 MuJoCo 开源并以预编译 wheel 分发。注意版本号pipinstallmujoco python3-cimport mujoco; print(mujoco.__version__)# 应输出 ≥ 3.2.0≥ 3.2.0 是因为这个版本引入了 passive viewer 的线程安全改进对后续的 Gymnasium 环境封装第四章至关重要。Gymnasium NumPy OpenCV这三个包在第四章才会正式用到但在这里一并安装可以避免后续的版本冲突。Gymnasium 是 OpenAI Gym 的继任者提供标准 RL 环境接口reset()/step()/render()。NumPy 是所有数值计算的基础。OpenCV 用于 MuJoCo 摄像头渲染的图像处理L5 传感器层。pipinstallgymnasium numpy scipy opencv-python trimeshGLFW视窗渲染MuJoCo Viewer 依赖 GLFW 创建本地渲染窗口。Windows 上 GLFW 随 mujoco wheel 内置macOS 需要brew install glfwLinux 需要apt install libglfw3-dev。如果你不需要在本地窗口中看机器人、只跑 headless 训练EGL 模式下不需要 GLFW这一步可以跳过。组件WindowsmacOSLinuxPython3.11 (winget)3.11 (brew)3.11 (apt)MuJoCopip install mujocopip install mujocopip install mujocoGLFW内置无需手动安装brew install glfwapt install libglfw3-devFreeCAD.msi 安装包.dmg 安装包AppImage / aptGPUCUDA 12.x (可选)Metal (MPS, 内置)CUDA 12.x (可选)2.3 实操我的搭建过程我在 Ubuntu 22.04、i9-11900、RTX 2060 12GB 的开发机上走完整条流程记录如下——你可以逐行复制、逐行验证# 步骤 1确认 Python 版本python3--version# → Python 3.11.x# 步骤 2创建 venv 环境python3-mvenv .venv--pythonpython3.11source.venv/bin/activate# 步骤 3安装核心依赖pipinstallmujoco gymnasium numpy scipy opencv-python trimesh# 步骤 4验证 MuJoCo 导入python3-cimport mujoco; print(mujoco.__version__)# → 3.2.x# 步骤 5验证 assets 目录完整性lsassets/cad/ElectronBot.step# 必须存在30.5MBlsassets/meshes/base_link.stl# 必须存在~1.1MBlsassets/mjcf/electronbot_full_arm.xml# 必须存在~1.7MB# 步骤 6加载模型——这是你看到的第一个成果python3-mmujoco.viewer--mjcfassets/mjcf/electronbot_full_arm.xml最后一步会在屏幕上弹出一个 MuJoCo 窗口里面是一个银色双臂机器人。用鼠标拖拽可以旋转视角按 Tab 键切换自由视角/跟踪视角。如果你看到了它——环境搭建成功。下一节我们让它的关节动起来。 关键词释义术语定义MuJoCoMulti-Joint dynamics with ContactGoogle 维护的开源刚体动力学仿真器RK4 积分器原生 Python binding。MJCFMuJoCo XML 模型格式定义 body/joint/geom/actuator 的层级树。inline mesh 版将 STL 网格嵌入 XML 中实现单文件自包含。GLFW跨平台 OpenGL 窗口库MuJoCo Viewer 用它在本地创建渲染窗口。headless 训练模式EGL不需要 GLFW。EGLEmbedded-system Graphics Library无头渲染接口。在服务器上训练 RL 策略时MuJoCo 通过 EGL 在 GPU 上离屏渲染不需要物理显示器。 本节涉及的资源文件assets/cad/ElectronBot.step— 原始 CAD 图纸30.5MB24 零件第三章建模的输入assets/meshes/base_link.stl— 底座 2 零件合并 STL~1.1MBassets/mjcf/electronbot_full_arm.xml— 主 MJCF 模型inline mesh~1.7MB 单文件零外部依赖assets/mjcf/scene_single.xml— 右臂场景入口include electronbot.xmlassets/mjcf/scene_dual.xml— 双臂场景入口含左右双臂⚙️ 本节逻辑认识原材料assets/ 的三个子目录分别对应 L1 的输入CAD、中间产物STL、输出MJCF。理解依赖栈Python 3.11 → venv 隔离 → pip mujoco → GLFW 渲染。每层的选择都有技术原因不是碰巧能用。逐行执行6 步搭建命令每步都可以独立验证。最后一行mujoco.viewer是你得到的第一个可见成果。进入下一节环境就绪后02-02 将通过键盘交互验证 6 个关节的运动范围和映射关系。
02-01-确认环境依赖（全平台发布）
发布时间：2026/7/10 1:08:54
2.1 章节目标 上下文回顾在 01 章看完七层架构全景之后你现在站在 L1 模型描述层的入口。本章不涉及任何代码编写——它的唯一目标是让你在 30 分钟内把环境搭好、把 ElectronBot 的 MJCF 模型加载到 MuJoCo Viewer 里、看到 6 个关节自由转动。这是全书的Hello World如果这一步走不通后续的仿真、控制、AI 训练都无从谈起。依赖栈的设计有意做得极简——venv 虚拟环境 pip install mujoco 一个 assets/ 目录不需要 Docker、不需要 GPU、不需要 ROS。 核心概念MuJoCo 依赖栈的极简设计为什么 ElectronBot-SIM 的依赖栈如此简洁三个设计意图Python 3.11 是硬要求MuJoCo 3.x 的 Python binding 基于 Python 3.8选 3.11 是因为它是 PyTorch/robomimic/stable-baselines3 等 AI 生态当前最稳定的版本。低于 3.10 的部分 binding 不可用。使用 venv 而非系统 pipvenv 是 Python 3.3 内置的虚拟环境模块无需额外安装能干净地隔离项目依赖避免与系统 Python 包冲突。CUDA 通过系统 apt 安装版本管理清晰独立。没有 Docker、没有 ROS、没有 GPU 要求这是故意的。仿真核心L2-L4完全 CPU 可跑AI 训练L6可选 GPU 加速。最低配置只需要 4 核 CPU 16GB RAM。核心关键词Python 3.11MuJoCo 3.xMJCFGLFWassetsGymnasiumEGL2.1 先认识 assets/——你的原材料仓库在装任何依赖之前先看一眼项目根目录下的assets/。这里存放着 ElectronBot-SIM 的全部原材料——没有它们后面的仿真、动作、AI 训练都无从谈起子目录内容在架构中的角色assets/cad/ElectronBot.step30.5MB、cadelectron.FCStdL1 输入稚晖君原版 CAD 设计图24 个零件的精确尺寸和装配关系。第三章的起点。assets/meshes/5 个 STL 文件base_link / body / head / left_arm / right_armL1 中间产物从 CAD 按运动组合并导出的三角网格。每个 STL 对应一个在仿真中独立运动的刚体组。assets/mjcf/electronbot_full_arm.xml~1.7MB、electronbot.xml、scene_single.xml / scene_dual.xmlL1 最终输出MuJoCo 可直接加载的物理模型。full_arm 版使用 inline mesh单文件自包含零外部依赖——这就是你这章要加载的文件。这里有一个值得理解的细节为什么 STL 是 5 个而不是 24 个ElectronBot 的 CAD 原始设计有 24 个独立零件左右手的外壳、骨架、连接件等但如果按每个零件单独导出 STLMJCF 中需要定义 24 个 body——不仅工作量大而且很多相邻零件之间根本没有相对运动比如左手的 6 个零件在运动中始终一起动。第三章会详细展开这个按运动组合并的核心决策——现在你只需要知道5 个 STL 对应 5 个运动组每个组内的零件在物理上固连不需要独立建模。2.2 环境依赖为什么是这些Python 3.11看起来像是一个平淡无奇的要求但背后有具体的技术原因。MuJoCo 的 Python bindingmujoco包要求 Python ≥ 3.8而选 3.11 是因为① 它是 PyTorch 2.x、robomimic、stable-baselines3 在 2024-2025 年最稳定的 Python 版本② 3.12/3.13 的部分 C 扩展特别是 EGL headless 渲染相关尚未完全适配③ 3.11 的性能比 3.8/3.9 有显著提升。验证命令python3--versionPython venv 虚拟环境本书的所有操作都在一个名为.venv的 venv 隔离环境中进行。用 Python 自带的 venv 而非系统 pip是为了避免项目依赖污染系统 Python 环境。CUDA 工具包通过系统 apt 安装版本管理清晰独立。创建环境python3-mvenv .venv--pythonpython3.11source.venv/bin/activateMuJoCo 3.x核心物理引擎MuJoCo 是 ElectronBot-SIM 的物理心脏——所有刚体动力学、碰撞检测、关节运动都由它计算。安装只需要一行 pip因为 Google 在 2021 年收购 DeepMind 后将 MuJoCo 开源并以预编译 wheel 分发。注意版本号pipinstallmujoco python3-cimport mujoco; print(mujoco.__version__)# 应输出 ≥ 3.2.0≥ 3.2.0 是因为这个版本引入了 passive viewer 的线程安全改进对后续的 Gymnasium 环境封装第四章至关重要。Gymnasium NumPy OpenCV这三个包在第四章才会正式用到但在这里一并安装可以避免后续的版本冲突。Gymnasium 是 OpenAI Gym 的继任者提供标准 RL 环境接口reset()/step()/render()。NumPy 是所有数值计算的基础。OpenCV 用于 MuJoCo 摄像头渲染的图像处理L5 传感器层。pipinstallgymnasium numpy scipy opencv-python trimeshGLFW视窗渲染MuJoCo Viewer 依赖 GLFW 创建本地渲染窗口。Windows 上 GLFW 随 mujoco wheel 内置macOS 需要brew install glfwLinux 需要apt install libglfw3-dev。如果你不需要在本地窗口中看机器人、只跑 headless 训练EGL 模式下不需要 GLFW这一步可以跳过。组件WindowsmacOSLinuxPython3.11 (winget)3.11 (brew)3.11 (apt)MuJoCopip install mujocopip install mujocopip install mujocoGLFW内置无需手动安装brew install glfwapt install libglfw3-devFreeCAD.msi 安装包.dmg 安装包AppImage / aptGPUCUDA 12.x (可选)Metal (MPS, 内置)CUDA 12.x (可选)2.3 实操我的搭建过程我在 Ubuntu 22.04、i9-11900、RTX 2060 12GB 的开发机上走完整条流程记录如下——你可以逐行复制、逐行验证# 步骤 1确认 Python 版本python3--version# → Python 3.11.x# 步骤 2创建 venv 环境python3-mvenv .venv--pythonpython3.11source.venv/bin/activate# 步骤 3安装核心依赖pipinstallmujoco gymnasium numpy scipy opencv-python trimesh# 步骤 4验证 MuJoCo 导入python3-cimport mujoco; print(mujoco.__version__)# → 3.2.x# 步骤 5验证 assets 目录完整性lsassets/cad/ElectronBot.step# 必须存在30.5MBlsassets/meshes/base_link.stl# 必须存在~1.1MBlsassets/mjcf/electronbot_full_arm.xml# 必须存在~1.7MB# 步骤 6加载模型——这是你看到的第一个成果python3-mmujoco.viewer--mjcfassets/mjcf/electronbot_full_arm.xml最后一步会在屏幕上弹出一个 MuJoCo 窗口里面是一个银色双臂机器人。用鼠标拖拽可以旋转视角按 Tab 键切换自由视角/跟踪视角。如果你看到了它——环境搭建成功。下一节我们让它的关节动起来。 关键词释义术语定义MuJoCoMulti-Joint dynamics with ContactGoogle 维护的开源刚体动力学仿真器RK4 积分器原生 Python binding。MJCFMuJoCo XML 模型格式定义 body/joint/geom/actuator 的层级树。inline mesh 版将 STL 网格嵌入 XML 中实现单文件自包含。GLFW跨平台 OpenGL 窗口库MuJoCo Viewer 用它在本地创建渲染窗口。headless 训练模式EGL不需要 GLFW。EGLEmbedded-system Graphics Library无头渲染接口。在服务器上训练 RL 策略时MuJoCo 通过 EGL 在 GPU 上离屏渲染不需要物理显示器。 本节涉及的资源文件assets/cad/ElectronBot.step— 原始 CAD 图纸30.5MB24 零件第三章建模的输入assets/meshes/base_link.stl— 底座 2 零件合并 STL~1.1MBassets/mjcf/electronbot_full_arm.xml— 主 MJCF 模型inline mesh~1.7MB 单文件零外部依赖assets/mjcf/scene_single.xml— 右臂场景入口include electronbot.xmlassets/mjcf/scene_dual.xml— 双臂场景入口含左右双臂⚙️ 本节逻辑认识原材料assets/ 的三个子目录分别对应 L1 的输入CAD、中间产物STL、输出MJCF。理解依赖栈Python 3.11 → venv 隔离 → pip mujoco → GLFW 渲染。每层的选择都有技术原因不是碰巧能用。逐行执行6 步搭建命令每步都可以独立验证。最后一行mujoco.viewer是你得到的第一个可见成果。进入下一节环境就绪后02-02 将通过键盘交互验证 6 个关节的运动范围和映射关系。
