Three.js 模型导入后显示黑色的常见原因及解决方案

Three.js 模型导入后显示黑色的常见原因及解决方案

在使用 Three.js 进行 WebGL 开发时，经常会遇到模型加载成功但渲染出来是黑色的情况。这通常不是模型文件损坏，而是场景配置或材质属性未对齐导致的。作为老手，我遇到过两次这类问题，排查下来主要集中在以下两个方面。

材质属性与阴影设置

很多时候模型本身有贴图，但在默认材质下无法正确反射光线。在加载回调中遍历模型子对象，手动调整材质属性是一个有效的调试手段。特别是 emissive（自发光）属性的设置，能让物体在无光照环境下也能显现颜色。

loader.load('xxx.3mf', function ( object ) {
  object.traverse( function ( child ) {
    if ( child.isMesh ) {
      child.castShadow = true;
      // 将基础色赋予自发光属性，确保可见性
      if ( child.material ) {
        child.material.emissive = child.material.color;
        child.material.emissiveMap = child.material.map;
      }
    }
  });
  scene.add( object );
});

注意这里加了 child.isMesh 的判断，避免对非网格对象误操作。同时，如果后续需要真实光照效果，记得把 emissive 改回正常逻辑，否则物体会一直发亮。

场景光照缺失

Three.js 的场景默认没有光。如果没有添加任何光源，所有物体都会因为接收不到光线而呈现黑色。这是新手最容易忽略的环节。

我们需要至少补充环境光来提供基础亮度，再配合点光源模拟主光源方向：

// 1. 添加环境光，照亮整个场景
let ambientLight = new THREE.AmbientLight(0xffffff);
scene.add(ambientLight);

// 2. 添加点光源，模拟具体照射位置
let pointLight = new THREE.PointLight(, , );
pointLight..(, , );
scene.(pointLight);