Web 图形与 3D / 系统课时

模型加载进度与错误如何处理

模型加载进度与错误如何处理

产品模型迟迟不出现时,用户需要知道正在下载、正在解析,还是已经失败。本篇使用 LoadingManager 和 GLTFLoader 制作带进度条、失败提示与重试按钮的最小页面,并通过缺失文件和断网验证处理路径。

学习目标

  • 区分单个模型的字节进度、资源项进度与模型真正就绪。
  • 使用加载回调更新界面,并分别记录资源错误和模型加载失败。
  • 验证 404、网络中断和重试后的成功状态。

区分资源进度与模型就绪

GLTFLoader.load(url, onLoad, onProgress, onError) 负责一个 glTF 模型;它的 onProgress(event) 反映文件传输情况。仅在 event.lengthComputable 且 event.total > 0 时,才能用 loaded / total × 100% 显示字节百分比。服务器未提供可用的总长度时,应显示不确定进度,而不是 NaN%。

LoadingManager 汇总其管理的资源请求。manager.onProgress(url, itemsLoaded, itemsTotal) 中的 2/5 表示已结束 5 项中的 2 项,不是下载了 40% 的字节。对于引用外部 .bin、纹理的 .gltf,资源总数还可能在加载期间增加,所以不要将这个比例当作稳定的整体百分比。

三个结束信号也不能混用:manager.onError(url) 指出某项资源出错;manager.onLoad() 表示受管理的资源项均已结束,即使其中有失败项也可能触发;只有 GLTFLoader 的 onLoad(gltf) 才适合把当前模型标为可加入场景。主文件下载达到 100% 时,解析和纹理解码也未必完成。接口定义可对照 GLTFLoader 与 LoadingManager 官方文档。

准备最小工程与样例资产

以下命令适用于 macOS、Linux 或 Windows Git Bash。先在空目录安装 Three.js 与 Vite,再将 Khronos 的 Duck GLB 样例下载到 Vite 的 public 目录。public/models/Duck.glb 在开发服务器中对应请求路径 /models/Duck.glb。

bash
npm init -y
npm install three
npm install --save-dev vite
mkdir -p public/models
# -f 使 HTTP 404 返回失败状态,避免保存错误页面
curl -fLsS https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Duck/glTF-Binary/Duck.glb -o public/models/Duck.glb
test -s public/models/Duck.glb && echo "样例模型已就绪"

预期输出(npm 安装日志因环境而异):

text
样例模型已就绪

在项目根目录创建 index.html,让加载界面与三维画布并列显示。progress 初始没有 value 属性,浏览器会显示不确定进度。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>glTF 加载状态演示</title>
  <style>
    body { margin: 0; font: 16px system-ui; }
    #stage { display: block; width: 100vw; height: 70vh; }
    #panel { padding: 16px; }
    #bar { width: 220px; }
  </style>
</head>
<body>
  <canvas id="stage"></canvas>
  <div id="panel" role="status" aria-live="polite">
    <span id="message">准备加载</span>
    <progress id="bar" max="100"></progress>
    <button id="retry" type="button" hidden>重试加载</button>
  </div>
  <script type="module" src="/main.js"></script>
</body>
</html>

这个页面尚未发起请求;三维画面与状态更新由接下来的 main.js 控制。

实现加载状态与重试

在项目根目录新建 main.js。这里使用同一个 LoadingManager 管理模型资源,但不在 manager.onLoad 中宣布成功。进度回调最多把进度条推进到 99,待 gltf.scene 交给场景后才设为 100;请求失败则保留可操作的重试按钮。

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

const canvas = document.querySelector('#stage');
const message = document.querySelector('#message');
const bar = document.querySelector('#bar');
const retry = document.querySelector('#retry');

const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xe9eff3);
scene.add(new THREE.HemisphereLight(0xffffff, 0x667788, 3));
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(0, 1, 4);
const modelSlot = new THREE.Group();
scene.add(modelSlot);

const manager = new THREE.LoadingManager();
manager.onProgress = (url, done, total) => {
  console.info(`资源已结束 ${done}/${total}: ${url}`);
};
manager.onError = (url) => console.error('资源请求失败:', url);
manager.onLoad = () => console.info('资源请求已结束,不代表模型成功');

const loader = new GLTFLoader(manager);
let attempt = 0;
const modelURL = '/models/Duck.glb';

function loadModel() {
  const current = ++attempt;
  retry.hidden = true;
  bar.removeAttribute('value');
  message.textContent = '正在请求模型…';

  // 每次重试使用新查询串,避免沿用浏览器缓存的失败响应
  loader.load(`${modelURL}?attempt=${current}`, (gltf) => {
    if (current !== attempt) return;
    modelSlot.clear();
    const bounds = new THREE.Box3().setFromObject(gltf.scene);
    const size = bounds.getSize(new THREE.Vector3());
    const center = bounds.getCenter(new THREE.Vector3());
    const longest = Math.max(size.x, size.y, size.z);
    const holder = new THREE.Group();
    gltf.scene.position.sub(center);
    holder.add(gltf.scene);
    if (longest > 0) holder.scale.setScalar(2 / longest);
    modelSlot.add(holder);
    bar.value = 100;
    message.textContent = '模型加载成功';
  }, (event) => {
    if (current !== attempt) return;
    if (event.lengthComputable && event.total > 0) {
      const percent = Math.round(event.loaded / event.total * 100);
      bar.value = Math.min(percent, 99);
      message.textContent = `文件传输 ${percent}%(仍可能正在解析)`;
    } else {
      bar.removeAttribute('value');
      message.textContent = '正在加载,无法计算字节百分比';
    }
  }, (error) => {
    if (current !== attempt) return;
    bar.removeAttribute('value');
    message.textContent = '模型加载失败,请检查网络或文件路径';
    retry.hidden = false;
    console.error('glTF 加载失败:', error);
  });
}

retry.addEventListener('click', loadModel);
function resize() {
  const width = canvas.clientWidth;
  const height = canvas.clientHeight;
  renderer.setSize(width, height, false);
  camera.aspect = width / height;
  camera.updateProjectionMatrix();
}
window.addEventListener('resize', resize);
resize();
renderer.setAnimationLoop(() => renderer.render(scene, camera));
loadModel();

预期结果:通过开发服务器打开页面后,鸭子模型显示在画布中央,界面最终显示“模型加载成功”,进度条为 100,重试按钮隐藏。控制台可看到资源项完成记录;具体次数取决于模型是否引用外部资源。

启动命令:

bash
npx vite

预期输出包含开发地址,端口以实际值为准:

text
Local: http://localhost:<PORT>/

分清失败分支与恢复路径

缺失主模型、外部纹理请求失败、GLB 内容损坏可能在不同阶段出错:资源级问题由 manager.onError(url) 记录,模型整体是否失败由 GLTFLoader 的 onError(error) 决定。加载面板不应在 manager.onLoad() 时无条件消失,否则失败后也可能闪现“完成”。

glTF 模型加载、错误与重试流程

示例用 attempt 过滤旧回调,避免过时请求覆盖新状态;用变化的查询字符串减少缓存干扰。重试不是保证成功:404 必须先恢复文件,断网必须先恢复连接。真实业务还应限制自动重试次数(例如最多 2 次)、避免 404 的无意义自动重试,并在切换不同模型前清理不再使用的几何体和材质。

验证缺失文件和网络异常

  1. 正常打开 npx vite 输出的本地地址,确认模型、成功提示、100% 进度条均出现。浏览器开发者工具中的 Network 应能找到 /models/Duck.glb 请求。
  2. 将 public/models/Duck.glb 临时改名为 Duck.glb.bak,刷新页面。预期看到失败提示、重试按钮,Network 中模型请求通常显示 404。恢复原文件名并点击重试,预期重新显示模型。
  3. 保持页面已经加载完成的状态,先制造一次 404 使重试按钮出现,然后在开发者工具 Network → Offline 下点击重试。预期请求显示网络错误而不是 HTTP 404,失败提示仍然可见。关闭 Offline、恢复文件后再次重试,预期成功。
  4. 需要排查 .gltf 时,除了主文件,还应逐项检查其引用的 .bin、图片路径、大小写和跨域响应;仅凭主文件返回 200 不能认定模型已经就绪。

这样,状态面板由模型级回调决定成败,资源管理器负责提供逐项线索;当用户报告“卡在 100%”或“模型消失”时,能先辨认传输、解析和路径故障,再选择正确的重试或修复方式。

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

目录与阅读设置

阅读设置

17

记录一个想法

模型加载进度与错误如何处理

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

登录哪都通