📚 课程目录第3章项目结构解剖

3、项目结构解剖：一个标准 Isaac Sim 项目的文件组织方式

拿到一个新项目，第一件事是什么？

我个人习惯，不是急着点运行，而是先看文件夹。就像搬进新家，先搞清楚厨房在哪、厕所在哪，心里才有底。Isaac Sim 项目也一样，文件结构就是它的骨架。骨架搭得清楚，后面调试、扩展、团队协作都会顺很多。

3.1 顶层目录：一眼看穿项目全貌

一个标准的 Isaac Sim 项目，通常长这样：

my_robot_project/
├── config/
├── extensions/
├── worlds/
├── robots/
├── scripts/
├── assets/
├── logs/
├── .vscode/
├── user.config.json
└── README.md

嗯，别被吓到。每个文件夹都有它的使命。我拆开来讲。

目录/文件	作用	我踩过的坑
`config/`	存放项目配置文件，比如机器人参数、传感器配置	曾经把路径写死在这里，换台机器就崩了
`extensions/`	自定义扩展模块，核心业务逻辑放这	扩展命名不规范，导致加载顺序错乱
`worlds/`	场景文件（.usd），定义仿真环境	场景文件太大，git 提交慢到怀疑人生
`robots/`	机器人模型文件（.usd/.urdf）	URDF 转 USD 时材质丢失，折腾了两天
`scripts/`	启动脚本、测试脚本、工具脚本	脚本和扩展耦合太紧，改一处崩一片
`assets/`	贴图、音频、额外资源	资源路径用中文，Linux 下直接报错
`logs/`	运行时日志，排查问题第一站	日志不轮转，磁盘爆满才反应过来

我的习惯： 每个项目根目录下放一个 .gitignore，把 logs/、*.pyc、__pycache__/ 都忽略掉。不然你提交代码时，会发现一堆没用的垃圾文件。

3.2 核心灵魂：extensions 目录

说白了，extensions/ 才是项目的灵魂。Isaac Sim 的扩展机制，跟插拔U盘一样——你写好一个扩展，它就能被引擎加载，提供独立的功能模块。

一个标准扩展的内部结构：

extensions/
└── my_robot_extension/
    ├── __init__.py
    ├── extension.py
    ├── config/
    │   └── extension.toml
    ├── ui/
    │   ├── __init__.py
    │   └── main_window.py
    ├── controllers/
    │   ├── __init__.py
    │   └── robot_controller.py
    └── tests/
        └── test_controller.py

这里有几个关键文件：

extension.toml：扩展的身份证。名字、版本、依赖、加载顺序都写在这。格式不对，扩展根本加载不起来。
extension.py：扩展的入口。Isaac Sim 启动时会调用这里的 on_startup() 和 on_shutdown() 方法。
ui/：界面逻辑。我习惯把 UI 和业务逻辑分开，这样改界面不用动控制器代码。
controllers/：业务逻辑。机器人控制、传感器数据处理都放这。

注意： 扩展的 __init__.py 不能为空。至少写一句 from .extension import MyExtension。我曾经漏了这行，结果扩展加载了但啥也不干，排查了整整一个下午。

3.3 场景与模型：worlds 和 robots 的协作

你想想看，仿真仿真，核心就两样东西：环境（world）和机器人（robot）。

worlds/ 里放的是场景文件，通常是 .usd 格式。一个场景可以包含地面、墙壁、障碍物、光照、甚至动态物体。

robots/ 里放的是机器人模型。可以是 .usd，也可以是 .urdf。如果是 URDF，Isaac Sim 会自动帮你转成 USD，但转换过程可能会有坑——比如关节限位丢失、碰撞模型偏移。

我一般这样组织：

worlds/
├── warehouse.usd        # 仓库场景
├── outdoor.usd          # 室外场景
└── empty_room.usd       # 空房间，用于测试

robots/
├── my_robot.usd         # 主机器人
├── my_robot_urdf/       # URDF 源文件
│   ├── my_robot.urdf
│   └── meshes/
└── sensor_rig.usd       # 传感器支架

  经验之谈： 场景文件和机器人文件尽量用相对路径引用资源。路径一换机器就废。我见过一个项目，所有路径都写 C:/Users/xxx/...，拿到 Linux 服务器上直接瘫痪。

3.4 配置文件：把参数从代码里抽出来

代码里硬编码参数，是新手最容易犯的错。比如把机器人速度写死在控制器里，换个场景就得改代码。

我的做法：所有可调参数都放到 config/ 目录下，用 JSON 或 YAML 管理。

config/
├── robot_params.json       # 机器人物理参数
├── sensor_config.yaml      # 传感器配置
└── simulation_settings.json # 仿真步长、重力等

举个例子，robot_params.json 长这样：

{
  "max_linear_velocity": 1.5,
  "max_angular_velocity": 0.8,
  "wheel_radius": 0.1,
  "base_mass": 20.0
}

然后在代码里用 json.load() 读取。想调参数？改配置文件就行，不用动一行代码。

小技巧： 配置文件里加个 "version" 字段。我吃过亏——参数文件被改了，但不知道是哪个版本，回退都找不到依据。

3.5 项目结构全景图

说了这么多，画张图帮你理清关系。

3.6 避坑指南：我见过的文件组织灾难

这些年我接手过不少项目，有些结构真是让人头大。总结几个常见问题：

所有代码塞一个文件夹：扩展、脚本、测试全混在一起。找文件靠猜，改代码靠运气。
大文件不拆分：一个 .py 文件写 3000 行。你想想看，光滚动就要滚半天。
忽略 __init__.py：Python 包识别全靠它。少了它，import 直接报错。
资源路径用中文或空格：Windows 下可能没事，Linux 下直接崩。我吃过这个亏，教训深刻。
没有版本控制：项目文件夹叫 final_v3_真的不改了。结果第二天又改了一版。

血的教训： 我曾经接手一个项目，所有文件都在根目录下，文件名是 1.py、2.py、3.py…… 你猜哪个是主入口？我花了三天才理清楚。从那以后，我坚持每个项目必须按标准结构组织。

3.7 小结

项目结构这件事，说白了就是「规矩」。规矩立好了，后面写代码、调试、交接都轻松。规矩没立好，后面全是坑。

我个人建议，拿到一个新项目，先花 10 分钟看文件夹结构。如果结构混乱，先重构再动手。别急着跑代码——骨架歪了，肉长上去也是畸形的。