跑具身智能相关项目的人，大概率都经历过这样的夜晚：论文里Habitat的demo视频看起来特别丝滑，轮到自己动手，装依赖就装了三天，好不容易import habitat成功，跑example.py又迎面撞上一堆GL error。这篇博文就是想把这一步彻底趟平。我会从 Habitat Simulator 和 Habitat-Lab 这两层核心组件的关系讲起，一路带你跑到 example.py 在屏幕上输出第一帧深度图，把版本、驱动、数据集、渲染后端这些容易炸的点一次性理清楚。不管你是刚入门的本科生，还是被项目进度逼着的工程师，只要机器有 NVIDIA 显卡、能装 Linux，这条路径基本都能复现。
1. 先搞清楚你装的到底是哪个 Habitat
很多教程把 Habitat 当成一个东西在装，装完跑不起来就开始怪环境。实际上你至少会碰到两个紧密相关但完全不同的项目：Habitat-Sim 和 Habitat-Lab。前者是底层模拟器，后者是上层算法框架，example.py 这类示例脚本通常跑在 Habitat-Lab 这一层。不把这条主线理清，后面每一步都可能踩坑。
1.1 Habitat-Sim 和 Habitat-Lab 各自负责什么
Habitat-Sim 是一个 3D 仿真平台，底层用 C++ 和 Unity 引擎的物理、渲染模块实现，专门为具身智能研究设计。它负责加载三维场景、控制虚拟机器人、生成 RGB 图像、深度图、语义分割图，以及做碰撞检测和物理模拟。你可以把它理解成一台“虚拟摄影棚”，真实感强、渲染速度快，单机跑交互任务能达到很高的帧率。
Habitat-Lab 则是在 Habitat-Sim 之上封装的 Python 库，提供了统一的配置系统、环境接口（habitat.Env）、任务定义和 benchmark。日常写算法、跑强化学习、做 pointnav 或者 objectnav，基本都是在 Habitat-Lab 里写代码。example.py 会同时用到这两者：Habitat-Lab 解析配置文件并构建环境，Habitat-Sim 在底层完成实际的场景加载和渲染。
所以装的时候不能只装其中一个。只装 Habitat-Sim，你只能自己写 C++ 或底层 Python 调用；只装 Habitat-Lab，它 imports 时会直接报No module named 'habitat_sim'。这套关系就像发动机和整车的关系——Habitat-Sim 是发动机，Habitat-Lab 是带方向盘和仪表盘的整车，example.py 就是一次试驾。
1.2 example.py 到底在验证什么
如果你打开官方仓库或者翻到一些教学项目，会看到类似example.py的文件。它的目标很简单：加载一个场景，创建一个智能体，执行一系列动作，把传感器的观察结果打印出来。可能是 RGB 图像、深度图像，也可能是碰撞状态和智能体位姿。
跑通这个脚本，不等于你学会了具身智能，但至少说明四件事：Habitat-Sim 能正常加载物理场景，Habitat-Lab 能正确解析配置，传感器流能成功输出，底层渲染后端不会崩。这四件事任何一件出问题，后面的训练代码都跑不动。所以我习惯把它当成环境自检工具——每次新建虚拟环境、换服务器、换数据集，第一件事就是跑一遍 example.py。
2. 动手安装前的三个硬性检查项
在敲第一条安装命令之前，先把下面三项确认清楚。我见过太多人跳过这一步，装到一半才发现系统版本不匹配或者显卡驱动太老，最后全部推倒重来。
2.1 操作系统与显卡驱动是地基
Habitat-Sim 官方主要支持 Linux 和 macOS，Windows 虽然能折腾，但渲染后端和物理库的坑会多出好几倍。如果你只是在本地笔记本上学习，建议装一个 Ubuntu 20.04 或 22.04 的双系统，或者直接用一台带 NVIDIA 显卡的 Linux 机器。我在实际项目中用的就是 Ubuntu 22.04，驱动版本 535，CUDA 用 11.7 或 11.8 都能跑通。
检查驱动的命令很简单：
nvidia-smi如果这条命令能显示显卡型号和驱动版本，第一步就过了。如果提示command not found，要么驱动没装，要么你没在有 GPU 的机器上。没有 NVIDIA 显卡也能跑 Habitat-Sim，但只能用 CPU 渲染，速度会非常慢，跑 example.py 这类小脚本还行，做训练基本不现实。
2.2 用 Miniconda 隔离环境，别用系统 Python
我强烈建议用 Miniconda 而不是系统自带的 Python，原因有三个：第一，Habitat-Sim 的老版本经常对 Python 版本有硬性要求，系统 Python 版本一旦升级就很难回退；第二，Habitat-Lab 依赖的包很多，直接装进系统环境很容易跟其他项目冲突；第三，Conda 创建的虚拟环境可以随时删掉重建，装坏了不心疼。
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh装完记得重开终端让 conda 生效，然后创建一个独立的 Python 3.9 环境。我建议固定用 Python 3.9，不要图新鲜上 3.11 或 3.12，很多依赖包对高版本 Python 的支持还没跟上，跑起来容易碰到莫名其妙的问题。
3. Habitat-Sim 安装：能选预编译包，就别先折腾源码
Habitat-Sim 有两种安装方式：直接用 Conda 或 pip 装预编译包，或者从源码编译。对于 90% 的场景，预编译包完全够用，而且能省掉 CMake、编译器、OpenGL 头文件这一大堆麻烦。源码编译的最大优势是能自定义显卡架构、打开或关闭特定功能，但你不是为了给 Habitat-Sim 提 PR 的话，真没必要第一步就硬啃源码。
3.1 用预编译包快速安装的完整命令
我的建议是先建环境，再装 Habitat-Sim，最后装 Habitat-Lab，顺序不要乱。
conda create -n habitat python=3.9 cmake=3.14.0 conda activate habitat conda install habitat-sim withbullet -c conda-forge -c aihabitat这里有个关键点，withbullet表示启用 Bullet 物理引擎，也就是让虚拟机器人能够模拟碰撞、抓取和受力。如果你只是跑 pointnav 这类导航任务，不启用 Bullet 也能跑，但后续一旦接触机器人操作任务，没有它就寸步难行。一次性装好withbullet版本，后面就省得重装。
装完先做一个最简单的 import 测试：
python -c "import habitat_sim; print(habitat_sim.__file__)"如果这行命令能输出 habitat_sim 的路径，说明核心模拟器已经装好。如果提示缺少libGL.so.1，说明系统缺少 OpenGL 运行时库，执行下面的命令补上：
sudo apt update sudo apt install libgl1 libglib2.0-0 libgl1-mesa-glx有些机器还会提示缺少libxrender、libxkbcommon之类的库，用apt补装即可。这个步骤看似琐碎，但踩过的人都知道，libGL.so.1报错长期占据 Habitat 安装问题榜首。
3.2 源码编译是什么时候才需要做的事
如果你用的显卡特别新，预编译包里的 CUDA 算子不兼容，或者你想改 Habitat-Sim 的原始代码，再考虑源码编译。大致流程是：
git clone https://github.com/facebookresearch/habitat-sim.git cd habitat-sim pip install -r requirements.txt conda install -y -c conda-forge ninja python setup.py build_egg # 构建底层源码编译的时间通常在半小时到一小时之间，具体看机器性能。编译前还要确保系统装了 build-essential、CMake、OpenGL 开发库，路径配置错一个就编译失败。我的建议是：先用预编译包把 example.py 跑通，建立对整个系统的体感之后再有针对性地学编译细节。
4. 装好 Habitat-Lab 才算有完整的环境交互层
Habitat-Sim 装好只是第一步，example.py 依赖 Habitat-Lab 提供的高层接口，所以还要把仓库克隆下来并安装。
4.1 Clone 官方仓库并执行 editable 安装
git clone https://github.com/facebookresearch/habitat-lab.git cd habitat-lab pip install -e .这里我解释一下-e（editable）这个参数。它表示以“可编辑模式”安装，也就是说 Python 不会把 Habitat-Lab 拷贝到 site-packages，而是直接引用你当前目录下的源码。这样改代码不需要重新安装，方便调试，也方便随时切换到不同分支。注意，这条命令会读取setup.py，如果缺少某些编译依赖，pip 会自动去 PyPI 下载。
安装完成后，可以顺手验证一下版本：
python -c "import habitat; print(habitat.__version__)"4.2 准备测试数据集：先下 Replica，别一上来就搞 MP3D
example.py 要运行，必须有一个场景文件可供加载。Habitat 官方支持多种三维数据集，常见的有 Gibson、Matterport3D（MP3D）和 Replica。其中 Replica 的体积相对小，场景语义清晰，单张显卡跑起来压力小，最适合做第一次环境验证。
数据集目录结构一般是这样的：
habitat-lab/ └── data/ └── scene_datasets/ └── replica/ ├── apartment_0/ │ ├── apartment_0.glb │ └── ... └── apartment_1/你需要手动创建data/scene_datasets目录，再把下载好的 Replica 数据集放进去。配置文件中scene_id通常写的是相对路径，比如data/scene_datasets/replica/apartment_0/apartment_0.glb，所以目录结构必须严格对齐，少一层或多一层都会报“找不到场景”的错误。
如果下载速度不理想，建议使用官方提供的下载脚本或者先下载体积最小的 apartment 子集，跑通后再补充完整数据。这个策略能帮你快速排除“数据集没下全”的干扰。
5. example.py 逐行拆解：从加载配置到拿到第一帧观察
环境装好了，数据集也在正确的位置，现在终于到了核心环节——把 example.py 彻底跑通。我以下面这段代码为例，它和官方示例的逻辑基本一致，只是我按自己的习惯整理成了一个独立文件。
5.1 核心代码全览与手动编排
import habitat import numpy as np import cv2 def main(): # 1. 加载配置文件 config = habitat.get_config("configs/tasks/pointnav.yaml") # 2. 基于配置创建环境 env = habitat.Env(config) # 3. 重置环境，获得第一帧观察 obs = env.reset() print("Observation keys:", list(obs.keys())) # 4. 打印关键传感器的 shape if "rgb" in obs: print("RGB shape:", obs["rgb"].shape) if "depth" in obs: print("Depth shape:", obs["depth"].shape) # 5. 执行 50 步随机动作 for step in range(50): action = env.action_space.sample() obs = env.step(action) if step % 10 == 0: print(f"Step {step}: reward = {env.get_metrics()}") # 如果当前观察里有深度图，就保存当前帧 if "depth" in obs: depth_img = (obs["depth"] * 255).astype(np.uint8) cv2.imwrite(f"depth_frame_{step:03d}.png", depth_img) # 6. 关闭环境 env.close() if __name__ == "__main__": main()如果你是在habitat-lab仓库根目录下运行，直接把它保存成example.py，然后执行：
python example.py正常情况下你会看到类似这样的输出：
Observation keys: ['rgb', 'depth', 'semantic', 'proprioception', 'collision'] RGB shape: (720, 1280, 3) Depth shape: (720, 1280, 1)这说明环境已经成功加载，传感器也开始工作了。
5.2 配置文件的路径和内容怎么确认
configs/tasks/pointnav.yaml是 Habitat-Lab 官方提供的一个示例配置，它定义了任务类型、传感器组、动作空间和场景路径。不同版本可能把配置文件放在不同目录，如果你打开仓库找不到这个路径，可以在configs目录里搜一遍：
find . -name "*.yaml" | grep pointnav如果只看到pointnav_gibson.yaml或pointnav_mp3d.yaml，那说明官方已经把任务基准按数据集拆开了，选一个把场景路径改到你下载的数据集即可。这是我踩过的坑之一，照抄老教程里的配置文件路径，结果在新版本里根本不存在。
5.3 无显示器环境下怎么跑：headless 和离屏渲染
很多同学是把 Habitat 装在云服务器或者 Docker 容器里的，根本没有物理显示器。这种情况下直接跑 example.py，大概率会报Could not create GL context。解决办法是使用 headless 模式，让 Habitat-Sim 走 EGL 或 OSMesa 这类离屏渲染后端。
在启动脚本之前设置环境变量：
export HABITAT_SIM_HEADLESS=1或者在 Python 代码里手动指定渲染设备：
from habitat_sim.utils import settings settings.sim_settings["enable_gfx"] = True如果你用的是支持 EGL 的 Docker 镜像，通常不需要额外安装 X11 服务；但如果是纯 CPU 环境，需要确保系统有 Mesa 软件渲染库：
sudo apt install libegl1 libgl1-mesa-dri这一步最容易让人崩溃的地方在于：headless 模式下程序完全不弹窗，也没有可视化画面，你以为它卡死了，实际上它正在后台正常计算。所以要学会通过日志和输出判断状态，而不是等一个永远不会出现的窗口。
6. 常见问题速查与排错实录
把 example.py 从“能写出来”到“稳定跑通”，中间隔着一堆奇奇怪怪的错误。这里我把过去半年在群里和 внутренних验证中看到的高频问题整理成一个速查表，并按自己的经验补充排查思路。
6.1 高频错误对照表
| 错误现象 | 可能原因 | 解决办法 |
|---|---|---|
No module named 'habitat_sim' | 没有安装 Habitat-Sim，或者当前 conda 环境不对 | 激活正确的环境，重新执行conda install habitat-sim withbullet -c conda-forge -c aihabitat |
ImportError: libGL.so.1 | 系统缺少 OpenGL 运行时库 | sudo apt install libgl1 libgl1-mesa-glx |
Failed to load scene/Invalid scene | 数据集路径和配置文件里的scene_id不一致 | 检查data/scene_datasets目录层级，确认 glb 文件存在 |
CUDA error: out of memory | 显存不足，或者多进程同时占用 GPU | 调低分辨率，或者设置gpu_device_id: -1用 CPU 跑测试 |
Could not create GL context | 无显示器环境没有启用离屏渲染 | 设置HABITAT_SIM_HEADLESS=1 |
Bullet not enabled | 安装时没有带withbullet选项 | 重装withbullet版本的 habitat-sim |
| 运行过程中 crash 但无明显报错 | 显卡驱动版本和 PyTorch/CMake 不匹配 | 用nvidia-smi确认驱动，升级到 470+ 版本 |
6.2 几条实操心得，属于文档里不会写的内容
第一，版本不要盲目追新。Habitat-Sim 的更新节奏挺快，但新版本往往伴随新的依赖要求，老模型代码不一定兼容。如果只是学习或复现经典论文，建议直接固定一个稳定版本组合。比如我的机器上长期用的是 habitat-sim 0.2.2 配合 habitat-lab v0.2.2，跑官方 benchmark 从未出过兼容性问题。
第二，先跑小场景再做大事。一上来就下载几十个 GB 的完整数据集，不仅下载慢，加载也慢，出错了还不好判断是代码问题还是数据问题。先下一个小 apartment 场景，确认 example.py 能跑通，再把数据补齐。我踩过最冤的一次坑就是数据集不完整，配置里的 glb 文件缺失，结果报错一直指向渲染层，排查了整整一下午，最后发现只是数据没放对位置。
第三，要多看官方 issues，但也要注意时效性。GitHub 上关于 Habitat 的讨论非常多，很多报错两年前的 issue 里就有答案。但官方版本变更后，旧答案可能失效。我的做法是：先搜索 issue，再看时间，优先采纳最近半年内的方案，跨版本的经验要谨慎参考。
7. 一些补充建议，给第一次接触这套生态的朋友
example.py 跑通之后，你其实已经拿到了一张进入具身智能研究的地图。先别急着写算法，我还想多说几句。
7.1 学会阅读 yaml 配置，比多写一百行代码更有用
Habitat 的设计哲学就是把环境、任务、传感器、动作空间全部通过配置文件参数化。你以后做实验，经常要改的是 yaml 而不是 Python 代码。举个例子，你想让机器人加上语义传感器，只需要在配置文件里加一行semantic_sensor: {type: HabitatSimSemanticSensor}，而不需要改任何 C++ 代码。所以花半小时把configs/tasks/pointnav.yaml从头到尾看一遍，搞清楚每个字段的含义，比多跑十个示例脚本收益更大。
7.2 善用官方自带的测试场景
Habitat-Sim 会附带一些简单测试场景，路径通常类似habitat-sim/data/scene_datasets/habitat-test-scenes/apartment_1.glb。如果你暂时不知道怎么下载 Replica，可以先用这个测试场景把 example.py 的逻辑调通。修改配置的时候，把配置文件里的scene_id指向这个 glb 文件即可。等你真正理解了配置结构，再切换成正式数据。
7.3 把 example.py 变成一个可复用的自检脚本
我自己的习惯是保留一份最小化的 example.py，内容不复杂，但每次在新机器上部署环境时都会跑一遍。这个脚本不依赖大场景，不依赖外部数据集，只验证核心链路。一旦换机器、换服务器、换容器，就能在五分钟内确认环境是否可用。你可以基于上面的代码，把场景路径改成官方测试场景，把输出改成只打印关键信息，保留这个自检习惯，后面的项目推进会顺利非常多。
说到底，Habitat 的安装和跑通真不是什么高深技术，它考验的全是细节：目录结构对不对、CUDA 版本配不配、OpenGL 库缺没缺、配置文件路径指向哪里。把这些细节一个个理顺，example.py 自然就跑起来了。我个人的经验是，这类环境问题解决得越多，你对整套系统的控制感就越强，以后再碰到论文复现中的诡异报错，也会比一般人更快定位到根因。希望这篇把流水账写成避坑指南的记录能帮你在第一步就少走几段弯路。
