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:

bash
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,移除模板默认的画布外边距和宽度限制:

css
html, body, #app {
  width: 100%;
  height: 100%;
  margin: 0;
  overflow: hidden;
}
canvas { display: block; }

这些样式使渲染画布铺满视口。然后用下面的完整内容替换 src/main.js,自动框住模型并允许拖动观察:

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 定义;其余加载逻辑不变:

js
import modelUrl from './assets/model.glb?url';
const url = modelUrl;

此片段依赖上面的 Three.js 场景和加载代码,不能独立执行。特别注意:如果只导入一个 .gltf?url,Vite 不会自动发现 JSON 内字符串引用的所有外部图片和 .bin 文件,建议把这类完整文件组放在 public。

Vite 中 public 与 src 模型文件的请求及构建路径对比

验证请求与构建结果

  1. 打开开发页面,按 F12 进入 DevTools,切到 Network,勾选 Disable cache 后刷新,筛选 model.glb。
  2. 检查 Request URL 是否为当前站点下的 /models/model.glb,状态是否为 200;再核对 Response 是否是 GLB 二进制内容,而非 index.html。Vite 的单页应用回退可能使错误路径也返回 200 和 HTML。
  3. 查看 Console 是否打印 已加载:;若请求 404,检查文件大小写与目录;若返回 HTML 或提示解析错误,重点排查 URL;若请求成功却看不到模型,检查是否有实际网格及解码扩展。

如果将网站部署在 /showroom/ 而不是站点根目录,可在项目根目录新建 vite.config.js,指定 Vite 的发布基础路径;部署到站点根目录时无需此配置:

js
import { defineConfig } from 'vite';
export default defineConfig({ base: '/showroom/' });

配置生效后,import.meta.env.BASE_URL 会让模型请求使用 /showroom/models/model.glb。最后执行构建与本地预览:

bash
npm run build
npm run preview

预期结果:构建成功后存在 dist/models/model.glb,终端出现预览站点地址;按该地址访问页面并在 Network 中复查请求。发布到子路径时还需让服务器实际托管对应的 /showroom/ 目录,只有设置 base 而未正确部署文件仍会返回 404。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Vite 提供模型静态资源

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

登录哪都通