Isaac Sim Troubleshooting 是一个针对 NVIDIA Isaac Sim 的故障排查技能，聚焦启动挂起、阶段加载停滞、MDL/着色器编译冻结、物理步进阻塞、Replicator/Hydra 问题、Nucleus 延迟以及 GPU 显存溢出崩溃等问题的诊断与解决。
用途 该技能用于定位和解决 Isaac Sim 在运行过程中的挂起、冻结与性能退化，尤其针对大规模 USD 场景（1 万至 15 万以上 prim，例如工厂或仓库数字孪生）。同时也可诊断独立库（standalone library）的导入、加载与链接失败。
前置条件 资料指出：库故障需要已配置好的构建环境或已安装的包环境；Kit/GPU 前置条件仅适用于所诊断的 Kit 工作负载。其余具体环境要求暂未提供。
诊断流程 资料提供了一份速查流程图，按发生阶段将问题分流：启动阶段（加载 stage 之前）归入启动挂起；关闭或 SimulationApp.close() 阶段归入关闭挂起；stage 打开/USD 加载阶段归入阶段加载挂起；着色器/材质编译阶段归入 MDL/着色器编译；物理步进、SimulationManager 设置或时间线播放阶段归入物理挂起；Replicator 或传感器采集阶段归入 Replicator 挂起；渲染阶段（视口冻结）归入 Hydra/渲染挂起；Nucleus/远程资产拉取归入 Nucleus 网络挂起；OOM 崩溃或内存飙升归入内存问题；缓慢但未冻结则归入性能优化。
主要能力与要点 启动挂起：常见原因包括扩展冲突（循环导入）、渲染器初始化冻结、高核心数 CPU 上的线程超额订阅，以及 Nucleus 登录弹窗卡死。资料给出的处理方式包括排除问题扩展、强制使用 Vulkan、重置用户设置、限制线程数，以及强制结束 Isaac Sim 并重启后先完成登录。 关闭挂起：症状为 SimulationApp.close() 永不返回，进程无限挂起，堆栈显示线程在 carb.tasking 线程池拆除期间阻塞于 futex_wait。根因描述为 shutdown_and_release_framework() 与 unload_all_plugins() 这类 C 扩展调用在持有 GIL 时发生原生线程 join 死锁，Python 侧的 threading.Event 看门狗因需要 GIL 而无法触发。资料给出的修复是使用 SIGALRM 看门狗：在阻塞式 C 调用前设置 alarm，死锁时由信号处理器无条件 SIGKILL 进程。资料强调在 CPython 中，当 Python 看门狗需要守护可能长期持有 GIL 的 C 扩展调用时，signal.alarm()（Linux）或 os.alarm() 是唯一可靠的、不依赖 GIL 的超时机制。相关参考文件为 source/extensions/isaacsim.simulation_app/isaacsim/simulation_app/simulation_app.py。 阶段加载挂起：通过 stage.GetUsedLayers() 检查图层数量，若超过 1,000 层则为主要瓶颈。资料对比了按资产文件与库打包两种策略（分别为 11,488 层约 4 分钟冷加载，与 8 层约 53 秒），建议将资产打包为库图层。同时需审计缺失或损坏的引用，它们会导致 USD 尝试包括网络回退在内的所有解析器。 着色器/MDL 编译：首次启动总会编译 MDL 着色器，可能耗时 5 至 15 分钟，属正常现象；后续启动使用着色器缓存，缓存位置为 ~/.nvidia-omniverse/data/Kit/Isaac-Sim/shader_cache/，删除缓存文件夹可强制重建。 物理挂起：物理设置或首次播放挂起通常由物理启动时尚未定义 PhysicsScene、首步接触对过多，或在超过 10 万刚体时启用 GPU 动力学引起。资料给出的修复包括在 reset 前确保 PhysicsScene 存在，以及启用稳定化以减少初始接触风暴。 Replicator 挂起：rep.orchestrator.run() 挂起需确保时间线正在播放；step_async() 永不完成需在异步上下文中正确 await；帧采集挂起需在采集前调用一次 update 以让渲染器刷新帧。 渲染（Hydra）挂起：视口黑屏冻结时检查 GPU 显存，RTX 渲染器 OOM 时可降低纹理流预算。 Nucleus 网络挂起：可设置超时、尽量使用本地资产，或通过启动参数禁用 Nucleus 以进行纯本地工作。 内存问题：prim 超过 15 万时启用实例化；纹理使用图集并降低分辨率；并给出监控 GPU 显存的命令。 性能优化：包括图层打包、网格实例化、将大型子场景标记为未加载的 payload，以及降低非关键对象的碰撞网格复杂度。
独立库诊断 资料建议在无 Kit 的普通进程中复现问题，检查已安装分发、wheel/原生依赖闭包、加载器路径与重定位；使用 isaacsim.common.logging.Logger 做库诊断，用 carb.log_* 做 Kit 日志，仅在需要有意输出到 stdout 结果时使用 print()。
上游调试文档 资料指向 docs/isaacsim/utilities/debugging/（性能分析与 Python 调试教程），并建议与 profile-isaac-sim 搭配，基于 Tracy 进行诊断。
限制 资料明确指出：症状清单属启发式，根因可能在不同子系统间重叠；部分修复需要本地 Kit 构建或 NVIDIA 内部专属包。