Autodesk Forge Viewing 加载含参考模型的ZIP后Model browser未显示已加载模型名称

核心问题定位 #

ZIP包含多模型可正常渲染但Model Browser无对应条目，本质是三类环节的配置错位导致：转换阶段未识别独立参考模型节点、Viewer组件加载时过滤了节点、Model Browser初始化逻辑未绑定已加载模型实例。

具体排查与解决方向 #

• 校验ZIP内的参考模型目录结构
  确保ZIP内主模型与关联参考模型的相对路径，和本地源文件引用时的目录结构完全一致：不要出现参考模型脱离主模型的引用路径层级、直接散落在ZIP根目录的错位情况，否则转换服务会仅解析主模型几何，不会将参考模型识别为独立的可枚举模型节点。
• 调整模型转换的作业参数
  提交转换任务时，需开启关联参考模型的完整解析配置，选择全量提取模式，不要使用仅提取主模型几何的精简转换规则。如果使用精简模式，所有参考模型的几何会被合并进主模型的节点树，不会生成可被Model Browser识别的独立模型条目。
• 检查Model Browser的节点过滤规则
  确认自定义的Model Browser初始化代码中，没有配置针对模型层级的过滤逻辑（例如仅展示带特定自定义属性的节点），这类规则会直接将参考模型对应的节点从树结构中剔除，需移除自定义过滤逻辑，恢复默认的全树渲染规则。
• 手动绑定已加载模型到Model Browser
  当视口已经可以正常渲染所有模型几何时，可直接遍历Viewer的已加载模型集合，手动将模型条目追加到Model Browser面板，绕开默认枚举逻辑的限制，参考实现代码如下：

// 遍历当前Viewer实例加载的全部模型
viewer.getAllModels().forEach((model, index) => {
    // 为每个模型生成带明确标识的面板条目，绑定对应模型的唯一UID
    modelBrowser.addModelItem(model, `已加载模型${index + 1}: ${model.getDocumentNodeName() || model.getURN()}`)
})

• 排除文件解析异常情况
  确认ZIP内的所有模型文件无加密、无文件锁、无指向ZIP包外部的素材关联路径，这类异常会导致转换服务静默跳过参考模型解析，既不生成树结构条目，也不会在任务反馈中抛出明确报错，需将所有模型依赖的关联文件全部打包进ZIP对应目录后重新提交转换。

内容的提问来源于stack exchange，提问作者bimal george