怎么在 Three.js 中加载 GLTF/GLB 模型并修复材质丢失

一、GLTF 与 GLB 的文件机制与资源寻址差异

GLTF（GL Transmission Format）是由 Khronos Group 推出的开放标准 3D 传输格式，旨在成为“3D 领域的 JPEG”。在实际工程项目中，我们通常会接触到两种存储形态：后缀为 .gltf 的分离式文件，以及后缀为 .glb 的单文件二进制封包。

分离式 .gltf 本质是一个明文 JSON 文本文件，记录了场景节点树、网格定义、材质参数、相机与骨骼动画元数据。然而，网格的具体顶点坐标、法线向量和 UV 贴图坐标并不存储在 JSON 中，而是保存在一个独立的 .bin 二进制缓冲文件中；同时，漫反射贴图、法线贴图和粗糙度贴图则以独立的 PNG 或 JPEG 文件保存在外部目录（通常为 textures/）。

相比之下，.glb 是 GLTF 的二进制直接封包。它由 12 字节的文件头（包含魔数 0x46546C67 即 glTF、版本号与总字节数）、JSON 描述块、BIN 二进制块以及内嵌在缓冲区内的图片码流完整组成。

理解这一差异是排查“材质丢失”的基石。分离式 .gltf 极其脆弱，当开发者使用现代前端脚手架（如 Vite、Webpack 或 Next.js）打包部署时，构建工具通常会对静态资源进行路径哈希化或目录重组。如果 .gltf 内部记录的图片相对 URI（例如 "uri": "textures/diffuse.png"）与实际部署在服务器上的相对路径不匹配，浏览器在发起二次网络请求时就会收到 HTTP 404 响应。Three.js 无法取得纹理图像，便只能以白色底模或缺失占位状态渲染。

因此，在生产环境中，优先推荐直接导出并使用 .glb 格式。所有几何与纹理数据一次性传输交付，从根本上杜绝了因相对路径偏离造成的贴图丢失。

二、Three.js 中加载 GLTF/GLB 的标准流程与环境准备

在 Three.js 中载入模型，需要核心库以及扩展加载器 GLTFLoader。如果模型在导出阶段开启了 Google Draco 几何体压缩，还必须额外挂载 DRACOLoader，否则解析器将因无法识别压缩网格流而中断报错。

DRACO 压缩算法通过量化与差分编码大幅缩减了网格数据体积，但解码需要独立的 WebAssembly 或 JavaScript 解码器库。这些解码器文件位于 Three.js 仓库的 examples/jsm/libs/draco/ 目录下，需要完整复制到前端项目的静态公开资源目录（如 public/draco/）。

以下是完整的加载器初始化与场景挂载代码示例。代码涵盖了渲染器配置、DRACO 解码器路径注入、模型加载监听以及基础光源配置：

import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';

// 1. 初始化场景与渲染器
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf0efeb);

const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.set(3, 2, 5);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

// 关键：现代 Three.js (r152+) 必须配置色彩空间，确保贴图颜色准确输出
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.shadowMap.enabled = true;
document.body.appendChild(renderer.domElement);

// 2. 注入基础光源（PBR 材质依赖光照计算）
const ambientLight = new THREE.AmbientLight(0xffffff, 0.8);
scene.add(ambientLight);

const dirLight = new THREE.DirectionalLight(0xffffff, 1.5);
dirLight.position.set(5, 10, 7.5);
dirLight.castShadow = true;
scene.add(dirLight);

// 3. 配置 DRACO 解码器与 GLTFLoader
const dracoLoader = new DRACOLoader();
// 指向存有 draco_decoder.wasm 和 draco_decoder.js 的静态服务目录
dracoLoader.setDecoderPath('/draco/');

const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);

// 若使用分离式 .gltf 且贴图存放在特定目录，可通过 setResourcePath 统一指定基准路径
// gltfLoader.setResourcePath('/models/textures/');

// 4. 执行异步加载
gltfLoader.load(
  '/models/sample_model.glb',
  (gltf) => {
    const model = gltf.scene;

    // 遍历模型网格，执行材质校验与属性修复
    model.traverse((child) => {
      if (child.isMesh) {
        child.castShadow = true;
        child.receiveShadow = true;

        if (child.material) {
          // 开启双面渲染，杜绝单面剔除导致的背光隐形或破面
          child.material.side = THREE.DoubleSide;
          child.material.needsUpdate = true;
        }
      }
    });

    scene.add(model);
    console.log('模型及材质装配成功');
  },
  (xhr) => {
    const percent = Math.round((xhr.loaded / xhr.total) * 100);
    console.log(`加载进度: ${percent}%`);
  },
  (error) => {
    console.error('模型加载失败，请核查路径与网络状态:', error);
  }
);

// 5. 循环渲染
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;

function animate() {
  requestAnimationFrame(animate);
  controls.update();
  renderer.render(scene, camera);
}
animate();

三、材质丢失与黑模异常的四大核心诱因与排查

在实际项目反馈中，“模型加载成功但材质不正确”往往表现为纯黑剪影、无贴图白模、颜色过暗失真或旋转时局部破面。针对这些不同症状，应按因果逻辑逐项诊断。

1. 诱因一：场景未注入有效光照（表现为模型全黑）

这是最常见但最容易被误判为“材质丢失”的技术现象。GLTF 规范默认使用基于物理渲染的 PBR 材质（在 Three.js 中映射为 MeshStandardMaterial 或 MeshPhysicalMaterial）。PBR 材质的表面着色完全依赖入射光辐照度和反射方程。

传统的 MeshBasicMaterial 不受光照影响即可自发光显示，但 PBR 材质在没有光照的暗室场景中，其反射辐照度计算结果为 0，因而渲染出纯黑像素。如果场景中只添加了弱光或完全没有灯光，模型轮廓存在但通体全黑。

排查与修复：检查场景中是否添加了 AmbientLight（环境光，提供整体漫反射基底）和 DirectionalLight（平行光，产生明暗面与高光），或使用 RGBELoader 载入 HDR 全景贴图并赋值给 scene.environment，为整个场景提供真实的环境光照（IBL）。

2. 诱因二：外部纹理路径解析失败或跨域拦截（表现为贴图全失/白模）

当模型结构正常显示但表面原本的图案、色彩和细节贴图完全缺失时，问题几乎全部出在贴图文件传输链路上。

打开浏览器开发者工具（F12）的 Network（网络） 面板，过滤 Img 或文件后缀，检查是否有状态码为 404 Not Found 或 403 Forbidden 的贴图请求。

排查与修复：

• 如果使用 .gltf，在调用 loader.load() 之前，通过 gltfLoader.setResourcePath('/your/texture/path/') 显式指定贴图资源的根目录；
• 如果静态资源存放在不同域名的 CDN 上，需确保 CDN 服务器响应头包含了 Access-Control-Allow-Origin: *，否则 WebGL 纹理上传将被浏览器的 CORS 安全策略拦截；
• 根治策略：直接将模型在 DCC 软件中重新导出为 .glb 格式，将贴图内嵌进二进制数据流。

3. 诱因三：渲染器与贴图色彩空间失配（表现为发灰、暗沉或泛白）

在 3D 渲染管线中，图像文件存储通常采用 sRGB 非线性色彩空间（经过 Gamma 校正以适应人眼观察），但在着色器计算阶段，所有物理光照公式必须在线性空间（Linear Space）中执行，最终由渲染器转回 sRGB 显示在屏幕上。

在旧版 Three.js 中，开发者习惯配置 renderer.outputEncoding = THREE.sRGBEncoding，但在较新版本（r152+）中，旧属性已废弃，统一迁移至 renderer.outputColorSpace = THREE.SRGBColorSpace。

如果未配置渲染器颜色空间，或者模型的漫反射贴图（map）被错误解析为线性空间，渲染结果就会如同蒙上一层灰雾；反之，若法线贴图（normalMap）或粗糙度贴图（roughnessMap）被错误地赋予了 sRGB 转换，则会导致法线破损或光影计算过曝。

4. 诱因四：法线反转与背面剔除机制（表现为局部透明或穿透）

为了优化性能，WebGL 与 GPU 默认开启背面剔除（Backface Culling），即仅绘制三角形网格正面（顶点环绕顺序逆时针的面），背面直接丢弃不参与着色计算。

如果 3D 建模人员在建模软件中未统一法线朝向，或者模型中存在无厚度的单片网格（如布料下摆、树叶、窗纸），从特定角度观察时，背面就会变成完全透明，让读者误以为“该区域材质丢失”。此外，如果材质被错误开启了 transparent = true 但没有正确管理 depthWrite，也会引发视锥深度排序混乱。

四、遍历网格（Traverse）与批量修复材质的具体实现

在实际项目中，从外部导入的模型材质参数可能参差不齐。最稳妥的工程做法是在 gltfLoader.load 的完成回调中，通过 scene.traverse 递归遍历所有子节点，针对所有网格的材质进行统一校验与防御性修复。

以下函数展示了生产级的网格遍历修复逻辑，处理了材质数组兼容性、双面渲染、色彩空间校验以及贴图兜底：

/**
 * 对载入的 GLTF 模型执行全局材质与着色器校准
 * @param {THREE.Object3D} modelRoot - gltf.scene 根节点
 * @param {Object} options - 可选的修复参数
 */
function repairModelMaterials(modelRoot, options = {}) {
  const {
    forceDoubleSide = true,
    fixRoughness = true,
    enableShadows = true
  } = options;

  modelRoot.traverse((child) => {
    // 过滤出几何网格对象
    if (!child.isMesh) return;

    // 1. 投影与受影开关
    if (enableShadows) {
      child.castShadow = true;
      child.receiveShadow = true;
    }

    // 获取材质实例（兼容处理单个材质与 Multi-Material 材质数组）
    const materials = Array.isArray(child.material) 
      ? child.material 
      : [child.material];

    materials.forEach((mat) => {
      if (!mat) return;

      // 2. 开启双面渲染，杜绝单片面因背面剔除导致消失
      if (forceDoubleSide) {
        mat.side = THREE.DoubleSide;
      }

      // 3. 校准基础漫反射贴图的色彩空间为 sRGB
      if (mat.map) {
        mat.map.colorSpace = THREE.SRGBColorSpace;
      }

      // 4. 法线贴图、金属度与粗糙度贴图必须保持线性色彩空间
      if (mat.normalMap) mat.normalMap.colorSpace = THREE.NoColorSpace;
      if (mat.roughnessMap) mat.roughnessMap.colorSpace = THREE.NoColorSpace;
      if (mat.metalnessMap) mat.metalnessMap.colorSpace = THREE.NoColorSpace;

      // 5. 修复极端材质参数（避免高金属度在无 HDR 环境下纯黑）
      if (fixRoughness && mat.isMeshStandardMaterial) {
        // 部分模型导出时 metalness 为 1 且无 envMap，导致反射环境全黑
        if (mat.metalness === 1 && !mat.envMap) {
          mat.metalness = 0.2;
          mat.roughness = 0.6;
        }
      }

      // 6. 深度写入防护（非透明物体切勿关闭 depthWrite）
      if (!mat.transparent) {
        mat.depthWrite = true;
      }

      // 7. 标记材质着色器需要重新编译上传 GPU
      mat.needsUpdate = true;
    });
  });
}

五、模型导出与工程化上线的核查清单

要彻底避免材质丢失，不仅需要在 Three.js 前端代码中进行拦截和修复，还需要在资产制作、导出与服务端部署阶段建立严密的交付标准。

按照上述流程操作，从文件格式规范化、环境光照补齐、网络请求核实到遍历网格属性修复，即可快速定位并彻底根除 Three.js 中 GLTF/GLB 模型的材质丢失与黑屏问题，确保 3D 场景高保真稳定呈现。