4.3 资源管理与生态

4.3 资源管理与生态

本节摘要：模型库是 Gazebo 资源生态的组织单元（model.config + model.sdf + meshes 目录三件套），model:// URI 靠环境变量驱动的路径栈解析。团队协作里"启动失败八成是路径问题"的根源就在解析顺序。本节给出模型三件套规范、路径解析表与一套可复现的团队配置。

一个模型文件夹的三件套

model:// 协议指向的不是单个文件，而是一个目录：

my_robot/
  model.config      # 元数据: 名称/版本/作者/sdf 文件名
  model.sdf         # 模型本体(或 model.config 里指向的文件)
  meshes/           # 视觉网格(可选)
  materials/        # 贴图与脚本(可选)
  thumbnails/       # 模型库 GUI 缩略图(可选)
​

model.config 是名片：

<?xml version="1.0"?>
<model>
  <name>My Robot</name>
  <version>1.0</version>
  <sdf version="1.9">model.sdf</sdf>
  <author><name>your team</name></author>
  <description>差速底盘 + 16线雷达的实验平台</description>
</model>
​

生态主体是官方燃料库（Fuel）：云端的模型仓库，gz sim 里可直接按 URI 引用 Fuel 格式的 URI 引用其模型，运行时自动下载缓存。工程上把 Fuel 当"公共素材库"，把自建模型库当"团队资产"，两条线并行。

路径解析：启动失败的第一嫌疑

SDF 里写 <uri>model://my_robot</uri> 时，解析器按顺序翻路径栈，先命中先用：

⚠️ 常见坑：~/.bashrc 里 export 了路径但用了相对路径，或 IDE/launch 从别的目录启动导致环境变量没带上——"在我终端里能跑，在 launch 里 404"。处方：路径一律绝对路径；团队统一用一个 env setup 脚本，所有启动方式（命令行、launch、CI）都先 source 它。

# 团队统一入口: env.sh 放仓库根, 任何启动前 source
export GZ_SIM_RESOURCE_PATH="$HOME/robot_sim/models:$PWD/models:$GZ_SIM_RESOURCE_PATH"
export GZ_SIM_SYSTEM_PLUGIN_PATH="$PWD/build/plugins:$GZ_SIM_SYSTEM_PLUGIN_PATH"
​

可复现性：把"环境"也当代码管

仿真是实验装置，实验装置的第一美德是可复现。三条实操：

1. 自建模型库进版本管理。 meshes 大文件用 LFS；每个模型 model.config 里的 version 语义化递增。
2. Fuel 依赖显式化。Fuel 模型会更新，今天引用的版本明天可能变样。关键实验把用到的 Fuel 模型下载进本地库并锁定，世界文件引用本地 URI。
3. CI 冷启动验证。流水线里从零 clone 仓库 → source env.sh → gz sim -s -r smoke_test.sdf 跑 1000 步退出。任何路径漂移、模型缺失都会在这里暴露，而不是在同事的演示现场。

依赖审计：把 model:// 全部钉在纸上

路径栈的第 4 行（Fuel 远程）是可复现性的暗门：世界文件里一个 <uri> 指向 Fuel，内网 CI 或三年后的复现就会卡住。治理办法是给仓库做一次依赖审计——扫描所有世界与模型文件里的 model:// 引用，逐一核对本地库是否收录：

# 列出仓库引用的全部 model:// URI 及其是否能被当前路径栈解析
grep -rhoE "model://[a-zA-Z0-9_/-]+" --include="*.sdf" --include="*.config" . \
  | sort | uniq -c | sort -rn > uri_inventory.txt
# 逐个验证解析结果（打印实际命中的目录）
while read -r cnt uri; do
  path="${uri#model://}"
  found=$(find $GZ_SIM_RESOURCE_PATH -maxdepth 2 -type d -name "$path" 2>/dev/null | head -1)
  echo "${uri} -> ${found:-未在本地库找到(将走Fuel或失败)}"
done < uri_inventory.txt
​

审计输出分三类处理：命中本地库的正常项不动；"未在本地库找到"且来自 Fuel 的，用 gz fuel download 落库并把引用改写成本地 URI；拼错或废弃的引用当场清理。这份 uri_inventory.txt 本身值得进版本管理——它就是场景资产的依赖清单，评审新世界文件时 diff 一下，新增的外部依赖一目了然。配合上一节的 CI 冷启动，Fuel 依赖从"碰运气的隐性输入"变成"钉在纸上的显性资产"，可复现三件套才算闭环。

本节要点回顾

• 模型 = 三件套目录：model.config 名片 + model.sdf 本体 + 素材；Fuel 是公共库，本地库是团队资产。
• 解析顺序：内置 → 环境变量 → Fuel 缓存/远程；启动失败先查 GZ_SIM_RESOURCE_PATH 是否真的传进了那个进程。
• 统一 env.sh：绝对路径、所有启动方式共 source，终结"在我机器上能跑"。
• 可复现三件套：模型库版本化、Fuel 依赖锁定、CI 冷启动冒烟。

至此，物理账、场景账都已入册。最后一章处理感知账：传感器数据不是"拍"出来的，是渲染引擎与噪声模型合谋"造"出来的——理解这一点，你的算法才不会被过分干净的仿真数据惯坏。