Web 图形与 3D / 系统课时

处理加载进度、失败与重试

处理加载进度、失败与重试

模型文件下载到 100% 后,仍可能在解析网格、解码纹理或等待外部资源。本篇用 LoadingManager 与 GLTFLoader 分别跟踪请求和模型结果,做出能提示进度、展示失败原因并支持手动重试的 Three.js 页面,避免资源异常时持续空白。

学习目标

  • 区分字节下载进度、资源完成计数和模型真正可用的时机。
  • 用成功、进度及错误回调控制加载提示和重试按钮。
  • 通过浏览器 Network 与 Console 复现并定位加载失败。

区分下载、解析和可用状态

GLTFLoader.load(url, onLoad, onProgress, onError) 中的 onProgress 报告主文件传输事件:loaded 是已接收字节数,只有 lengthComputable 为 true 且 total > 0 时,才能计算 loaded / total × 100%。若响应没有可用的总长度,显示“已接收多少 KiB”或不确定进度条,不要假定总数。

LoadingManager.onProgress(url, itemsLoaded, itemsTotal) 关注的是已结束的资源请求数,不是字节进度;这里的总请求数还可能随外部纹理等依赖被发现而增加。manager.onError(url) 可以指出失败的资源 URL,但完整的失败提示由 GLTFLoader 的 onError(error) 处理。

判断模型是否能加入场景,应以 GLTFLoader.onLoad(gltf) 为准。主文件下载 100%、管理器计数达到总数,甚至 manager.onLoad 触发,都不应直接当成模型解析成功:资源请求可能已结束但解析尚未完成,或其中有请求失败。

相关接口定义可查阅 GLTFLoader 官方文档 和 LoadingManager 官方文档。

GLB 下载、解析与失败重试的事件和状态流程

实现加载提示和手动重试

示例适用于 Vite 的原生 JavaScript 模板与当前支持 three/addons 导入路径的 Three.js。先创建项目并安装依赖:

bash
npm create vite@latest gltf-status -- --template vanilla
cd gltf-status
npm install
npm install three

预期结果:项目中出现 package.json、src/main.js 和 node_modules/three,安装命令没有报错。准备一个未使用 Draco 或 KTX2 扩展压缩、位于原点附近的有效 GLB,放在 public/models/model.glb;这个文件需要由读者自行提供。

将 src/main.js 替换为以下完整代码。每次加载创建独立管理器;失败后才显示按钮,重试会清空上次提示并重新发出请求。

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

document.body.style.margin = '0';
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf4f7fa);
const camera = new THREE.PerspectiveCamera(
  45, window.innerWidth / window.innerHeight, 0.1, 100
);
camera.position.set(0, 1.2, 4);
camera.lookAt(0, 0, 0);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
scene.add(new THREE.HemisphereLight(0xffffff, 0x667788, 2));
const sun = new THREE.DirectionalLight(0xffffff, 3);
sun.position.set(3, 5, 4);
scene.add(sun);

const panel = document.createElement('div');
panel.style.cssText = 'position:fixed;top:16px;left:16px;z-index:2;background:white;padding:12px;font:14px sans-serif';
panel.innerHTML = '<div id="state"></div><div id="bytes"></div><div id="items"></div><button id="retry" hidden>重新加载</button>';
document.body.appendChild(panel);
const state = panel.querySelector('#state');
const bytes = panel.querySelector('#bytes');
const items = panel.querySelector('#items');
const retry = panel.querySelector('#retry');

let attempt = 0;
function loadModel() {
  const id = ++attempt; // 防止旧请求回调覆盖新一轮状态
  retry.hidden = true;
  state.textContent = '正在请求模型…';
  bytes.textContent = '主文件:等待传输';
  items.textContent = '资源:等待统计';

  const manager = new THREE.LoadingManager();
  manager.onProgress = (_url, done, total) => {
    if (id !== attempt) return;
    items.textContent = `已结束请求:${done}/${total}`;
  };
  manager.onError = (url) => {
    if (id === attempt) console.error('资源请求失败:', url);
  };

  const loader = new GLTFLoader(manager);
  loader.load(
    `${import.meta.env.BASE_URL}models/model.glb`,
    (gltf) => {
      if (id !== attempt) return;
      scene.add(gltf.scene); // 只有此时才确认模型已解析可用
      state.textContent = '模型加载成功';
      bytes.textContent = '下载和解析已完成';
    },
    (event) => {
      if (id !== attempt) return;
      if (event.lengthComputable && event.total > 0) {
        const percent = Math.min(100, Math.round(event.loaded / event.total * 100));
        bytes.textContent = `主文件下载:${percent}%`;
        if (percent === 100) state.textContent = '下载结束,等待解析或依赖资源…';
      } else {
        bytes.textContent = `已接收 ${Math.round(event.loaded / 1024)} KiB(总量未知)`;
      }
    },
    (error) => {
      if (id !== attempt) return;
      state.textContent = '加载失败,请检查资源后重试';
      console.error('模型加载失败:', error);
      retry.hidden = false;
    }
  );
}

retry.addEventListener('click', loadModel);
renderer.setAnimationLoop(() => renderer.render(scene, camera));
loadModel();

window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

预期结果:页面先显示加载提示;模型解析成功后出现 3D 模型和“模型加载成功”,重试按钮保持隐藏。进度百分比和资源计数受文件大小、缓存及响应头影响,可能很快跳过或不出现。

验证失败与恢复

启动开发服务器:

bash
npm run dev

预期结果:终端出现 Vite 的 Local 访问地址,例如 http://localhost:<PORT>/;<PORT> 为实际分配的端口。按下面步骤测试,不必修改主逻辑:

  1. 打开浏览器开发者工具的 Network 与 Console,确认 models/model.glb 的响应确实为 GLB 文件,页面能显示模型。
  2. 在 Chrome 开发者工具中通过 More tools → Network request blocking 拦截匹配 *model.glb 的请求,然后刷新。预期页面显示“加载失败”和“重新加载”,Console 给出加载错误;具体错误文本依浏览器而异。
  3. 停用请求拦截并点击“重新加载”。预期重新请求模型并恢复成功状态,页面上只有一个模型实例。

测试中若主文件显示下载 100%,但页面仍提示等待解析,不应立即认定卡死。较大的模型、外部纹理或解码工作会延后 GLTFLoader.onLoad;只有进入成功回调才隐藏加载状态。

按网络响应定位故障

观察到的现象 优先检查 处理方式
请求为 404,或返回 200 但内容是 HTML public 文件位置、部署基础路径、SPA 回退页面 文件放到 public/models/model.glb,使用 import.meta.env.BASE_URL 组合请求路径
请求被阻断,出现 CORS、401 或 403 跨域响应头、身份认证与资源权限 修复服务端授权和允许的来源,而不是不断自动重试
GLB 已下载但解析报错 文件完整性、glTF 扩展与解码器 用 glTF Validator 检查文件;使用 Draco/KTX2 时按格式配置相应加载器
成功回调已触发但画面无模型 gltf.scene 内容、尺寸、相机朝向 检查模型边界盒并调整相机,不要误判为下载失败

这个实现把请求统计交给 LoadingManager,把是否能加入场景交给 GLTFLoader.onLoad,把失败后重新请求交给界面按钮。生产项目还可以按需要增加超时提示、取消请求和有限次数的退避重试。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理加载进度、失败与重试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通