Web 图形与 3D / 系统课时

用 glTF Validator 校验资产

用 glTF Validator 校验资产

模型在建模软件中正常显示,不代表它符合 glTF 2.0 规范,也不保证 Three.js 能正确加载。这里用 Khronos glTF Validator 检查结构、扩展与外部资源,再用独立查看器核对材质和动画,把“能打开”转为可复核的资产验收结论。

学习目标

  • 使用在线 Validator 识别结构、引用和扩展问题。
  • 读懂错误、警告、提示与具体字段位置,并用 Node.js 检查外部资源。
  • 联合独立查看器,制定模型入库的通过条件。

准备资产并运行在线校验

先固定交付目录:例如 models/chair/chair.gltf 通过相对 URI 引用同目录的 chair.bin 和 textures/basecolor.png。文件名大小写须与 JSON 中的 uri 一致;Windows 本机能加载,不代表区分大小写的部署服务器也能加载。.glb 通常把二进制数据打包在单个容器中,但仍应检查是否存在外部引用。

  1. 打开 Khronos glTF Validator。
  2. 选择或拖入 chair.glb,等待结果。网页在浏览器本地执行校验,不会上传模型到服务端。
  3. 查看 Errors、Warnings、Infos 和各项详情;.gltf 如果引用外部 .bin、图片而网页无法读取,应使用下文的本地校验,不要把“资源未加载”误判为模型本身缺失。

Validator 能检查 JSON/GLB 格式、索引与缓冲区边界、部分动画数据和它已实现的扩展规则;它不负责确认最终灯光和材质观感。

按严重程度处理报告

报告级别 典型信号 处理动作
Error(severity=0) UNRESOLVED_REFERENCE、UNDECLARED_EXTENSION 阻断交付,先修引用或扩展声明
Warning(severity=1) NON_RELATIVE_URI、MESH_PRIMITIVE_NO_POSITION 检查跨环境加载与网格用途,记录是否可接受
Info(severity=2) UNSUPPORTED_EXTENSION、UNUSED_OBJECT 不等于运行时支持;确认加载器能力并判断是否清理
Hint(severity=3) BUFFER_VIEW_TARGET_MISSING 作为优化建议处理

每条问题通常有 code、message 和 JSON Pointer,例如 /meshes/0/primitives/0 指向第一个网格的第一个图元;部分 GLB 问题给出字节 offset。按位置找到导出来源修复,比直接手改复杂的索引或缓冲区安全。extensionsRequired 列出的扩展必须由目标加载器支持,不能仅凭 Validator 没报错就放行。具体问题代码可查阅 官方问题列表。

规范检查与可视验收双通道流程

使用 Node.js 验证外部文件

已有 Node.js 18 或更高版本的工程,可安装官方 npm 包,把 .gltf 所引用的 .bin 和图片按模型文件位置一并读取。

bash
npm install --save-dev gltf-validator

预期结果:依赖出现在 package.json 的 devDependencies 中,安装命令退出码为 0;安装日志与实际版本可能不同。

在工程根目录保存 validate.cjs:

js
const fs = require('node:fs/promises');
const path = require('node:path');
const validator = require('gltf-validator');

const input = process.argv[2];
if (!input) {
  console.error('用法: node validate.cjs <模型路径>');
  process.exit(2);
}

const file = path.resolve(input);
(async () => {
  const bytes = new Uint8Array(await fs.readFile(file));
  const report = await validator.validateBytes(bytes, {
    uri: path.basename(file),
    maxIssues: 1000,
    // 依据模型所在目录读取 glTF 的外部 buffer / image URI。
    externalResourceFunction: async (uri) => {
      const target = path.resolve(path.dirname(file), decodeURIComponent(uri));
      return new Uint8Array(await fs.readFile(target));
    }
  });

  const issues = report.issues;
  console.log(`Errors=${issues.numErrors} Warnings=${issues.numWarnings} Infos=${issues.numInfos}`);
  for (const item of issues.messages) {
    console.log(`${item.severity} ${item.code} @ ${item.pointer ?? `byte:${item.offset}`}`);
  }
  if (issues.truncated) console.error('报告被截断,需增大 maxIssues 后重检');
  process.exitCode = issues.numErrors || issues.truncated ? 1 : 0;
})().catch((error) => {
  console.error(error.message);
  process.exitCode = 2;
});

对实际文件运行:

bash
node validate.cjs ./models/chair/chair.gltf

预期输出(仅当模型没有任何报告项时):

text
Errors=0 Warnings=0 Infos=0

实际数量与问题行取决于资产;有 Error 或报告被截断时进程退出码为 1,读取文件或解析异常时为 2。此脚本面向本地交付包中的文件引用;如果使用远程 URL,必须另行实现对应的资源读取策略。不要为了让输出归零而关闭外部资源检查或忽略全部错误。

用独立查看器确认能正确显示

打开 Khronos glTF Sample Viewer,优先拖入已验过的 .glb;多文件 .gltf 应保证查看器能访问相对资源。按下面清单观察:

  1. 旋转并缩放:模型正反面都可见,没有反面消失、异常拉伸或明显破面。
  2. 切换环境光或观察角度:基础色、法线、金属度与粗糙度表现符合美术验收图。
  3. 若有动画,打开 Animations 播放每个剪辑,检查起点、中段与末帧的骨骼、位移和循环衔接。
  4. 用课程项目实际采用的 Three.js GLTFLoader 再加载一次,确认要求的扩展(例如 Draco、KTX2)已配好相应解码器或加载器。

交付门槛建议定为:Error 为 0、报告未截断、全部 Warning 有处理结论、必需扩展被目标运行时支持、独立查看器与目标页面视觉验收通过。保存验证报告、模型版本及人工复核记录;规范通过与可视通过缺一不可。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 glTF Validator 校验资产

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

登录哪都通