如何在ThreeJS层级中添加GLTF模型？Forge Viewer开发加载扩展报错处理

算力阿峰

2026-10-2

报错原因

Forge Viewer 内置的 Three.js 是定制版本，和你外部引入的最新版 Three.js 构造的类实例不兼容，overlays.addMesh 仅支持识别 Viewer 内置 Three 生成的对象；且该方法仅支持传入单个 Mesh 实例，你直接传入整个 gltf.scene 复合对象也会触发异常。

解决方案

优先使用 Viewer 内置的 Three 实例加载模型，同时遍历模型内所有 Mesh 节点逐个添加到 overlay 场景，修正后的代码如下：

// 从Viewer实例获取内置的THREE对象，不要使用外部引入的版本
const THREE = this.viewer.impl.THREE;
const gltfLoader = new THREE.GLTFLoader();
const overlayName = "gltf";

// 提前初始化overlay场景
if (!this.viewer.overlays.hasScene(overlayName)) {
  this.viewer.overlays.addScene(overlayName);
}

gltfLoader.load(
  "https://threejsfundamentals.org/threejs/resources/models/cartoon_lowpoly_small_city_free_pack/scene.gltf",
  (gltf) => {
    // 遍历所有Mesh节点逐个添加
    gltf.scene.traverse(node => {
      if (node.isMesh) {
        this.viewer.overlays.addMesh(node, overlayName);
      }
    });
    // 触发Viewer重渲染
    this.viewer.impl.invalidate(true);
  }
);