人形机器人与人工智能

从零搭一个人形机器人开发环境：4 个阶段门把底座、ROS、仿真和记录先跑通

Written by

博华

in

很多人以为自己卡在人形机器人的 walking、抓取或者 teleop 上，实际上更早就已经卡住了，只是问题藏在开发环境里。

表面上你在装 Ubuntu、装 ROS 2、装仿真平台。真正决定项目能不能往前走的，是这些东西有没有连成一条稳定、可验证、可重复的 bring-up 链路。如果今天只是“勉强装上”，明天一重启就挂，换一台机器就得重来，录了一堆视频却回放不了实验，那后面做控制、做数据、接真机都会越来越贵。

所以这篇不是安装清单 dump，也不是泛工具综述。我只想帮你先搭出一条最小可用开发闭环，让你能判断自己的环境到底是已经能做项目，还是只是看起来装好了。

这篇适合谁，不适合谁

适合这两类读者：一是已经决定认真做 humanoid prototype，而不是只跑演示的人；二是有基本 Linux 经验，但还没有一套稳定机器人开发环境的人。

如果你想在一篇文章里把 simulation、training、control、hardware 全部装齐，这篇不适合你。这里先做地基，不做全栈百科。

什么叫开发环境真的可用

在人形机器人项目里，开发环境可用，不等于桌面上多了几个图标，也不等于某条安装命令没报错。更实际的判断标准只有四件事：你能把底层版本边界定住；你能拉起并维护一套 ROS 2 workspace；你能稳定进入一个可重复验证的仿真入口；你能把每次实验记录下来并重新回放。

只要这四件事还没成立，就别急着往上叠更重的东西，比如复杂 teleop 框架、训练栈、真机驱动或者一大堆模型环境。顺序反了，后面通常会变成环境问题伪装成算法问题。

先看整条 staged bring-up ladder

这篇的主线只有 4 个阶段门。先过底座门，把 Ubuntu、GPU、磁盘和版本边界固定住，确保机器重启后还是同一台可用机器。再过ROS 门，把 workspace、rosdep、colcon 和 source 顺序纪律立起来，确认最小 demo 能在新终端重复跑通。然后过仿真门，先把仿真当成可重复验证层，而不是炫技层，重点看 bridge、启动脚本和重复拉起是否稳定。最后过记录门，把 config、run dir、bag/MCAP、日志和人工结论串成闭环。4 门都过了，你才适合决定后面把时间压到 walking、manipulation 还是 teleop。

第 1 门，底座门：先把 Ubuntu、GPU、磁盘和版本边界定住

人形机器人开发环境最怕的不是一开始装得慢，而是底座边界没固定。系统版本、驱动版本、磁盘规划这三件事不稳，后面很多“高级问题”都会退化成底层环境问题。

对大多数人来说，先固定一套 Ubuntu LTS 是最稳的起点。如果你后面要接 GPU 仿真、视觉模型或者 Isaac 系工具链，就尽早把 NVIDIA 驱动状态理干净，不要一边做项目一边频繁换系统、换驱动、换桌面环境。你需要的是可维护底座，不是追最新。

磁盘也别临时糊弄。系统盘、项目代码、仿真资产、bag 数据、模型权重，最好从第一天就分层。很多项目不是死在算法，而是死在系统盘爆满、缓存混进代码目录、bag 无处可放，最后谁也不敢删。

底座门最小验收

底座门只看 3 件事，过了再往上走：

  • 重启后 nvidia-smi 稳定返回，显卡状态不是一次性侥幸正常
  • 当前 Ubuntu 版本、内核版本、驱动版本已经写进 docs/bringup-checklist.md
  • df -h 能看清系统盘和数据盘边界，项目目录不再和缓存、下载目录混成一团

如果这 3 条还不能稳定满足，就先别碰更上层的 ROS 和仿真。

第 2 门，ROS 门：不是“装 ROS 2”，而是建立可长期维护的 workspace

很多人安装 ROS 2 时最大的误区，是把“命令跑完”当成目标。对 humanoid 项目来说，更重要的是这套 workspace 以后能不能继续加依赖、加驱动、加仿真、加日志，而不迅速变脏。

所以这一步的重点不是多装几个包，而是把 workspace 纪律立起来。rosdep 负责依赖补齐，colcon 负责构建，workspace 要明确 underlay 和 overlay 的边界，新终端里先 source underlay，再 source overlay，不要在同一终端里混着 build、source 和多套发行版。很多所谓 ROS 玄学，本质上都是 source 顺序脏了。

目录上也尽量分层。src/ 放你真正维护的代码，third_party/ 放外部仓库，launch/ 和 config/ 单独管理运行入口与参数。这样后面无论接 bridge、仿真还是真机，都比较容易判断问题到底出在哪一层。

ROS 门最小验收

ROS 门统一按下面 4 条验收：

  • ros2 最小 demo 跑通，比如 talker/listener
  • workspace 可以正常 colcon build
  • rosdep install 能把依赖树解析并补齐
  • 新开一个终端，按固定 source 流程再重复验证一次

如果这一步没过，不要继续往仿真层加复杂仓库。那只会把基础问题放大。

第 3 门，仿真门：把仿真当成可重复验证层，不是选型综述

仿真在这里的作用，不是让你看一个更酷的 3D 画面，而是给你一个能重复启动、重复观察、重复排错的验证层。

如果你现在的目标是先把模型、接触、控制链和日志链跑顺，MuJoCo 这类轻量仿真更适合当第一入口。它的价值不是大而全，而是摩擦小，适合先确认基本模型和控制思路是不是通的。

如果你后面要接视觉、GPU、ROS bridge、复杂场景或者更重的学习栈，Isaac Sim / Isaac Lab 更有意义。但这里先只把它们当成重验证层和后续路线，不展开安装教学，也不展开训练教学。当前更重要的问题只有一个，你的仿真入口能不能被稳定、重复地拉起来。

仿真门最小验收

仿真门也统一成固定格式：

  • 能稳定拉起一个 humanoid 或近似机器人样例
  • 有固定启动命令或脚本，不靠 GUI 乱点
  • 如果用了 ROS bridge，topic / 状态流真的可见
  • 同一流程至少能重复启动 3 次，不是今天行、明天不行

这里的重点不是你选了哪个平台，而是你有没有建立起可重复验证层。

第 4 门，记录门：把实验从“记得跑过”变成“能回放、能复盘”

这是最容易被忽视，但对真实项目最关键的一门。

如果你从一开始就没有日志、回放和配置归档，后面所有排错都会慢慢退化成口头回忆。你会记得“昨天好像跑通过一次”，但说不清当时用了哪份参数、哪个 launch、哪套版本、出了什么异常。对 humanoid 项目来说，这种模糊几乎一定会拖慢整个节奏。

所以这一步要尽早建立最小记录链。一个够用的链路可以很朴素，但必须完整：

config -> run dir -> bag/MCAP -> log -> conclusion

在 ROS 2 里，MCAP 已经是很值得优先采用的记录后端之一。重点不在于你追最新格式，而在于你能稳定录、稳定放、稳定找到对应配置。

记录门最小验收

记录门只看这 4 件事：

  • 每次实验都有统一 run_id 或时间戳命名
  • 至少留下配置副本、日志、bag 或 MCAP
  • 可以完成一次最小录制和回放
  • 几天后的自己能根据 run 目录重新理解当时发生了什么

如果你现在只能录屏，不能留下结构化记录，这一门就还没过。

Run record template

把“记起来”变成真实动作，最简单的方法不是多讲道理，而是固定一个 run record 模板。每次实验结束时，哪怕只花 2 分钟，也把本次输入、输出和人工结论落下来。这样环境问题、bridge 问题、配置漂移问题，后面都更容易对齐。


runs/2026-04-16_1430_sim-smoke-test/
  config/
    robot.yaml
    sim.yaml
  launch/
    bringup.launch.py
  bags/
    session.mcap
  logs/
    console.log
    rosout.log
  NOTES.md


# Run Record
- run_id: 2026-04-16_1430_sim-smoke-test
- goal: 验证 ROS bridge 与关节状态链路
- env: Ubuntu 24.04 / ROS 2 Jazzy / driver 550.xx
- command: ros2 launch ...
- record: ros2 bag record -s mcap --all
- result: 仿真启动成功，joint_states 可见
- issue: bridge 首次启动延迟偏高
- next_step: 复测一次冷启动，并检查 source 顺序

让目录结构服务 bring-up，而不是只服务“看起来整齐”

目录结构不需要复杂，但必须支撑 bring-up 逻辑。最小可复制模板可以像这样：


robot_ws/
  src/
  third_party/
  launch/
  config/
  bags/
  logs/
  assets/
  docs/
    bringup-checklist.md

这套结构的意义不在名字本身，而在边界清楚：src/ 和 third_party/ 分开，方便判断问题是你自己的代码还是外部依赖；launch/ 和 config/ 分开，方便把启动入口和参数版本绑定到同一个 run；bags/、logs/、assets/ 分开，避免实验记录、仿真资产和代码互相污染；docs/bringup-checklist.md 则负责把阶段门验收固定下来，而不是每次靠脑子记。

Bring-up checklist 模板

你可以把下面这个模板直接放进 docs/bringup-checklist.md。它不求大而全，只求每一门都能被明确勾掉。只要有一项说不清，就别急着继续往上加层。


# Bring-up Checklist

## 底座门
- [ ] 重启后 `nvidia-smi` 正常
- [ ] Ubuntu / kernel / driver 版本已记录
- [ ] `df -h` 边界清楚，系统盘与数据盘分开

## ROS 门
- [ ] talker / listener 跑通
- [ ] `rosdep install` 正常
- [ ] `colcon build` 正常
- [ ] 新终端按固定 source 顺序复验通过

## 仿真门
- [ ] 最小样例可启动
- [ ] 启动命令已固定
- [ ] bridge / topic / state 可见
- [ ] 连续 3 次重复启动通过

## 记录门
- [ ] run_id 规则已固定
- [ ] bag/MCAP 可录可放
- [ ] config / logs / conclusion 已归档

## 分流出口
- [ ] 下一步走 walking / manipulation / teleop 之一

统一阶段门，别再用零散“装好了”自我安慰

到这里，整篇文章其实只剩一个判断动作。不要再问“我是不是大概装好了”，而是问自己 4 个阶段门有没有逐一过掉：

  1. 底座门：系统、驱动、磁盘和版本边界是否固定
  2. ROS 门：workspace、rosdep、colcon、source 顺序是否稳定
  3. 仿真门：最小仿真入口和 bridge 是否可重复验证
  4. 记录门：配置、bag/MCAP、日志、人工结论是否形成闭环

只要前一门没过，就不要把后一门当成“顺手一起做”。很多后续困难，其实只是阶段顺序错了。

排错顺序与风险边界

如果环境挂了，别第一反应就是重装。更有效的顺序通常是，先看边界，问题到底发生在系统驱动、Python 环境、ROS workspace，还是仿真依赖；再看复现性，它是每次都出现，还是只出现在某个终端、某个目录；然后看日志和状态，确认 topic、bridge、bag 回放和磁盘空间；最后才考虑重装。真只有 2 小时时，也别贪多，优先压实 4 件事，固定底座边界，跑通 ROS 最小 demo，拉起一个最小仿真入口，完成一次结构化记录和回放。这样得到的是可继续工作的环境，不是一堆安装痕迹。

4 门都过了之后，再往哪条路分流

这时开发环境才算从“能装”走到“能做事”。接下来可以按目标分流，但这里只保留出口，不展开成子教程。

  • walking：接触切换、状态估计、whole-body control、短链路验收
  • manipulation：末端执行器、视觉抓取、标定、数据验收
  • teleop：遥操作链路、数据结构、回放、人工 supervisor

先把出口看清，再决定资源压哪里，不要在地基还没稳时同时摊开三条线。

边界收口：这篇只做地基，不做全栈百科

如果你读到这里，最重要的收获不应该是“又多记了几个工具名”，而是知道一套 humanoid 开发环境该按什么顺序搭、按什么标准验、按什么方式记。底座门、ROS 门、仿真门、记录门过了，后面的 simulation、control、training、hardware 才有地方落。没过，就先别扩。

真正拖慢人形机器人项目的，往往不是你还没学会更高级的方法，而是开发环境根本没有形成一条稳定、可验证、可复用的工程链。先把这条链搭起来，后面的每一步都会便宜很多。

延伸阅读与参考来源

站内延伸阅读

Share this article

Send it to someone following humanoid robotics, embodied AI, or deployment trends.

More posts