Three.js 怎么加载 GLTF/GLB 模型及处理纹理缺失

一、GLTF 与 GLB 的文件机制与贴图存储方式

要彻底解决纹理缺失，首先需要理解 .gltf 与 .glb 在资源存储组织上的本质差异。很多新手直接将两者混为一谈，导致在文件迁移或部署时丢失关键依赖。

.gltf（分体式格式） 本质是一个基于 JSON 的文本文件，它记录了三维场景的节点树层级、骨骼骨架、网格索引以及材质参数描述。然而，模型的几何顶点数据通常存放在单独的 .bin 文件中，而漫反射贴图、法线贴图和粗糙度金属度贴图等图片文件（如 .png、.jpg）则保存在外部独立子目录（如 textures/）。在 .gltf 文件的 images 属性中，仅记录了这些图片的相对 URI 字符串。

.glb（单文件一体包） 是 GLTF 的二进制封装版本。它将 JSON 场景定义、几何体二进制缓冲区（Binary Buffer）以及所有的图片原始字节流全部压缩封装在同一个二进制文件中。

从图 1 可以看出，纹理丢失绝大多数发生在采用 .gltf 分体文件的情况下。当网页将 model.gltf 部署在例如 /assets/models/ 目录时，如果网页本身运行在根目录 /，GLTFLoader 内部默认会尝试以网页所在当前路径或请求路径拼接贴图。如果贴图没有正确存放在预期路径，浏览器就会产生 404 错误，导致模型变成无贴图的白模或粉紫占位色。因此在生产环境中，优先推荐导出为 .glb 单文件，从源头切断路径断链问题。

二、Three.js 标准模型加载步骤

使用 Three.js 加载模型并非只调用一个加载函数，而是需要一个协同工作的完整闭环：渲染器基准设置、环境照明、加载器初始化、子网格遍历以及挂载到场景中。

按照图 2 的标准化流程，具体的代码实现步骤如下：

步骤 1：引入依赖与配置 WebGLRenderer

在现代前端工程（Vite、Webpack 或原生 ES Module）中，直接从 three/addons/loaders/GLTFLoader.js 引入 GLTFLoader。在初始化渲染器时，务必明确色彩空间。

import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

// 初始化场景与相机
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.set(0, 2, 5);

// 初始化渲染器并配置正确的色彩空间（针对 Three.js r152 及更新版本）
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

// 必须配置：统一渲染管线输出色彩空间为 sRGB，杜绝贴图泛白发灰
renderer.outputColorSpace = THREE.SRGBColorSpace;
document.body.appendChild(renderer.domElement);

步骤 2：布置必不可少的基础光照

GLTF/GLB 模型默认使用 PBR（基于物理渲染）材质——MeshStandardMaterial 或 MeshPhysicalMaterial。这类材质对光照有强依赖。如果在场景中没有添加任何灯光，即使纹理完全加载成功，模型在屏幕上也只会呈现纯黑色。很多开发者常将这种“无光照引起的黑模”误判为“纹理丢失”。

// 1. 添加环境光：为模型提供均匀的漫反射基础亮度
const ambientLight = new THREE.AmbientLight(0xffffff, 1.2);
scene.add(ambientLight);

// 2. 添加方向平行光：产生高光、明暗体积感与阴影
const dirLight = new THREE.DirectionalLight(0xffffff, 2.0);
dirLight.position.set(5, 10, 7);
scene.add(dirLight);

步骤 3：实例化 GLTFLoader 并执行异步加载

通过 loader.load() 方法异步载入模型。在成功回调函数中，gltf.scene 即为该模型根容器对象（Group）。

const loader = new GLTFLoader();

// 如果需要加载包含 Draco 压缩的几何体，需配合 DRACOLoader
// import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
// const dracoLoader = new DRACOLoader();
// dracoLoader.setDecoderPath('/draco/');
// loader.setDRACOLoader(dracoLoader);

loader.load(
  'models/robot.glb',
  (gltf) => {
    const model = gltf.scene;

    // 步骤 4：遍历所有子对象，规范材质与法线
    model.traverse((child) => {
      if (child.isMesh) {
        // 确保材质双面渲染，避免内翻面或法线反向造成表面缺失
        if (child.material) {
          child.material.side = THREE.DoubleSide;
        }
        child.castShadow = true;
        child.receiveShadow = true;
      }
    });

    // 步骤 5：挂载到场景中
    scene.add(model);
  },
  (xhr) => {
    // 进度回调（单位：百分比）
    if (xhr.total > 0) {
      const percent = (xhr.loaded / xhr.total) * 100;
      console.log(`模型加载进度: ${Math.round(percent)}%`);
    }
  },
  (error) => {
    console.error('模型加载失败:', error);
  }
);

三、纹理缺失的常见病因与针对性解决方案

当模型加载后未能正确显示纹理时，请不要盲目重导模型。根据实际表现，通过下面的故障排查决策树进行针对性核验。

1. 相对路径断裂与 setResourcePath() 的正确运用

典型现象：打开浏览器开发者工具（F12）的 Network（网络）面板，看到大量 .png 或 .jpg 请求报 404 Not Found。例如模型存放于 /static/models/car/car.gltf，但浏览器却向 /static/textures/wheel.png 发起请求。

根本原因：.gltf JSON 内部只写了 "uri": "textures/wheel.png"，GLTFLoader 默认以传入的 URL 字符串的相对目录作为前缀。如果在深层复杂路由或静态资源 CDN 部署下，解析的基础 URL 会脱幅。

解决方法：在调用 loader.load() 之前，显式调用 setResourcePath()，将关联纹理的基准网络目录单独指定：

const loader = new GLTFLoader();

// 1. 设置模型本体所在的目录路径
loader.setPath('https://cdn.example.com/assets/models/car/');

// 2. 核心：明确指定贴图引用的基准子目录（末尾务必带斜杠 /）
loader.setResourcePath('https://cdn.example.com/assets/models/car/textures/');

loader.load('car.gltf', (gltf) => {
  scene.add(gltf.scene);
});

2. 色彩空间（Color Space）不匹配导致贴图发灰或死黑

典型现象：贴图请求正常（200 OK），模型身上也有花纹，但整个模型看起来灰蒙蒙、色彩发白严重褪色，或者暗部严重死黑无过渡。

根本原因：数字图像（PNG/JPG）通常在 sRGB 空间进行伽马编码（Gamma 2.2），而 WebGL 着色器在物理线性空间（Linear）进行光照计算，最终由屏幕再还原回 sRGB。在 Three.js r152 之后，色彩管理全面重构，废弃了旧版 renderer.outputEncoding = THREE.sRGBEncoding，改用标准属性 renderer.outputColorSpace = THREE.SRGBColorSpace。

如果渲染器或纹理对象的色彩空间配置不一致，就会导致二次伽马矫正或未矫正：

• 固有色贴图（BaseColor / map）：必须声明为 THREE.SRGBColorSpace。
• 数据类贴图（法线 normalMap、粗糙度 roughnessMap、金属度 metalnessMap）：必须保持默认的 THREE.NoColorSpace（即线性空间），否则法线凹凸计算彻底错乱。

// 1. 确保渲染器已开启 SRGB 输出
renderer.outputColorSpace = THREE.SRGBColorSpace;

// 2. 在模型 traverse 遍历时，校验基础颜色贴图的色彩空间
model.traverse((child) => {
  if (child.isMesh && child.material) {
    const mat = child.material;
    
    // 如果存在固有色纹理，确保其被正确标记为 SRGB 空间
    if (mat.map) {
      mat.map.colorSpace = THREE.SRGBColorSpace;
      mat.map.needsUpdate = true;
    }
    mat.needsUpdate = true;
  }
});

3. 本地 file:// 协议与跨域 CORS 拦截

典型现象：直接在本地文件夹中双击 index.html，控制台报错：Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///...，或者出现 Canvas 被污染的报错。

解决方法：

1. 本地调试：不要直接双击 HTML 文件运行。在项目目录下通过终端启动本地静态服务器，如 npx serve . 或使用 VSCode 的 Live Server 插件。
2. 跨域生产环境：如果 3D 资产存放在阿里云 OSS、腾讯云 COS 或独立 CDN 域名下，必须在云端存储桶设置 CORS（跨域资源共享） 规则，允许 GET 请求且 AllowedOrigin: *。
3. 同时在代码中为加载器配置跨域凭证属性：

const manager = new THREE.LoadingManager();
manager.setCrossOrigin('anonymous'); // 允许匿名跨域拉取贴图

const loader = new GLTFLoader(manager);

4. 材质解绑时的手动纹理重构与替换

典型场景：在部分从 Sketchup、FBX 转存或由于建模导出设置疏忽的场景下，模型导出时仅保留了模型几何 UV 坐标，材质贴图丢失了绑定关系；或者在业务场景中，需要根据用户操作动态换装。此时可以使用 THREE.TextureLoader 手动加载图片并重新赋予网格。

const textureLoader = new THREE.TextureLoader();

// 异步载入独立贴图
textureLoader.load('textures/custom_diffuse.jpg', (customTexture) => {
  // 设置纹理参数
  customTexture.colorSpace = THREE.SRGBColorSpace; // 关键：sRGB
  customTexture.wrapS = THREE.RepeatWrapping;
  customTexture.wrapT = THREE.RepeatWrapping;
  customTexture.flipY = false; // GLTF 规范贴图通常不需要 Y 轴翻转

  // 查找到目标网格并替换贴图
  const targetMesh = model.getObjectByName('Body_Mesh');
  if (targetMesh && targetMesh.material) {
    targetMesh.material.map = customTexture;
    targetMesh.material.needsUpdate = true; // 触发材质着色器重编译
  }
});

四、工程实战：完整健壮的加载模板代码

以下是一份可在生产项目中直接复用的完整 HTML/JavaScript 范例。它集成了加载管理器、路径解析、灯光设置、子网格遍历、色彩空间纠偏以及响应式窗口适配。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Three.js 健壮加载 GLTF/GLB 演示</title>
  <style>
    body { margin: 0; overflow: hidden; background-color: #17324D; }
    #canvas-container { width: 100vw; height: 100vh; }
    #loading-ui {
      position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
      color: #FAFBFD; font-family: sans-serif; font-size: 16px;
      background: rgba(23, 50, 77, 0.85); padding: 12px 24px; border-radius: 8px;
    }
  </style>
</head>
<body>
  <div id="loading-ui">正在加载 3D 资产...</div>
  <div id="canvas-container"></div>

  <script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
      "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
    }
  }
  </script>

  <script type="module">
    import * as THREE from 'three';
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
    import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

    // 1. 基础场景搭设
    const container = document.getElementById('canvas-container');
    const scene = new THREE.Scene();
    scene.background = new THREE.Color('#17324D');

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

    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setSize(window.innerWidth, window.innerHeight);
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    // 强制色彩空间与阴影支持
    renderer.outputColorSpace = THREE.SRGBColorSpace;
    renderer.shadowMap.enabled = true;
    container.appendChild(renderer.domElement);

    const controls = new OrbitControls(camera, renderer.domElement);
    controls.enableDamping = true;

    // 2. 完善的光照系统（防止死黑）
    const hemiLight = new THREE.HemisphereLight(0xffffff, 0x444444, 1.2);
    hemiLight.position.set(0, 20, 0);
    scene.add(hemiLight);

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

    // 3. 带监控的统一 LoadingManager
    const loadingUI = document.getElementById('loading-ui');
    const manager = new THREE.LoadingManager(
      () => {
        loadingUI.style.display = 'none'; // 加载完成隐藏 UI
      },
      (url, itemsLoaded, itemsTotal) => {
        loadingUI.innerText = `正在加载资源: ${itemsLoaded} / ${itemsTotal}`;
      },
      (url) => {
        console.error(`资源加载失败: ${url}`);
      }
    );

    // 4. 初始化 GLTFLoader 并设置资源路径
    const loader = new GLTFLoader(manager);
    
    // 若贴图在特定子目录，使用 setResourcePath 避免 404
    // loader.setResourcePath('assets/models/textures/');

    loader.load(
      'models/sample.glb', // 推荐优先加载 .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;

              // 校验并确保漫反射颜色贴图符合 sRGB 标准
              if (child.material.map) {
                child.material.map.colorSpace = THREE.SRGBColorSpace;
              }
              child.material.needsUpdate = true;
            }
          }
        });

        // 自动计算包围盒居中放置
        const box = new THREE.Box3().setFromObject(model);
        const center = box.getCenter(new THREE.Vector3());
        model.position.sub(center);

        scene.add(model);
      }
    );

    // 5. 渲染循环与窗口适配
    window.addEventListener('resize', () => {
      camera.aspect = window.innerWidth / window.innerHeight;
      camera.updateProjectionMatrix();
      renderer.setSize(window.innerWidth, window.innerHeight);
    });

    function animate() {
      requestAnimationFrame(animate);
      controls.update();
      renderer.render(scene, camera);
    }
    animate();
  </script>
</body>
</html>

五、生产环境避坑与纹理自检清单

为了保证模型在各种生产环境下均能快速加载并精确还原材质效果，可以按照下面的五维自检核查矩阵逐项确认。

掌握上述核心逻辑与排查工具后，在遇到 Three.js 模型加载及材质问题时，只需先通过浏览器控制台与网络面板判断是“资源 404 缺失”、“色彩空间偏差”还是“灯光缺失造成的暗黑”，便能根据对应的配置代码迅速修复。