Web 图形与 3D / 系统课时
规范资源目录与版本化引用
规范资源目录与版本化引用
Three.js 模型在开发环境正常加载,部署到子路径后却出现 404,往往是静态资源根路径、构建规则与缓存版本没有统一。本课以 Vite 项目为例,建立 GLB、贴图、解码器和资源清单的目录约定,实现可追踪的版本化加载,并验证构建产物与浏览器实际请求一致。
学习目标
- 区分 Vite 中
public与src资源的构建及引用规则。 - 使用
base和资源清单统一管理模型、贴图与解码器地址。 - 检查生产构建、请求路径与缓存策略,避免部署后资源失效。
规划静态资源目录
Vite 默认提供两种资源管理方式:src 内被导入的资源由构建工具处理,通常生成带内容哈希的文件名;public 中的文件则保持原始名称,构建时原样复制到 dist 根目录。
对于需要由业务数据动态选择、文件名必须保持稳定的模型资源,使用 public 比逐个静态导入更直接。建议采用以下目录约定:
| 项目内路径 | 职责 | 构建后位置 |
|---|---|---|
public/models/v3/robot.glb |
第三版角色模型 | dist/models/v3/robot.glb |
public/textures/v3/robot-basecolor.webp |
独立基础色贴图 | dist/textures/v3/robot-basecolor.webp |
public/decoders/draco/v3/ |
Draco 浏览器解码文件 | dist/decoders/draco/v3/ |
public/resource-manifest.json |
当前资源版本与路径清单 | dist/resource-manifest.json |
src/assets/badge.png |
由源码直接导入的界面图片 | dist/assets/ 内的哈希文件 |
这里的 v3 是示例资源发布版本,不代表 Draco 算法版本。版本目录一经发布就不应覆盖原有文件;修改模型内容时改用 v4,使新旧资源拥有不同 URL。
Draco 解码器需要从项目安装的 Three.js 包中获取。使用支持这些文件的 Three.js 版本时,可以从 node_modules/three/examples/jsm/libs/draco/gltf/ 复制 draco_decoder.js、draco_decoder.wasm 和 draco_wasm_wrapper.js 到规划的解码器目录。不要混用来源不明的解码器文件。
固定部署基路径与资源清单
假设网站部署在 https://example.com/viewer/,模型最终请求地址应为 https://example.com/viewer/models/v3/robot.glb,而不是站点根目录下的 /models/v3/robot.glb。
在项目根目录创建或修改 vite.config.js:
import { defineConfig } from 'vite';
export default defineConfig({
// 与实际部署的 URL 前缀保持一致
base: '/viewer/'
});这里设置的是 URL 前缀,不会在 dist 中额外创建 viewer 文件夹。部署时应将 dist 的内容映射到服务器的 /viewer/ 路径下;如果网站部署在域名根目录,则改为 base: '/'。
Vite 会自动修正源码导入的资源 URL,但不会自动识别和重写 JavaScript 在运行时随意拼接的字符串。动态资源地址应使用 import.meta.env.BASE_URL 取得实际构建基路径。
接着创建 public/resource-manifest.json:
{
"version": "v3",
"model": "models/v3/robot.glb",
"texture": "textures/v3/robot-basecolor.webp",
"dracoDir": "decoders/draco/v3/"
}清单里的路径统一采用相对于部署基路径的写法:不以 / 开头,不带 public/,也不重复填写 /viewer/。这样切换测试环境或生产环境时,只需调整 Vite 的 base 并重新构建,不必逐项修改清单。

使用清单统一加载资源
下面示例适用于已经安装 three 的 Vite 工程。先准备真实的 robot.glb、robot-basecolor.webp 和前面列出的 Draco 解码文件,再将代码放入项目的 src/main.js,并确保入口 HTML 引用了该模块。
import { SRGBColorSpace, TextureLoader } from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
const base = import.meta.env.BASE_URL;
async function checkResources() {
// 清单可能更新,读取时要求浏览器重新验证缓存
const response = await fetch(`${base}resource-manifest.json`, {
cache: 'no-cache'
});
if (!response.ok) {
throw new Error(`manifest HTTP ${response.status}`);
}
const manifest = await response.json();
const draco = new DRACOLoader();
draco.setDecoderPath(`${base}${manifest.dracoDir}`);
const loader = new GLTFLoader();
loader.setDRACOLoader(draco);
loader.setMeshoptDecoder(MeshoptDecoder);
try {
// 所有 public 资源均从同一个 base 计算 URL
const gltf = await loader.loadAsync(`${base}${manifest.model}`);
const texture = await new TextureLoader().loadAsync(
`${base}${manifest.texture}`
);
texture.colorSpace = SRGBColorSpace;
console.log(
`${manifest.version}: model=${Boolean(gltf.scene)}, texture=${texture.isTexture}`
);
// 本例仅验证资源可加载,实际渲染时应继续使用它们
texture.dispose();
} finally {
draco.dispose();
}
}
checkResources().catch(console.error);当示例文件有效且请求全部成功时,浏览器控制台的预期输出为:
v3: model=true, texture=true本例独立加载贴图用于检查资源路径,没有把它重新设置到 GLB 材质上。实际项目如果已经在 GLB 内嵌相同贴图,应删除这次额外加载,避免重复占用内存。角色最终还需要添加到场景并由渲染循环显示。
GLTFLoader 只有遇到 KHR_draco_mesh_compression 扩展时才需要调用外部 Draco 解码器;对于 EXT_meshopt_compression,这里使用的 MeshoptDecoder 通过模块导入并随应用代码构建,不需要再单独规划一个公共 Meshopt 解码器目录。如果资产使用 KTX2 压缩贴图,还需要额外配置 KTX2Loader 和对应转码器,本示例的普通 WebP 贴图不需要该步骤。
检查构建产物与实际请求
资源目录正确不代表部署路径一定正确。验收应分别检查磁盘产物、浏览器请求和模型解析,避免只看到页面正常打开便认定资源已经部署成功。
在已配置 build 脚本的 Vite 项目根目录执行以下 Bash 命令:
npm run build &&
test -f dist/resource-manifest.json &&
test -f dist/models/v3/robot.glb &&
test -f dist/textures/v3/robot-basecolor.webp &&
test -f dist/decoders/draco/v3/draco_decoder.wasm &&
echo '静态资源检查通过'所有文件存在且构建成功时,构建日志的末行预期输出为:
静态资源检查通过如果命令没有打印这行文字,先检查缺失文件的源路径和构建错误。特别注意:public/models/v3/robot.glb 在构建后对应 dist/models/v3/robot.glb,不是 dist/public/models/v3/robot.glb。
接下来运行 npm run preview -- --port 4173,在浏览器访问 http://localhost:4173/viewer/,打开开发者工具的 Network 面板并刷新页面。端口被占用时可换用其他端口,以下地址也要相应调整。
重点检查以下请求:
| 请求路径 | 正确结果 |
|---|---|
/viewer/resource-manifest.json |
HTTP 200,响应体为清单 JSON |
/viewer/models/v3/robot.glb |
HTTP 200,响应为实际 GLB 二进制内容 |
/viewer/textures/v3/robot-basecolor.webp |
HTTP 200,响应为图片内容 |
/viewer/decoders/draco/v3/draco_decoder.wasm |
使用 Draco WASM 解码时 HTTP 200 |
如果模型返回 200 却无法解析,检查响应内容是否实际为 GLB。单页应用服务器可能把不存在的模型路径回退到 index.html,造成状态码看似正确、内容实际为 HTML 的问题。应检查 Network 的响应内容以及 Console 的解析异常,而不能只依据状态码判断。
Draco 解码文件只有在对应压缩模型触发解码时才会进入 Network 请求列表;没有看到该请求不一定是故障。对于压缩模型,应进一步确认模型加载成功、解码文件响应正常且控制台没有解码错误。
配置缓存并安全发布新版本
资源文件通常体积较大,合理缓存能减少重复下载。但清单与模型不能简单使用相同缓存策略,否则版本切换时容易出现旧清单指向已删除文件,或者新页面继续使用旧模型的问题。
建议在静态服务器或 CDN 上按路径设置以下 HTTP 响应头:
| 资源范围 | 建议 Cache-Control | 原因 |
|---|---|---|
/viewer/index.html |
no-cache |
每次使用前可重新验证入口内容 |
/viewer/resource-manifest.json |
no-cache |
可缓存,但使用前应重新验证当前版本 |
/viewer/models/v3/ |
public, max-age=31536000, immutable |
已发布的版本内容保持不变 |
/viewer/textures/v3/ |
public, max-age=31536000, immutable |
同一 URL 的贴图不再覆盖 |
/viewer/decoders/draco/v3/ |
public, max-age=31536000, immutable |
固定版本的解码资源可重复利用 |
以上都是服务器响应头配置建议,不是在 Vite 的 vite.config.js 中直接填写的属性。具体应配置在 Nginx、对象存储或 CDN 的响应规则中,并通过浏览器 Network 面板检查实际返回的 Cache-Control。
假设要将机器人模型从 v3 更新到 v4,正确发布顺序为:
- 创建
public/models/v4/和需要更新的贴图目录,生成新文件,不覆盖 v3。 - 先把 v4 资源上传并确认 HTTP 请求可用,必要时同步更新解码资源。
- 将
resource-manifest.json的version与对应路径改为 v4,再发布新清单及应用版本。 - 保留旧版资源一段兼容期,例如 7 天,并根据实际缓存时长、活跃会话与回滚需求延长保留时间。
- 在正式环境刷新并验证请求确实落到 v4;回滚时恢复清单引用,确认旧资源仍可访问。
不要仅在 URL 后添加 ?v=4 就认为缓存问题已经解决。如果 CDN 或代理没有按预期处理查询参数,仍可能返回旧内容。使用独立版本路径能够更明确地区分资源对象。
还应避免发布期间先删除旧版目录,再上传新资源。旧页面、未结束的会话和缓存中的旧清单仍可能引用 v3,提前清理会导致间歇性 404。
最终验收标准是:dist 内资源齐全,所有运行时地址都正确包含部署基路径,清单和实际加载版本一致,压缩模型可以正常解码,更新版本后 URL 随之变化,并且历史版本不会因新版本发布而立即失效。