简介：面向机器人学、运动控制与强化学习方向的C++开发者，这份打包资源解决了用CMake组织Mujoco工程并进行简单动力学计算的入门难题。压缩包内共217个文件，约26.29MB，以cmake配置脚本、make构建规则、C++源文件与头文件为主体，同时包含模型描述用的XML/URDF文件、txt说明文档、STL几何模型以及编译生成的动态库，构成一套完整的可编译参考工程；构建日志、缓存文件与可执行程序也被一并保留，便于对照整个编译流程排查问题。目前已有310人学习。借助该资源，可以理解在CMakeLists中如何查找Mujoco库、链接库并生成可执行程序，也能通过示例源码掌握mj_loadXML、mj_step等核心接口的调用方式；对刚接触Mujoco与CMake的开发者来说，这是一份结构清晰、可直接运行的入门资料，从构建到运行覆盖入门所需关键环节，能让学习者少走弯路。
1. 用CMake把MuJoCo动力学跑起来：先解决“配环境”这个拦路虎
做物理仿真的人多少都遇到过这种尴尬：引擎选型折腾半天，最后卡在编译环境上。MuJoCo确实是目前动力学计算里用得比较顺手的库，C++接口暴露得干净，可视化模块也能直接用原生窗口，但正因为它的SDK分发方式和传统库不太一样，很多人第一次用CMake集成时，光是找头文件和库文件就耗掉一晚上。这篇笔记就是把“用CMake构建一个最简单的MuJoCo动力学计算程序”这条路线完整拆开，从CMake怎么找到MuJoCo开始，到加载模型、步进仿真、读取状态，再到几个常见的坑。适合两种人：一种是C++刚入门、想在物理仿真里练手的学生，另一种是做机器人控制、需要把MuJoCo快速集成进现有CMake工程的一线开发者。读完你就能跑出一个会在重力下自由落体的小球，并且知道每个CMake变量和API调用在干什么。
2. CMake找MuJoCo的三种姿势：find_package、手动路径与目标链接
2.1 为什么MuJoCo的CMake集成比一般库“多一个步骤”
很多日常依赖库，比如OpenCV或者Eigen，装上之后系统路径里自然就有，find_package直接命中。但MuJoCo的官方SDK分发方式是压缩包解压后用，它不会主动往/usr/local里塞东西。如果你直接用find_package(mujoco)，大概率会得到一个“找不到包配置”的报错，然后你开始怀疑是不是装错了。
我一般建议把MuJoCo解压到某个固定目录，比如~/libs/mujoco-2.3.0，然后在CMakeLists.txt里明确告诉CMake去哪找。MuJoCo从2.0之后就在SDK里自带了CMake配置文件，路径是lib/cmake/mujoco/muJoCoConfig.cmake，这是它支持find_package的前提。你只要把mujoco_DIR指到那个目录，后面的用法就跟普通库一样了。
这里有个容易搞混的点：变量名是mujoco_DIR还是MUJOCO_DIR。不同版本的CMake模块生成规则不完全一样，有的文档写MUJOCO_DIR，但实际配置文件生成的是小写。如果你同时设置了两个，CMake会优先用更具体的那个。我的做法是只设小写的mujoco_DIR，避免干扰。
2.2 方法一：设置mujoco_DIR后用find_package
这是最标准和推荐的方式。假设你的MuJoCo安装在/home/yourname/libs/mujoco，那么最简的CMakeLists.txt长这样：
cmake_minimum_required(VERSION 3.16) project(mj_demo CXX) set(mujoco_DIR "/home/yourname/libs/mujoco/lib/cmake/mujoco") find_package(mujoco REQUIRED) add_executable(free_body main.cpp) target_link_libraries(free_body PRIVATE mujoco::mujoco)需要注意的是，这里链接的是mujoco::mujoco这个导入目标，它包含了头文件路径、库文件和必要的编译定义，不用你再手动去include_directories。CMake在导入目标里的编译定义会把MUJOCO_STATIC这种宏加进去，如果你绕过目标直接链接libmujoco.so，很容易遇到符号找不到的怪问题。
2.3 方法二：手动指定头文件与库路径
有些场景下你没法用find_package，比如MuJoCo的版本比较老，SDK里没有生成CMake配置文件，或者你从某个源里编译出来的是纯静态库。这时候退一步，手动把路径指全：
set(MUJOCO_ROOT "/opt/mujoco") find_path(MUJOCO_INCLUDE_DIR NAMES mujoco.h PATHS ${MUJOCO_ROOT}/include) find_library(MUJOCO_LIBRARY NAMES mujoco PATHS ${MUJOCO_ROOT}/lib) add_executable(free_body main.cpp) target_include_directories(free_body PRIVATE ${MUJOCO_INCLUDE_DIR}) target_link_libraries(free_body PRIVATE ${MUJOCO_LIBRARY})这种方式的缺陷是不会自动带上头文件里的版本宏。比如MuJoCo 2.3的头文件里有一些用宏控制的构建参数，你得自己处理。而且find_path如果搜到多个版本，可能会匹配到系统里另一个不相干的文件，所以PATHS一定要写精确。
2.4 方法三：直接拿到源码里当子工程
如果你对MuJoCo的源码做了定制，或者想带着源码一起编译，可以用add_subdirectory把其源码目录加进来。这种方式下CMake会生成mujoco这个库目标，链接方式就变成target_link_libraries(free_body PRIVATE mujoco)。注意这里的mujoco不带命名空间，因为它是当前项目生成的普通目标，不是导入目标。
用源码子工程的好处是你能改到内部编译选项，比如开启性能剖析或者断言，坏处是每次编译MuJoCo本体都要花不少时间，而且和官方预编译版本之间可能存在性能差异。我不建议普通用户直接用源码，除非你要二次开发求解器。
2.5 三种方式的选型建议
如果你只是跑简单动力学计算，直接下载官方SDK，用方法一就够了。如果你在公司内网、网络受限，只能拿到编译好的库文件，方法二最稳妥。如果你要做MuJoCo层面的修改，比如给碰撞检测加日志，方法三才有必要。选型标准是：能不动源码就别动，官方SDK的CMake配置已经写得很完整，它在Windows、Linux、macOS上生成的导入目标都是一致的，唯一需要你动手的就是把mujoco_DIR指对。
3. 第一步动力学计算：mjModel、mjData与仿真步进代码结构
3.1 mjModel和mjData各自负责什么
接触MuJoCo C++ API时，最先要分清两个核心结构体：mjModel和mjData。简单说，mjModel是“模型描述”，它保存几何、关节、执行器、惯性参数这些“不会随仿真发生变化”的信息；mjData是“状态空间”，保存位置、速度、加速度、力矩、接触等每个仿真步都会变化的数据。algebra.js里常见的那种混淆是把它们当成一个东西，结果在计算时反复拷贝模型数据，性能损失很大。
创建模型的标准函数是mj_loadXML。你需要传一个模型文件路径（比如scene.xml）和一个错误缓冲区。加载成功后，它会返回一个mjModel指针，再通过m_makeData分配mjData。释放时要用mj_deleteData和mj_deleteModel，不能直接delete，因为它们内部可能有额外分配的内存。
3.2 最小可跑的自由落体示例
我准备了一个最简单的场景：一个球体，没有关节，放在一个空旷的世界里，只受重力。MuJoCo允许场景里没有任何约束对象，但如果你完全不写body，它不会主动创建一个自由体。所以我用MJCF写一个单body球体，然后在C++里循环步进仿真，并打印球的位置。
MJCF文件free_body.xml内容如下：
<mujoco model="free_body"> <option gravity="0 0 -9.81"/> <worldbody> <body name="ball" pos="0 0 2"> <freejoint/> <geom type="sphere" size="0.2" mass="1" rgba="0.8 0.2 0.2 1"/> </body> </worldbody> </mujoco>这里给body添加了freejoint，表示它悬浮在空间中，不受关节约束。freejoint是MuJoCo里唯一能表示“自由刚体”的关节，不加的话body就被焊死在worldbody上了。mass写在geom上，MuJoCo默认会根据几何形状和密度推导质量，我显式指定了1kg，避免它自动计算后和预期不一致。
C++端代码：
#include <mujoco/mujoco.h> #include <iostream> int main() { char error[1024] = {0}; mjModel* model = mj_loadXML("free_body.xml", nullptr, error, 1024); if (!model) { std::cerr << "load model failed: " << error << std::endl; return 1; } mjData* data = mj_makeData(model); for (int i = 0; i < 200; ++i) { mj_step(model, data); double z =>int jnt_id = mj_name2id(model, mjOBJ_JOINT, "joint0"); int qpos_off = model->jnt_qposadr[jnt_id]; int qvel_off = model->jnt_dofadr[jnt_id]; double angle =>data->ctrl[0] = 1.0; // 设一个已知力矩 mj_forward(model, data); double acc =>for (int i = 0; i < model->nq; ++i) { >void print_force_decomposition(mjModel* model, mjData* data) { for (int i = 0; i < model->nv; ++i) { double constraint =><option integrator="RK4"/>或者在C++中：
model->opt.integrator = mjINT_RK4;注意这句要放在mj_makeData之前，因为有些仿真参数会被复制到data里，运行中修改model并不影响已创建的data。我遇到过在循环中间改integrator没反应的情况，原来是因为data里缓存了旧参数。正确顺序是改model，再重新m_makeData，或者直接改data->model->opt。
5. 避坑与常见问题排查：链接错误、数据未初始化与版本不匹配
5.1 现象：undefined reference tomj_loadXML
最典型的链接错误是这行。有些人在CMakeLists里写了target_link_libraries(free_body PRIVATE mujoco)，但依然报这个错。原因通常是用find_package找到的mujoco库文件是libmujoco.so，可你的编译器是gcc，它找不到这个so。
解决：先确认库路径是否正确。如果用了find_package，打开CMakeCache.txt查mujoco_DIR到底指向哪。如果改用了手动find_library，注意库文件名可能是libmujoco.so.2.3.0，而find_library默认匹配libmujoco.so，搜不到就成了空字符串，链接时直接没有-lmujoco。我一般把库目录直接写全路径，像这样：
set(MUJOCO_LIBRARY "/home/yourname/libs/mujoco/lib/libmujoco.so.2.3.0")这个路径是硬编码，不一定通用，但在自己机器上调试时最省心。
5.2 现象：运行时提示找不到libmujoco.so
编译过了，只要一运行就报“error while loading shared libraries: libmujoco.so”。原因很简单：可执行文件的动态链接器找不到运行库路径。你编译时用绝对路径链接，但运行时动态链接器只搜索标准路径，和你的自定义路径无关。
解决方法是设置LD_LIBRARY_PATH：
export LD_LIBRARY_PATH=/home/yourname/libs/mujoco/lib:$LD_LIBRARY_PATH或者在CMake里直接设置install rpath：
set(CMAKE_INSTALL_RPATH "${MUJOCO_ROOT}/lib")也可以用相对路径，但这和可执行文件在生产中的位置有关系。如果只在本机调试，LD_LIBRARY_PATH最简单。这个坑几乎每个MuJoCo初学者都会踩一次，因为官方文档的quickstart用的是命令行gcc，没有体现CMake工程里rpath的动态传递问题。
5.3 现象：mj_makeData返回空指针
创建数据失败，常见于模型加载成功但内存不足，或者模型里有不支持的执行器。更多的时候，问题出在你的MUJOCO版本和头文件不一致。比如你在某个头文件版本上编译，运行却链接到另一个版本的.so，二者内部结构大小不同，mj_makeData一开始就malloc失败。
解决：从CMakeCache里看mujoco_DIR，然后用ldd看可执行文件实际链接的库：
ldd ./free_body | grep mujoco如果输出里的路径和你期望的不一致，那就是CMake里路径优先级的问题。我处理这种问题时，会把find_package去掉，全部用绝对路径，等跑通了再换回find_package。
5.4 现象：模型加载失败，mj_loadXML返回null
错误信息在error缓冲区里。但很多人没注意error缓冲区长度，有的代码里写成：
char error[100]; mj_loadXML("x.xml", nullptr, error, 100);XML解析错误信息很容易超过100字节，此时缓冲区被截断，你看到的只有半句话。我一般是给足1024字节，并且初始化成0。还有一个常见低级错误：文件路径是从当前工作目录找的，如果你用CMake构建到build目录后直接运行build/free_body，当前目录就是build，找不到src里的xml。这不算MuJoCo的锅，但经常被误会长成“库有问题”。我把模型文件放在项目根目录，然后用绝对路径加载，或者用命令行参数传路径。
5.5 现象：仿真输出NaN
动力学计算出现NaN，是每个人都会经历的血泪经验。原因有很多，最常见的是模型里给了不合理的质量或惯量，导致质量矩阵奇异。另一个高发原因是你手动设置data->qvel时没考虑单位，四元数被填成非单位长度，解算器爆炸。
排查思路：先逐步减少场景复杂度，把碰撞关掉、执行器去掉，只留自由体，看还会不会NaN。如果不会，再一项项加回来。也可以打印每一步的data->qacc和data->qfrc_inverse，看哪个量先变成无穷大。我见过有人在control接口里给了超大比例增益，导致力矩上亿，直接让积分发散。MuJoCo对力矩没有上限，全靠你控制。
5.6 现象：编译警告“mujoco.h uses C++17 features”
编译时出现一堆C++17相关的警告，甚至错误。MuJoCo的高版本头文件用了少量现代C++特性，比如inline变量。你在CMake里没指定C++标准时，CMake会使用编译器默认标准，有些旧编译器默认C++11，导致不兼容。
解决：在CMakeLists里明确设置：
set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON)这个设置要在add_executable之前。如果项目里还有其他模块在C++11下编译，可以给MuJoCo相关目标单独加target_compile_features，不过简单项目直接全局设成17就行。
6. 进阶技巧：用CMake开关调试MuJoCo内部、断言与数据校验习惯
说到把MuJoCo用出高效的感觉，我习惯在CMake里维护一组编译开关。MuJoCo本身提供了调试宏，比如可以打开内存分配跟踪，但这些宏需要在你编译MuJoCo本体时才生效。如果你用官方预编译库，能用的主要是运行时选项：setting在mjData里设置mjENABLE_*标志。这些标志可以打开接触计算的可视化、几何穿透检测等，但核心调试还是得靠自定义断言。
我一般会在主循环里加一个状态校验函数：
void check_state(mjModel* model, mjData* data) { for (int i = 0; i < model->nv; ++i) { if (!std::isfinite(data->qvel[i])) { std::cerr << "non-finite qvel at dof " << i << std::endl; throw std::runtime_error("simulation diverged"); } } const double* pos =>target_compile_definitions(free_body PRIVATE MODEL_FILE="${CMAKE_SOURCE_DIR}/free_body.xml" )然后在C++里用：
#ifndef MODEL_FILE #define MODEL_FILE "free_body.xml" #endif mj_loadXML(MODEL_FILE, nullptr, error, sizeof(error));这样构建命令里就能指定不同模型。另一种更灵活的验证方法是写一个命令行参数解析，但我更喜欢编译期注入，因为这样在CMake工具链里重新跑一次就能切换配置。
说到后悔药，我最想提醒的是：在做任何动力学计算之前，先打印一遍model->nq、nv、nu和各个body的名称及其索引，确认模型和你脑中的自由度顺序一致。我翻车过最狠的一次，是连续调了三天前馈力矩，最后发现模型里有两个关节顺序反了，导致我一直在给错的自由度发控制。从那以后我每次加载到新模型，都强制走一遍“名称到索引映射表打印”，把这个当作习惯，再开始仿真计算。这个习惯省下过我不止一次排查时间，也推荐给你。希望帮到你。
本文还有配套的精品资源，点击获取
