Web 图形与 3D / 系统课时
用 Vite 提供模型静态资源
用 Vite 提供模型静态资源
本篇用 Vite 建立 Three.js 模型展示页,将 GLB 放入静态目录并完成加载。你会在浏览器 Network 面板验证文件响应,弄清 public 与 src 两种资源路径的处理差异,避免部署后出现模型 404。
学习目标
- 建立 Vite + Three.js 工程,正确放置
model.glb。 - 使用
GLTFLoader加载模型并检查浏览器请求。 - 区分
public原样复制与src模块化导入的资源路径。
创建展示工程
准备 Node.js 20.19+、22.12+ 或更新的受支持版本,以及一个包含可见网格的 glTF 2.0 二进制模型。下面使用 Vite 的原生 JavaScript 模板,命令适用于 npm:
node --version
npm create vite@latest three-model-demo -- --template vanilla
cd three-model-demo
npm install
npm install three
npm run dev预期结果:终端显示 Local: http://localhost:<PORT>/ 一类的地址,浏览器打开后看到 Vite 初始页面。<PORT> 为实际监听端口,通常从 5173 开始,端口占用时可能变化;开发服务器保持运行。
把模型放入静态目录
在项目根目录的 public 下创建 models 文件夹,将真实的 GLB 文件放为 public/models/model.glb。如果从 Blender 导出,可在“文件 > 导出 > glTF 2.0”中选择 glTF Binary (.glb)。本例先使用不依赖 Draco、Meshopt 或 KTX2 额外解码器的模型。
Vite 会把 public 下的文件按原名从站点根路径提供服务:文件系统里的 public/models/model.glb 对应开发时的 /models/model.glb,请求 URL 不包含 public。正式构建时文件原样复制到 dist/models/model.glb,不会被自动改成哈希文件名。
先直接访问开发服务器的 /models/model.glb 地址。浏览器可能下载二进制文件,这是正常现象;如果打开的是项目 HTML 页面,就要先核对文件名、大小写及目录层级。
加载并在页面显示模型
保留模板的 index.html,其中已有 #app 和 src/main.js 入口。先用以下完整内容覆盖 src/style.css,移除模板默认的画布外边距和宽度限制:
html, body, #app {
width: 100%;
height: 100%;
margin: 0;
overflow: hidden;
}
canvas { display: block; }这些样式使渲染画布铺满视口。然后用下面的完整内容替换 src/main.js,自动框住模型并允许拖动观察:
import './style.css';
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf3f5f8);
const camera = new THREE.PerspectiveCamera(45, 1, 0.01, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
document.querySelector('#app').replaceChildren(renderer.domElement);
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
scene.add(new THREE.HemisphereLight(0xffffff, 0x888888, 2));
const sun = new THREE.DirectionalLight(0xffffff, 2);
sun.position.set(4, 6, 8);
scene.add(sun);
function resize() {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
}
window.addEventListener('resize', resize);
resize();
// BASE_URL 兼容网站部署在 /showroom/ 等子路径的情况。
const url = `${import.meta.env.BASE_URL}models/model.glb`;
try {
const gltf = await new GLTFLoader().loadAsync(url);
scene.add(gltf.scene);
// 根据模型边界计算相机距离,避免只看到模型局部。
const bounds = new THREE.Box3().setFromObject(gltf.scene);
if (bounds.isEmpty()) throw new Error('模型不包含可见网格');
const center = bounds.getCenter(new THREE.Vector3());
const radius = bounds.getBoundingSphere(new THREE.Sphere()).radius;
const halfV = THREE.MathUtils.degToRad(camera.fov) / 2;
const halfH = Math.atan(Math.tan(halfV) * camera.aspect);
const distance = Math.max(radius / Math.sin(Math.min(halfV, halfH)), 1);
camera.position.copy(center).add(
new THREE.Vector3(distance * 0.2, distance * 0.1, distance * 1.25)
);
camera.near = Math.max(distance / 1000, 0.001);
camera.far = Math.max(distance * 10, 100);
camera.updateProjectionMatrix();
controls.target.copy(center);
controls.update();
console.log('已加载:', url);
} catch (error) {
console.error('模型加载失败:', error);
}
// 控制器的阻尼需要每帧更新。
renderer.setAnimationLoop(() => {
controls.update();
renderer.render(scene, camera);
});预期结果:开发页面变为浅灰色全屏画布,模型出现在视野内,可拖动旋转;控制台打印 已加载: /models/model.glb。如果 GLB 使用了尚未注册的压缩扩展,需额外配置对应解码器,本例不覆盖该情形。
区分 public 与模块化导入
public 适合保持固定文件名、由后端配置或用户数据拼接 URL 的模型,以及引用外部 .bin 和贴图的多文件 .gltf。src 则适合由源代码明确引用、希望参与 Vite 构建资源处理的单文件 GLB。两条路径不能混用:
| 资源所在位置 | 代码里的访问方式 | 构建行为 |
|---|---|---|
public/models/model.glb |
import.meta.env.BASE_URL + 'models/model.glb' |
原样复制到 dist/models/ |
src/assets/model.glb |
import modelUrl from './assets/model.glb?url' |
由构建处理,通常生成带哈希的资源 URL |
片段示例:如果改用 src/assets/model.glb,在原 src/main.js 的 import 区加入第一行,并用第二行替换原来的 const url 定义;其余加载逻辑不变:
import modelUrl from './assets/model.glb?url';
const url = modelUrl;此片段依赖上面的 Three.js 场景和加载代码,不能独立执行。特别注意:如果只导入一个 .gltf?url,Vite 不会自动发现 JSON 内字符串引用的所有外部图片和 .bin 文件,建议把这类完整文件组放在 public。

验证请求与构建结果
- 打开开发页面,按
F12进入 DevTools,切到 Network,勾选 Disable cache 后刷新,筛选model.glb。 - 检查 Request URL 是否为当前站点下的
/models/model.glb,状态是否为200;再核对 Response 是否是 GLB 二进制内容,而非index.html。Vite 的单页应用回退可能使错误路径也返回200和 HTML。 - 查看 Console 是否打印
已加载:;若请求404,检查文件大小写与目录;若返回 HTML 或提示解析错误,重点排查 URL;若请求成功却看不到模型,检查是否有实际网格及解码扩展。
如果将网站部署在 /showroom/ 而不是站点根目录,可在项目根目录新建 vite.config.js,指定 Vite 的发布基础路径;部署到站点根目录时无需此配置:
import { defineConfig } from 'vite';
export default defineConfig({ base: '/showroom/' });配置生效后,import.meta.env.BASE_URL 会让模型请求使用 /showroom/models/model.glb。最后执行构建与本地预览:
npm run build
npm run preview预期结果:构建成功后存在 dist/models/model.glb,终端出现预览站点地址;按该地址访问页面并在 Network 中复查请求。发布到子路径时还需让服务器实际托管对应的 /showroom/ 目录,只有设置 base 而未正确部署文件仍会返回 404。