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(0xffffff, 1, 0);
pointLight.position.set(200, 200, 200);
scene.add(pointLight);
实际项目中，建议根据模型大小调整光源位置和强度。比如大场景可能需要平行光，小物件则点光源足够。检查完这两项，大部分黑模问题都能解决。如果依然不行，再考虑纹理路径错误或材质侧向（Side）设置的问题。