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:

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:

json
{
  "version": "v3",
  "model": "models/v3/robot.glb",
  "texture": "textures/v3/robot-basecolor.webp",
  "dracoDir": "decoders/draco/v3/"
}

清单里的路径统一采用相对于部署基路径的写法:不以 / 开头,不带 public/,也不重复填写 /viewer/。这样切换测试环境或生产环境时,只需调整 Vite 的 base 并重新构建,不必逐项修改清单。

Vite 资源目录、构建产物和部署基路径的映射关系

使用清单统一加载资源

下面示例适用于已经安装 three 的 Vite 工程。先准备真实的 robot.glb、robot-basecolor.webp 和前面列出的 Draco 解码文件,再将代码放入项目的 src/main.js,并确保入口 HTML 引用了该模块。

js
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);

当示例文件有效且请求全部成功时,浏览器控制台的预期输出为:

text
v3: model=true, texture=true

本例独立加载贴图用于检查资源路径,没有把它重新设置到 GLB 材质上。实际项目如果已经在 GLB 内嵌相同贴图,应删除这次额外加载,避免重复占用内存。角色最终还需要添加到场景并由渲染循环显示。

GLTFLoader 只有遇到 KHR_draco_mesh_compression 扩展时才需要调用外部 Draco 解码器;对于 EXT_meshopt_compression,这里使用的 MeshoptDecoder 通过模块导入并随应用代码构建,不需要再单独规划一个公共 Meshopt 解码器目录。如果资产使用 KTX2 压缩贴图,还需要额外配置 KTX2Loader 和对应转码器,本示例的普通 WebP 贴图不需要该步骤。

检查构建产物与实际请求

资源目录正确不代表部署路径一定正确。验收应分别检查磁盘产物、浏览器请求和模型解析,避免只看到页面正常打开便认定资源已经部署成功。

在已配置 build 脚本的 Vite 项目根目录执行以下 Bash 命令:

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 '静态资源检查通过'

所有文件存在且构建成功时,构建日志的末行预期输出为:

text
静态资源检查通过

如果命令没有打印这行文字,先检查缺失文件的源路径和构建错误。特别注意: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,正确发布顺序为:

  1. 创建 public/models/v4/ 和需要更新的贴图目录,生成新文件,不覆盖 v3。
  2. 先把 v4 资源上传并确认 HTTP 请求可用,必要时同步更新解码资源。
  3. 将 resource-manifest.json 的 version 与对应路径改为 v4,再发布新清单及应用版本。
  4. 保留旧版资源一段兼容期,例如 7 天,并根据实际缓存时长、活跃会话与回滚需求延长保留时间。
  5. 在正式环境刷新并验证请求确实落到 v4;回滚时恢复清单引用,确认旧资源仍可访问。

不要仅在 URL 后添加 ?v=4 就认为缓存问题已经解决。如果 CDN 或代理没有按预期处理查询参数,仍可能返回旧内容。使用独立版本路径能够更明确地区分资源对象。

还应避免发布期间先删除旧版目录,再上传新资源。旧页面、未结束的会话和缓存中的旧清单仍可能引用 v3,提前清理会导致间歇性 404。

最终验收标准是:dist 内资源齐全,所有运行时地址都正确包含部署基路径,清单和实际加载版本一致,压缩模型可以正常解码,更新版本后 URL 随之变化,并且历史版本不会因新版本发布而立即失效。

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

目录与阅读设置

阅读设置

17

记录一个想法

规范资源目录与版本化引用

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

登录哪都通