简介：这份资源面向具备一定C++基础、希望上手Mujoco物理引擎的机器人学与运动控制学习者，围绕「用CMake构建并运行简单动力学计算」这一目标组织内容，帮助读者打通从库配置到仿真步进的完整链路。压缩包共217个文件、约26.29MB，以txt说明、stl几何模型、cmake与make构建脚本、h头文件、cpp源码及json、xml模型描述为主，另含编译产物与urdf机器人描述文件，便于直接对照工程结构理解各模块职责。已有311人学习下载，可作为入门参考。资源中既有CMakeLists配置示例，也有加载XML模型、调用mj_step推进仿真并释放资源的代码骨架，读者可据此掌握模型加载、数据初始化与动力学步进的基本流程，并借鉴其目录组织方式排查编译链接问题，为后续多平台构建与复杂场景仿真打下基础。

1. 用 CMake 把 MuJoCo 动力学算例跑通：一份能直接复现的 C++ 工程骨架

很多人第一次碰 MuJoCo 的 C++ 接口，卡住的地方不是物理公式，而是构建系统。官方给的示例往往默认你已经把mujoco的头文件和动态库放到了系统路径里，可实际开发机上 CMake 找不到mujoco.h、链接阶段又报undefined reference to mj_step，一个简单的动力学计算能折腾一下午。这份资源就是围绕「C++ + CMake + MuJoCo」这条最小链路，把模型加载、前向动力学、状态推进、结果输出串成一个可编译、可调试的工程骨架，适合已经会写 C++、想用 MuJoCo 做仿真验证或控制器原型的人。它不追求覆盖全部 API，而是把最容易翻车的构建与调用边界先钉死，让你把注意力放回动力学本身。

2. 工程结构与 CMake 链接：先让编译器认识 MuJoCo

2.1 目录怎么摆，依赖怎么放

MuJoCo 的 C++ 使用本质上就三样东西：头文件目录、动态库（Linux 下libmujoco.so，Windows 下mujoco.dll加导入库）、以及运行时能找到库的路径。工程骨架一般长这样，我习惯把第三方依赖单独收在third_party下，避免和系统安装的版本打架：

mujoco_dyn_demo/ ├── CMakeLists.txt ├── src/ │ └── main.cpp ├── model/ │ └── arm.xml └── third_party/ └── mujoco/ ├── include/mujoco/mujoco.h └── lib/libmujoco.so

模型文件用 MuJoCo 自己的 MJCF 格式，一个两连杆摆的例子就够验证动力学了。下面这段 MJCF 定义了一个带两个 hinge 关节的刚体链，重力默认朝下，跑起来能看到关节角随重力演化：

<mujoco model="two_link"> <option timestep="0.002" gravity="0 0 -9.81"/> <worldbody> <body name="link1" pos="0 0 1"> <joint name="j1" type="hinge" axis="0 1 0"/> <geom type="capsule" fromto="0 0 0 0.3 0 0" size="0.03"/> <body name="link2" pos="0.3 0 0"> <joint name="j2" type="hinge" axis="0 1 0"/> <geom type="capsule" fromto="0 0 0 0.3 0 0" size="0.03"/> </body> </body> </worldbody> </mujoco>

timestep决定积分步长，gravity是重力加速度向量，两个hinge关节绕 y 轴转动，capsule只是可视化用的碰撞体，动力学里质量默认由 geom 的密度推算。模型不需要写<actuator>，因为这一步只做被动动力学，没有控制输入，正好用来验证mj_step是否真的在推进状态。

2.2 CMakeLists 的关键几行

真正让新手翻车的是链接。下面这份CMakeLists.txt把 include 路径、库路径、运行时 rpath 一次性配好，Linux 下拷到别的机器也能直接跑：

cmake_minimum_required(VERSION 3.16) project(mujoco_dyn_demo CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # MuJoCo 依赖根目录，允许命令行覆盖 set(MUJOCO_ROOT "${CMAKE_SOURCE_DIR}/third_party/mujoco" CACHE PATH "MuJoCo install root") find_package(Threads REQUIRED) add_executable(dyn_demo src/main.cpp) target_include_directories(dyn_demo PRIVATE "${MUJOCO_ROOT}/include") target_link_libraries(dyn_demo PRIVATE "${MUJOCO_ROOT}/lib/libmujoco.so" Threads::Threads ${CMAKE_DL_LIBS}) # 让可执行文件在构建目录直接找到 .so，省去每次设 LD_LIBRARY_PATH set_target_properties(dyn_demo PROPERTIES BUILD_RPATH "${MUJOCO_ROOT}/lib" INSTALL_RPATH "${MUJOCO_ROOT}/lib")

MUJOCO_ROOT用CACHE PATH声明，意味着你可以cmake -DMUJOCO_ROOT=/opt/mujoco ..覆盖，不用改文件。Threads::Threads和${CMAKE_DL_LIBS}是 MuJoCo 内部用到线程与动态加载时需要的，漏了会在链接期报一堆符号缺失。BUILD_RPATH是最容易被忽略的一行——没有它，编译能过，一运行就error while loading shared libraries: libmujoco.so，这是血泪经验里出现频率最高的报错之一。

2.3 最小动力学主程序

主程序只做四件事：加载模型、拿mjData、循环mj_step、打印关节角。代码短，但每一行都对应一个容易出错的 API 契约：

#include <mujoco/mujoco.h> #include <cstdio> #include <cstring> int main() { char error[1000] = ""; // 1. 加载 MJCF，失败时 error 里带具体原因 mjModel* m = mj_loadXML("model/arm.xml", nullptr, error, 1000); if (!m) { std::printf("load failed: %s\n", error); return 1; } // 2. mjData 必须由 mj_makeData 分配，不能 new mjData* d = mj_makeData(m); // 3. 给关节一个初始角速度，否则纯重力下从静止开始变化太慢 d->qvel[0] = 1.0; const int steps = 1000; for (int i = 0; i < steps; ++i) { mj_step(m, d); // 前向动力学 + 积分 if (i % 200 == 0) { std::printf("step %4d q1=%.4f q2=%.4f\n", i, d->qpos[0], d->qpos[1]); } } // 4. 释放顺序：先 data 后 model mj_deleteData(d); mj_deleteModel(m); return 0; }

mj_loadXML的第四个参数是错误缓冲区长度，传小了错误信息会被截断，排查时反而误导。mj_makeData内部按模型维度分配所有状态数组，用new mjData是典型误用，析构时会对不上。d->qvel[0]对应第一个 hinge 关节的自由度，MuJoCo 里qpos和qvel的索引按关节在模型中的声明顺序排列，多关节模型一定要先确认索引映射，别想当然。mj_step一次完成「计算加速度 → 积分位置和速度」，不需要你手动调mj_forward再积分，这是和某些教科书式写法最大的差别。

构建与运行：

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j ./build/dyn_demo

如果输出里q1、q2随时间连续变化且没有nan，说明整条链路通了。出现nan通常是模型里质量或惯量为零，或者timestep给得过大导致积分发散，先把timestep降到0.001再试。

3. 动力学计算的核心调用：mj_forward、mj_step 与状态数组

3.1 三个函数的分工别搞混

MuJoCo 的动力学 API 里，mj_forward、mj_step、mj_step1/mj_step2经常被混用。理解它们的分工，决定了你写出来的是「每步算两遍」还是「算一遍就够」：

常见误用是循环里先mj_forward再mj_step，等于每步算了两遍动力学，性能直接砍半，而且如果中间改了qpos还会引入不一致。我一般只在需要读取d->qfrc_constraint这类派生量、又不想推进时间时单独调mj_forward。

3.2 状态数组的索引映射

qpos和qvel的长度不等于关节数。hinge 和 slide 关节各占 1 个qpos，free 关节占 7 个（3 位置 + 4 四元数），ball 关节占 4 个。qvel里 free 关节占 6 个。写控制器前先打印维度核对：

std::printf("nq=%d nv=%d nu=%d\n", m->nq, m->nv, m->nu); for (int j = 0; j < m->njnt; ++j) { std::printf("joint %d: name=%s qposadr=%d dofadr=%d\n", j, mj_id2name(m, mjOBJ_JOINT, j), m->jnt_qposadr[j], m->jnt_dofadr[j]); }

jnt_qposadr和jnt_dofadr是官方给的索引映射，比自己数关节靠谱得多。多关节模型里用错索引，表现是「某个关节不动」或「力矩加到了错误的自由度上」，这类 bug 不看映射表很难定位。

3.3 加控制输入的最小改法

被动动力学验证完，下一步通常是加执行器。在 MJCF 里补一段<actuator>，主程序里写d->ctrl[0]：

<actuator> <motor joint="j1" ctrlrange="-5 5" ctrllimited="true"/> </actuator>

// 简单 PD：目标角 0，当前角 d->qpos[0] const double kp = 20.0, kd = 2.0; d->ctrl[0] = -kp * d->qpos[0] - kd * d->qvel[0]; mj_step(m, d);

ctrlrange和ctrllimited一定要设，否则 PD 输出可能瞬间超出执行器能力，仿真里表现为关节角剧烈震荡甚至发散。d->ctrl的长度是m->nu，索引按 actuator 声明顺序，和关节索引不是一回事，这点在多个执行器时尤其要小心。

4. 避坑与排查：链接、路径、数值三类高频翻车

4.1 编译过了运行报找不到 libmujoco.so

现象：cmake --build成功，执行时报error while loading shared libraries: libmujoco.so: cannot open shared object file。原因：链接期用的是绝对路径，但运行时动态加载器只查系统路径和 rpath，构建目录没被写进 rpath。解决：在CMakeLists.txt里设BUILD_RPATH（见 2.2），或者临时LD_LIBRARY_PATH=third_party/mujoco/lib ./build/dyn_demo验证。长期方案是 rpath，临时方案只用于确认问题根源。

4.2 mj_loadXML 返回空但错误信息是乱码或截断

现象：加载失败，error缓冲区里只有半句话。原因：错误缓冲区长度传得太小，或者模型路径是相对路径而工作目录不对。解决：缓冲区给到 1000 以上；路径统一用相对于可执行文件的方式，或者在 CMake 里用configure_file把模型目录绝对路径写进配置头。我一般会在加载前打印一次getcwd，确认工作目录，这个习惯省掉过很多次「明明文件在却找不到」的困惑。

4.3 仿真几步后 qpos 变成 nan

现象：前几十步正常，之后qpos出现nan并扩散到所有状态。原因：积分步长相对模型刚度太大，或者模型里某个 geom 的mass为 0、惯量矩阵奇异。解决：先把timestep减半观察是否消失；再检查 MJCF 里是否有density="0"又没显式给mass的 geom。数值发散在刚体动力学里是玄学重灾区，二分步长是最快的定位手段。

4.4 多关节模型力矩加错自由度

现象：给d->ctrl[0]赋值，动的却是另一个关节。原因：actuator 顺序和 joint 顺序不一致，ctrl索引按 actuator 排，不是按 joint 排。解决：用mj_id2name打印每个 actuator 绑定的关节名，或者直接按名字查 id 再映射，别靠声明顺序硬记。

4.5 Release 下结果和 Debug 不一致

现象：Debug 构建结果正常，Release 下轨迹偏移。原因：代码里有未初始化变量，或者浮点优化改变了累加顺序，在动力学这种对初值敏感的循环里被放大。解决：编译加-Wall -Wextra把未初始化警告打开；对比时固定timestep和初始状态，逐帧打印qpos找第一处偏差。这类问题不是 MuJoCo 的锅，但仿真会把它放大到肉眼可见。

5. 进阶验证：用能量守恒和解析解给仿真结果上保险

跑通不等于算对。动力学代码最怕「看起来在动，其实数值是错的」，我习惯用两个低成本手段做验证。第一个是能量守恒：无控制、无接触、无阻尼的被动系统，总能量应该基本恒定。在循环里加一段能量统计：

// 动能 = 0.5 * qvel^T * M * qvel，M 用 mj_fullM 取 std::vector<double> M(m->nv * m->nv); mj_fullM(m, M.data(), d->qM); double ke = 0.0; for (int i = 0; i < m->nv; ++i) for (int j = 0; j < m->nv; ++j) ke += 0.5 * d->qvel[i] * M[i * m->nv + j] * d->qvel[j]; // 势能近似：各 body 的 z 坐标乘质量乘 g，简化版够用 double pe = 0.0; for (int b = 1; b < m->nbody; ++b) pe += m->body_mass[b] * 9.81 * d->xpos[3 * b + 2]; std::printf("E=%.6f\n", ke + pe);

mj_fullM把稀疏的qM展开成稠密矩阵，小模型直接这么用没问题，大模型要注意nv平方的内存开销。能量在几百步内漂移超过百分之几，基本可以判定步长偏大或有未建模的阻尼。第二个手段是对单摆做解析对照：把模型简化成一个 hinge 加一个质点，初始角给一个小角度，仿真周期应接近2π√(l/g)，偏差大就回头查惯量和质心位置。这两个检查不花多少代码，但能把「能跑」和「算对」区分开。

从那以后我每次新建 MuJoCo 工程，都先把 rpath、错误缓冲区、索引映射这三件事在骨架里固定好，再动动力学逻辑，省下来的排查时间远比写这几行配置多。希望帮到你。

本文还有配套的精品资源，点击获取