第 07 课 · 排错方法论:卡住了怎么办
这一课解决什么问题:报错不可避免,但慌乱可以避免。这一课给你一套固定的五步排错流程,并用本项目三个真实踩坑案例走一遍。学完它,任何报错都变成"有流程可走的事"。
前置:第 03 课 起的任意一课。你最近被哪个报错卡过,带着它来最好。
1. 通用五步流程
- **把报错从头读到尾。**新手最大的毛病是只看最后一行就开猜。先读第一行(在跑什么)和最后一行(死于什么)。
- **最小复现。**把命令删到最简,只留能触发报错的部分——复现越短,排除的干扰越多。
- **一次只改一件事。**改前记下当前状态,改完立刻验证——同时改三处,好了不知道是谁的功劳,坏了查不回来。
- **按层查文档,不越层乱改。**OpenMicroDuck 排错文档给了一条"先查哪层"的顺序:当前目录和 commit → uv/依赖环境 → 任务注册表 → MJCF 能否加载 → ONNX 路径与 61 → 14 接口 → 模型变体/关节顺序/归一化 → 最后才轮到训练或控制效果。原话提醒:前几步没通过,就不要改 Reward、BAM、摩擦、质量。
- **记录进踩坑日志。**按"现象 → 原因 → 解决"三段写,没解决就老实写"未解决"。下一个踩同一坑的人是你自己。
提问或提 issue 前,先保存四项信息:git rev-parse HEAD、uv --version、uv run list-envs、uv run scripts/infer_policy.py --help。训练阶段的报错,再补完整命令和完整错误文本。
2. 案例一:无 GPU 的 Mac 一训练就崩
现象:uv run train 直接崩,IndexError: list index out of range,崩在 mjlab 的 gpu.py select_gpus。
走流程:①读完报错——死在"选 GPU"的函数里,不是模型、不是数据;②最小复现——任何 train 命令都崩,与参数无关;③查根因——训练器默认 gpu_ids=[0],无 CUDA 的机器上 GPU 列表为空,按索引取值越界;④查到 mjlab 官方约定:CUDA_VISIBLE_DEVICES=""(设为空)就是显式 CPU 模式(gpu.py 文档字符串写明);⑤解决并记入构建日志。
反面教材:若跳过第①步,把它猜成"数据问题"去乱改奖励参数——完全跑偏,而且修不好。
3. 案例二:wandb 没 API key 直接报错
现象:同一天第二个坑:默认日志器是 wandb(联网上传实验数据的服务),机器上没配 API key,直接报错。
走流程:读报错定位到日志上传环节 → 最小复现确认与训练无关 → 换本地日志器 --agent.logger tensorboard(与官方冒烟参数一致)→ 记录。
这一课的道理:两个坑叠加时,"一次只改一件事"才救得了你——若当时同时加上 CPU 环境变量和 tensorboard 参数,好了也不知道哪副药治哪个坑,下次少带一副就翻车。
4. 案例三:相对路径找错文件
现象:exp001b 扰动测试,评估脚本里写了 ../rl-series/... 相对路径,换个目录运行就找错了位置——构建日志原话:"本会话第二次栽在相对路径上"。
走流程:现象是"文件不存在",但文件明明在,而且时好时坏——取决于从哪个目录运行命令 → 根因:相对路径随工作目录流动 → 解决并固化成规矩:脚本内一律基于 __file__(脚本自身位置)定位仓库相对路径。
这一课的道理:时好时坏的 bug,几乎都是"某个隐含前提在变"——工作目录、环境变量、默认参数。钉死成显式配置,bug 就消失。
5. 建你自己的"踩坑笔记"
构建日志"踩过的坑"一节开头写着:**这一节是整份日志最有价值的部分——别人可以不重复踩。**现在轮到你建自己的了:一个 踩坑笔记.md,每条按"现象 → 原因 → 解决"写。开张第一页可以抄 docs/新手学习文档.md 第 9 节的"必踩的坑"(12 条),本课三个案例作第 2–4 条。每次凭流程修好一个报错就多一条——三十天后它是最值钱的文件。
动手练习(15 分钟)
把第 03 课以来最烦你的一个报错,按"现象 → 原因 → 解决"写进新开的踩坑笔记。没遇到过的,复述案例一,重点写"跳过第①步,我会往哪个错误方向猜"。
自查清单
- [ ] 我能默写五步流程,并说出每一步防的是什么错
- [ ] 我能说出提问前要保存的四项信息
- [ ] 我能复述至少两个真实踩坑案例的"现象 → 原因 → 解决"
- [ ] 我已建了自己的踩坑笔记,里面至少有一条
全部打勾,进入第 08 课:看懂电路图。
下一课预告
阶段 B 完结,下一阶段进入硬件:第 08 课开始碰真实世界,先学把 imu_to_dxl 原理图读成一句人话。
延伸资源
- OpenMicroDuck 新手排错(按症状查层的对照表):
open-microduck/docs/zh-CN/getting-started/troubleshooting.md - 构建日志"踩过的坑"章节(三个案例的原始记录):
microduck-replica/构建日志.md - 新手学习文档第 9 节"必踩的坑":
docs/新手学习文档.md