npx gltf-transform 详细使用说明

gltf-transform 是一个专为处理 glTF 2.0 格式3D模型的 JavaScript/TypeScript SDK，支持在 Web 和 Node.js 环境中使用。它提供了命令行界面（CLI），可以快速对 GLB/GLTF 文件进行压缩、优化和检查。

1. 安装

使用 npx 可以无需全局安装直接运行：

npx gltf-transform <命令> [参数...] [选项...]

如果需要频繁使用，可以全局安装：

npm install --global @gltf-transform/cli

安装后直接使用：

gltf-transform <命令> [参数...] [选项...]

国内用户注意：如果安装过程中遇到 Sharp 相关错误，可以配置国内镜像源：

npm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
npm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"
npm install --global @gltf-transform/cli

2. 查看帮助

# 查看所有命令
npx gltf-transform --help

# 查看特定命令的帮助
npx gltf-transform optimize --help
npx gltf-transform draco --help

3. 核心功能分类

gltf-transform 提供了丰富的命令，按功能可分为以下几大类：

🔍 检查与验证

命令	用途
inspect	查看模型内容，识别性能瓶颈（几何密集还是纹理密集、绘制调用次数等）
validate	验证模型是否符合 glTF 规范

使用示例：

npx gltf-transform inspect input.glb

📦 整体优化

命令	用途
optimize	一键综合优化，组合多种优化方法
prune	移除未引用的节点、材质、纹理等冗余数据
dedup	去重访问器和纹理
merge	合并多个模型为一个

使用示例：

# 一键综合优化（最常用）
npx gltf-transform optimize input.glb output.glb --compress draco --texture-compress webp

🧊 几何压缩

命令	用途	特点
draco	Google Draco 算法压缩几何数据	压缩率极高，需解码器
meshopt	Meshoptimizer 算法压缩几何、变形目标和动画	解压速度快，无需额外解码器
quantize	量化几何数据，降低精度（如32位→16位）	有损但高效，兼容性好
simplify	简化网格，减少顶点/面数	有损操作，直接改变模型细节
weld	索引几何体，合并相似顶点	无损

使用示例：

# Draco 压缩
npx gltf-transform draco input.glb output.glb

# Meshopt 压缩（推荐，无需解码器）
npx gltf-transform meshopt input.glb output.glb --level medium

# 量化几何（先量化再 Draco 可获得更小体积）
npx gltf-transform quantize input.glb output.glb --qp 14 --qn 10

# 简化几何（减面50%）
npx gltf-transform simplify input.glb output.glb --ratio 0.5

重要提示：如果同时使用 quantize 和 draco，应先执行 quantize 再执行 draco，这样 Draco 可以基于量化后的低精度数据进行更高效的压缩。

🎨 纹理压缩

纹理通常是 GLB 文件中占用空间最大的部分。

命令	用途
webp	转换为 WebP 格式（兼容性好）
avif	转换为 AVIF 格式（压缩率更高）
resize	调整纹理尺寸（如 2048→1024）
uastc	KTX2 + UASTC 压缩（GPU 原生格式，提升性能）
etc1s	KTX2 + ETC1S 压缩（体积更小）

使用示例：

# 压缩纹理为 WebP
npx gltf-transform webp input.glb output.glb

# 调整纹理尺寸
npx gltf-transform resize input.glb output.glb --width 1024 --height 1024

# KTX2 压缩（UASTC 格式，GPU 友好）
npx gltf-transform uastc input.glb output.glb --level 4

⏯️ 动画优化

命令	用途
resample	重采样动画，无损去重关键帧

4. 典型工作流程

方案一：一键优化（快速上手）

npx gltf-transform optimize input.glb output.glb \
  --compress meshopt \
  --texture-compress webp

方案二：分步精细控制（推荐）

每次优化生成一个新文件，便于调试和回滚：

# 第1步：压缩纹理
npx gltf-transform webp input.glb step1.glb

# 第2步：清理冗余数据
npx gltf-transform prune step1.glb step2.glb

# 第3步：几何压缩（Meshopt 不需要解码器）
npx gltf-transform meshopt step2.glb step3.glb

# 第4步（可选）：合并网格减少绘制调用
npx gltf-transform merge step3.glb final.glb

# 查看最终效果
ls -lh input.glb final.glb

方案三：针对几何密集模型的极致压缩

如果模型没有纹理或主要瓶颈在几何体，可以使用量化和 Draco 组合压缩：

# 先量化
npx gltf-transform quantize input.glb step1.glb --qp 14 --qn 10

# 再 Draco 压缩
npx gltf-transform draco step1.glb final.glb

注意：使用 Draco 压缩的文件需要在加载端配置 DRACOLoader 解码器，而 meshopt 压缩在 Babylon.js 5.0+ 和 Three.js r136+ 中已原生支持。

5. 针对节点控制的特殊处理

如果你的模型包含需要通过代码控制的节点（如车轮 wheel_FL、wheel_FR 等），需要注意：

optimize 命令可能会改变节点结构或合并节点，导致代码中通过 getNodeByName() 获取不到对应节点。

推荐分步执行：只运行 webp（纹理压缩）和 draco/meshopt（几何压缩），不执行 optimize，这样可以最大程度保留原始节点结构。

# 只压缩纹理和几何，不改变节点结构
npx gltf-transform webp input.glb step1.glb
npx gltf-transform meshopt step1.glb final.glb

6. 常见问题

6.1 simplify 命令没有效果

如果 simplify 命令执行后顶点数没有变化，通常是因为模型使用了硬法线（hard normals），导致顶点无法共享。可以在简化前移除法线属性：

# 在 gltf.report 的 Script 标签中执行
for (const mesh of document.getRoot().listMeshes()) {
  for (const prim of mesh.listPrimitives()) {
    prim.getAttribute('NORMAL')?.dispose();
  }
}
await document.transform(weld(), simplify({ ratio: 0.5 }));

6.2 使用 Draco 压缩后加载报错

报错 No DRACOLoader instance provided 表示加载端没有配置 Draco 解码器。解决方法：

• 改用 meshopt 压缩（不需要解码器）
• 或在加载端配置 Draco 解码器

6.3 纹理压缩失败

如果 webp 命令报错，可能与 Sharp 库有关。可以尝试使用 resize 调整纹理尺寸作为替代，或检查 Node.js 版本是否兼容。

7. 命令速查表

需求	命令
查看模型信息	npx gltf-transform inspect input.glb
一键综合优化	npx gltf-transform optimize input.glb output.glb --compress meshopt --texture-compress webp
Draco 几何压缩	npx gltf-transform draco input.glb output.glb
Meshopt 几何压缩	npx gltf-transform meshopt input.glb output.glb
量化几何	npx gltf-transform quantize input.glb output.glb --qp 14 --qn 10
WebP 纹理压缩	npx gltf-transform webp input.glb output.glb
调整纹理尺寸	npx gltf-transform resize input.glb output.glb --width 1024 --height 1024
清理冗余数据	npx gltf-transform prune input.glb output.glb
合并网格	npx gltf-transform merge input.glb output.glb
简化几何	npx gltf-transform simplify input.glb output.glb --ratio 0.5