Web 图形与 3D / 系统课时
DRACOLoader 怎样解码压缩网格
DRACOLoader 怎样解码压缩网格
Draco 压缩后的 glTF 能减小网格传输体积,却不能直接交给渲染器。本篇用 Vite 和 Three.js 加载一份含 Draco 网格的 GLB,配置解码器资源,验证模型显示,并用网络请求排查路径与解码错误。
学习目标
- 说清
GLTFLoader、DRACOLoader与 Draco 解码器文件的分工。 - 在 Vite 项目中正确部署解码器并加载压缩 GLB。
- 从 Network 和 Console 区分模型路径错误、解码器缺失与格式问题。
Draco 与 glTF 的职责
Draco 负责压缩顶点位置、法线、索引等几何数据,不负责材质、贴图或场景层级。glTF 使用 KHR_draco_mesh_compression 扩展指出哪些网格图元含有压缩数据;扩展可出现在 .gltf 或 .glb 中,文件后缀本身不能证明用了 Draco。
GLTFLoader 先解析 glTF 容器,再把相应图元的压缩数据交给 DRACOLoader。后者通过 Worker 调用 JS 或 WASM 解码器,生成 BufferGeometry,再由 glTF 加载流程与材质和节点组合成可渲染场景。只用 DRACOLoader.loadAsync() 直接加载的是独立 .drc 几何文件,不是整套 glTF 场景。

准备解码器与压缩模型
以下示例适用于 Node.js 22.12+、Vite 和 Three.js 0.180.0;终端命令适用于 macOS、Linux 或 Git Bash。先创建项目,将 同版本 three 包自带的 glTF 专用解码器复制到 Vite 的 public/draco/,并下载 Three.js 示例里的 Draco 压缩模型。
npm create vite@latest draco-view -- --template vanilla
cd draco-view
npm install
npm install three@0.180.0
mkdir -p public/draco public/models
cp node_modules/three/examples/jsm/libs/draco/gltf/draco_decoder.js node_modules/three/examples/jsm/libs/draco/gltf/draco_wasm_wrapper.js node_modules/three/examples/jsm/libs/draco/gltf/draco_decoder.wasm public/draco/
curl -fL https://raw.githubusercontent.com/mrdoob/three.js/r180/examples/models/gltf/LittlestTokyo.glb -o public/models/LittlestTokyo.glb预期结果:public/draco/ 中有 draco_decoder.js、draco_wasm_wrapper.js、draco_decoder.wasm,public/models/ 中有 LittlestTokyo.glb。下载失败时先确认网络可访问原文件,再继续;该模型是 Three.js 官方示例引用的第三方素材,公开使用应保留原作者署名。
public/ 下的文件按站点静态资源发布,URL 不包含 public 字样;setDecoderPath() 要指向解码器目录 URL,并保留末尾 /,不能填写 node_modules 的磁盘路径。
配置加载与显示
将 Vite 自动生成的 src/main.js 完整替换为下面的代码。先注册 Draco,再调用 GLTFLoader.loadAsync();import.meta.env.BASE_URL 使静态资源路径也适用于部署在子目录的站点。
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
document.body.style.margin = '0';
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
document.querySelector('#app').replaceChildren(renderer.domElement);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xeaf0f3);
scene.add(new THREE.HemisphereLight(0xffffff, 0x445566, 3));
const camera = new THREE.PerspectiveCamera(
50, window.innerWidth / window.innerHeight, 0.1, 1000
);
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
const draco = new DRACOLoader();
draco.setDecoderPath(`${import.meta.env.BASE_URL}draco/`);
draco.setWorkerLimit(2); // 限制并发解码 Worker 的数量
const loader = new GLTFLoader();
loader.setDRACOLoader(draco); // 必须在开始加载压缩图元前注册
try {
const gltf = await loader.loadAsync(
`${import.meta.env.BASE_URL}models/LittlestTokyo.glb`
);
const model = gltf.scene;
const box = new THREE.Box3().setFromObject(model);
const center = box.getCenter(new THREE.Vector3());
const distance = box.getSize(new THREE.Vector3()).length();
model.position.sub(center); // 以模型包围盒中心作为观察目标
scene.add(model);
camera.position.set(distance, distance * 0.7, distance);
camera.near = Math.max(0.01, distance / 1000);
camera.far = Math.max(100, distance * 10);
camera.updateProjectionMatrix();
controls.update();
console.info('Draco 模型加载成功');
} catch (error) {
console.error('模型或解码器加载失败:', error);
}
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});
renderer.setAnimationLoop(() => {
controls.update();
renderer.render(scene, camera);
});预期结果:浏览器显示可拖动旋转的城市模型;开发者工具 Console 出现 Draco 模型加载成功。包围盒计算仅用于把示例模型放到视野中心,不属于 Draco 解码步骤。
运行与检查请求
在项目目录启动 Vite:
npm run dev预期结果:终端给出可访问的本地开发地址(端口以实际显示为准)。打开页面后,按 F12 查看 Network,启用 Disable cache 并刷新页面,依次核对:
LittlestTokyo.glb返回 200,响应不是 HTML 错误页。- 支持 WebAssembly 的浏览器能请求到
draco_wasm_wrapper.js和draco_decoder.wasm;不支持时可能回退到draco_decoder.js。相关资源应成功返回,而不是 404。 - Console 输出成功信息,画布显示网格;仅有资源 200 不代表解码或渲染已完成。
按请求定位故障
| 现象 | 先检查什么 | 修复方式 |
|---|---|---|
.glb 返回 404 |
模型 URL、大小写以及 public/models/ 位置 |
使用 ${import.meta.env.BASE_URL}models/LittlestTokyo.glb 对应的发布路径 |
.wasm 或包装脚本返回 404 |
setDecoderPath() 与 public/draco/ 文件名 |
补齐三个解码器文件,目录 URL 以 / 结尾 |
脚本解析报 Unexpected token '<' 或 MIME 错误 |
Network → Response 是否实际返回了 index.html |
修正路径及静态服务器回退规则,确保返回真正的 JS/WASM |
| 提示缺少 DRACOLoader 实例 | setDRACOLoader() 是否先于 loadAsync() |
在开始解析 glTF 前完成注册 |
| 请求均正常却解码失败 | 模型是否损坏,扩展是否确为 Draco,Console 是否显示 Worker 错误 | 换官方示例模型做对照,再检查导出与压缩链路 |
不要通过删除 KHR_draco_mesh_compression 声明来“绕过”解码:当网格没有未压缩的备用数据时,这只会让文件无法正确解析。生产项目应复用一份 Draco 加载器;在应用退出、确认不再解码时调用 draco.dispose() 释放 Worker,并避免再次使用已释放的实例。